Manage prepaid account balances

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

To manage the balance in a prepaid account, you can:

• View the current prepaid account balance. See Viewing prepaid account balances using the API.
• Reload (add money to) the account balance as required using a third-party payment provider, such as Worldpay. See Managing prepaid balances using a third-party payment provider.

  Alternatively, you can manage the reload by tracking payments manually or via an integrated billing system and then calling the monetization API to reload the account, as described in Managing prepaid balances manually.

• Set up automatic reload when a prepaid account balance drops below a certain threshold using the monetization API and a third-party payment provider, such as Worldpay. This option is useful to manage recurring payments for rate plans. For information, see Setting up automatic reload of prepaid account balances using the API.

How do I calculate the remaining prepaid account balance?

When viewing the prepaid account balance for a developer or company, as described in the following sections, you need to obtain the following values from the response:

• amount: Total amount of money available for the current billing period. This value is updated when you reload the prepaid account using the methods described in this section.
• usage: Total amount of money used during the current billing period. This value is updated with each qualified monetized transaction or by issuing a credit (positive or negative).

You can calculate the remaining prepaid account balance for the current billing period by subtracting the usage value from the amount value. For example, if the amount value is 335.50 and the usage value is 34, the remaining balance would be calculated as follows:

amount(335.50) - usage(34) = 229.50

Viewing prepaid account balances using the API

The following sections describe how to view prepaid account balances for a developer or company using the API.

Viewing prepaid account balances for a developer

To view prepaid account balances for a developer, issue a GET request to one of the following APIs, where {developer_id} is the email address of the developer:

• /mint/organizations/{org_name}/developers/{developer_id}/developer-balances: Returns prepaid account balance and recurring setup information for a developer.
• /mint/organizations/{org_name}/developers/{developer_id}/prepaid-developer-balances: Returns prepaid account balance information including current and total balance, usage, top ups, and usage tax.

You can pass the following query parameters to filter the results:

For example:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/{developer_id}/developer-balances" \
-u email:password

The following provides an example of the response:

{
    "developerBalance": [
        {
            "amount": 2005,
            "chargePerUsage": false,
            "id": "your-provider-id",
            "isRecurring": false,
            "supportedCurrency": {
                "description": "United States Dollars",
                "displayName": "United States Dollars",
                "id": "usd",
                "name": "USD",
                "organization": {
                    "address": [
                        {
                            "address1": "10 Almaden Blvd.",
                            "city": "San Jose",
                            "country": "US",
                            "id": "32e808d8-3a3c-4d76-a0ae-17d70a982c61",
                            "isPrimary": true,
                            "state": "CA",
                            "zip": "95113"
                        }
                    ],
                    "approveTrusted": false,
                    "approveUntrusted": false,
                    "billingCycle": "CALENDAR_MONTH",
                    "country": "US",
                    "currency": "USD",
                    "description": "my-org",
                    "groupOrganization": false,
                    "hasBillingAdjustment": false,
                    "hasBroker": false,
                    "hasSelfBilling": false,
                    "hasSeparateInvoiceForProduct": false,
                    "id": "my-org",
                    "issueNettingStmt": false,
                    "name": "my-org",
                    "nettingStmtPerCurrency": false,
                    "selfBillingAsExchOrg": false,
                    "selfBillingForAllDev": false,
                    "separateInvoiceForFees": false,
                    "status": "ACTIVE",
                    "supportedBillingType": "BOTH",
                    "taxModel": "HYBRID",
                    "timezone": "UTC"
                },
                "status": "ACTIVE",
                "virtualCurrency": false
            },
            "usage": 2.1572
        }
    ],
    "totalRecords": 1
}

Viewing prepaid account balances for a company

To view prepaid account balances for a company, issue a GET request to /mint/organizations/{org_name}/companies/{company_id}/developer-balances, where {company_id} is the ID of the company. If the company is prepaid, the request retrieves the current prepaid account balance. If the company is postpaid, the request retrieves the current credit limit.

You can pass the following query parameters to filter the results:

For example:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/companies/{company_id}/developer-balances" \
-u email:password

The response is similar to the response shown above, when viewing prepaid account balances for a developer.

Managing prepaid account balances using a payment provider

Manage prepaid account balances by setting up a merchant account with a third-party payment provider, such as Worldpay. The following figure shows how prepaid account balance are managed using the Worldpay payment provider.

The following table describes each step in the prepaid account balance management flow, shown above.

{
    "isRecurring": "false",
    "orderCode": "1234",
    "referenceId": "3042815493",
    "referenceUrl": "https://secure.worldpay.com/wcc/dispatcher?OrderKey=MERCH_CODE_FROM_PROVIDER%5E1234",
    "success": "true"
}

The following sections describe the steps required to manage prepaid balances using a third-party payment provider:

• Setting up a merchant account with the Worldpay payment provider
• Configuring the payment provider in Edge
• Viewing the payment providers configured for your organization
• Enabling and configuring required modules in the developer portal
• Initiating payment to a prepaid account using a payment provider
• Reloading a prepaid account balance using the API
• Deleting a third-party payment provider

Setting up a merchant account with the Worldpay payment provider

Before you begin, you must contact a third-party payment provider (Worldpay) to set up your merchant account(s). It is recommended that you set up two accounts, one for testing and one for production. For more information about Worldpay merchant accounts, see www.worldpay.com and wp-support.crm.worldpay.com (Worldpay support center).

After you've set up your merchant account and receive your account credentials, to configure your merchant account with Worldpay:

1. Navigate to https://secure.worldpay.com/sso/public/auth/login.html.
2. Log in to your Worldpay account using the credentials provided to you by Worldpay.
3. Set the XML password and message authentication code (MAC) secret key:
   1. Click Profile.
   2. Set the password to use when configuring the Worldpay payment provider in Edge in the XML Password field.
   3. Enter a 20 to 30-character MAC secret key in the Redirect MAC secret field.
   4. Click Save Profile
4. Add the Apigee Edge management server to the list of merchant IPs (allowlist):
   1. Click Profile > Merchant Environment.
   2. Click New Test IP.
   3. Enter the IP for the Apigee Edge management server.
   4. Click Save.
5. Configure merchant URL to append the Worldpay parameters, including the method authentication code (MAC):
   1. Click Installations > Hosted Payment Pages > Payment Page Designer.
   2. Under Edit Payment Pages, select your installation ID from the Select channel drop-down list.
   3. On the Properties tab, select Edit merchant configuration.
   4. Set the Send URL parameters value to True.
   5. Click the Publish tab.
   6. Promote changes, as follows:
      • For test environments, click Promote under Design to promote from Design to Sandbox.
      • For production environments, click Promote under Sandbox to promote from Sandbox to Production.

Configuring the payment provider in Edge

The next step is to configure the payment provider in Edge.

You can configure your payment provider for a specific organization using the following API:

/organizations/{org-name}/providers

Apigee Edge Private Cloud customers only with sys admin privileges can optionally configure a global payment provider using the following API:

/config/providers

When calling each API, you must specify the following information in the request body:

For example, the following sets up a merchant account with Worldpay named Worldpay-myorg:

$ curl  -H "Content-Type:application/json" -X POST -d \
'{
    "name": "Worldpay-myorg",
    "description": "Worldpay payment provider",
    "endpoint": "https://secure.worldpay.com/jsp/merchant/xml/paymentService.jsp",
    "authType": "123456",
    "credential": "dXNlcm5hbWU6cGFzc3dvcmQ=",
    "merchantCode": "myMerchantCode"
  }' \
"https://api.enterprise.apigee.com/v1/organizations/myOrg/providers" \
-u email:password 

Viewing third-party payment providers

View and confirm the third-party payment providers configured for your Edge organization by issuing a GET request to the following resource:

/mint/organizations/{org-name}/providers

For example, the following displays the third-party payment providers currently configured for myorg:

$ curl  -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/providers" \
-u email:password

The following provides an example of the response showing two merchant accounts, one for testing and the other for production.

{
  "provider" : [ {
    "authType" : "123456",
    "credential" : "dXNlcm5hbWU6cGFzc3dvcmQ=",
    "description" : "Worldpay payment provider",
    "endpoint" : "https://secure.worldpay.com/jsp/merchant/xml/paymentService.jsp",
    "id" : "worldpay-myorg",
    "merchantCode" : "MERCH_CODE",
    "name" : "Worldpay-myorg"
  }, {
    "authType" : "123456",
    "credential" : "dXNlcm5hbWU6cGFzc3dvcmQ=",
    "description" : "Worldpay payment provider",
    "endpoint" : "https://secure-test.worldpay.com/jsp/merchant/xml/paymentService.jsp",
    "id" : "worldpay-test",
    "merchantCode" : "MERCH_CODE_FROM_PROVIDER",
    "name" : "Worldpay-test"
  } ]
}

Enabling and configuring Monetization and Worldpay modules in the developer portal

Enable the required Monetization and Worldpay modules in the developer portal. For details, see Configure Monetization in the Developer Portal.

Initiating payment to a prepaid account using the payment provider

As shown in step 2 of the prepaid account management flow, payment to a prepaid account using a payment provider is initiated by the developer portal when API consumers:

• Accept a rate plan, but have insufficient funds in their prepaid account
• Request to add money to their prepaid account.

To initiate a payment from a third-party payment provider using the API, issue a POST request to the following resource, where {developer_id} is the email address of the developer.

/mint/organizations/{org_name}/developers/{developer_id}/payment?amount={amount}&provider={providerId}&supportedCurrencyId={currency}

When you issue the request, you need to specify the following values as query parameters:

• Amount to add to the prepaid account balance (amount={amount})
• Payment provider ID (provider={providerId})
• Supported currency (supportedCurrencyId={currency})

In addition, you need to pass basic account details, such as the company billing address.

For example, the following reloads a prepaid account balance using the Worldpay payment provider. The initial transfer to your prepaid account will be 10 US dollars (amount query parameter is set to 10).

$ curl  -H "Content-Type:application/xml" -X POST -d \
'{
    "address1": "5115 Hopyard Ave.",
    "city": "Pleasanton",
    "country": "US",
    "state": "CA",
    "zip": "58158"
}'
' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/{developer_id}/payment?amount=10&provider=worldpay-myorg&supportedCurrencyId=usd" \
-u email:password

The following provides an example of the response:

{
    "isRecurring": "false",
    "orderCode": "1234",
    "referenceId": "3042815493",
    "referenceUrl": "https://secure.worldpay.com/wcc/dispatcher?OrderKey=MERCH_CODE_FROM_PROVIDER%5E1234",
    "success": "true"
}

The URL to the Worldpay Secure Payment page is returned in referenceUrl with your unique order key appended as a query parameter.

Reloading a prepaid account balance using the API

As shown in step 15 of the prepaid account management flow, after verifying successful processing by the payment provider, the developer portal sends a request to Edge to reload the prepaid account.

You can reload the prepaid account balance using the API for a developer or company, as described in the following sections.

Reloading a prepaid account balance for a developer

To reload a prepaid account balance for a developer using the API, issue a POST request to /mint/organizations/{org_name}/developers/{developer_id}/developer-balances, where {developer_id} is the email address of the developer. When you issue the request, you need to specify in the request body the amount to add to the balance and the currency used.

For example, the following request adds $1000 to a developer's prepaid account balance:

$ curl -H "Content-Type:application/json" -X POST -d \
'{
  "amount": 1000,
  "supportedCurrency": {
      "id": "usd" 
  } 
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/{developer_id}/developer-balances" \
-u email:password

For a description of the request properties, see Summary of request properties for reloading a prepaid account.

Reloading a prepaid account balance for a company

To reload a prepaid account balance for a company using the API, issue a POST request to /mint/organizations/{org_name}/companies/{company_id}/developer-balances, where {company_id} is the ID of the company. When you issue the request, you need to specify in the request body the amount to add to the balance and the currency used.

For example, the following request adds $1000 to a company's prepaid account balance:

$ curl -H "Content-Type:application/json" -X POST -d \
'{
  "amount": 1000,
  "supportedCurrency": {
      "id": "usd" 
  } 
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/companies/{company_id}/developer-balances" \
-u email:password

For a description of the request properties, see Summary of request properties for reloading a prepaid account.

Summary of request properties for reloading a prepaid account

The following properties must be specified when reloading prepaid account balances using the API:

Deleting third-party payment providers

You can delete a third-party payment provider configured for your Edge organization by issuing a DELETE request to the following resource:

To delete a payment provider for a specific organization, use the following API:

/mint/organizations/{org-name}/providers/id

Apigee Edge Private Cloud customers only with sys admin privileges can optionally delete a global payment provider using the following API:

/config/providers/id

For example, the following deletes the third-party payment providers currently configured for myorg:

$ curl  -X DELETE \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/providers/worldpay-myorg" \
-u email:password

Managing prepaid account balances manually

Alternatively, you can manage the reload of prepaid balances by tracking payments manually or via an integrated billing system and then calling the monetization API to reload the account, as described in Reloading a prepaid account balance using the API.

Setting up automatic reload of prepaid account balances using the API

The following sections describe how to set up automatic reload of prepaid account balances for a developer or company using a third-party payment provider. This option is useful to manage recurring payments for rate plans.

Setting up automatic reload of prepaid account balances for a developer

To set up automatic reload of a prepaid account balance for a developer when the balance drops below a certain threshold, issue a POST request to /mint/organizations/{org_name}/developers/{developer_id}/developer-balances/recurring-setup, where {developer_id} is the email address of the developer.

When you issue the request, you need to specify the following:

• ID of the payment provider to use to reload the account (providerID)
• Flag that enables automatic reload (isRecurring)
• Threshold that the prepaid account balance must drop below in order to trigger automatic reload (replenishAmount)
• Amount to add automatically to the account (recurringAmount)
• supportedCurrencyID query parameter to specify the currency.

In the following example, when the developer's prepaid account balance drops below 5 US dollars, an additional 10 US dollars will be added automatically to the account.

$ curl -H "Content-Type:application/json" -X POST -d \
'{
    "providerId": "worldpay-myorg",
    "isRecurring" : true,
    "replenishAmount" : 5,
    "recurringAmount" : 10
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/{developer_id}/developer-balances/recurring-setup?supportedCurrencyId=usd" \
-u email:password

For a description of the request properties, see Summary of request properties for setting up automatic reload of a prepaid accounts.

Setting up automatic reload of prepaid account balances for a company

To set up automatic reload of a prepaid account balance for a company when the balance drops below a certain amount, issue a POST request to /mint/organizations/{org_name}/companies/{company_id}/developer-balances/recurring-setup, where {company_id} is the ID of the company.

When you issue the request, you need to specify the following:

• ID of the payment provider to use to reload the account (providerID)
• Flag that enables automatic reload (isRecurring)
• Threshold that the prepaid account balance must drop below in order to trigger automatic reload (replenishAmount)
• Amount to add automatically to the account (recurringAmount)
• supportedCurrencyID query parameter to specify the currency.

In the following example, when the company's prepaid account balance drops below 5 US dollars, an additional 10 US dollars will be added automatically to the account.

$ curl -H "Content-Type:application/json" -X POST -d \
'{
    "providerId": "worldpay-myorg",
    "isRecurring" : true,
    "replenishAmount" : 5,
    "recurringAmount" : 10
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/companies/{company_id}/developer-balances/recurring-setup?supportedCurrencyId=usd" \
-u email:password

For a description of the request properties, see Summary of request properties for setting up automatic reload of a prepaid accounts.

Summary of request properties for setting up automatic reload of prepaid accounts

The following attributes can be specified when reloading prepaid account balances automatically using the API.

Migrating to WorldPay's Hosted Payment Pages

WorldPay has updated their secure payment processing flow to use a new set of pages, referred to as the Hosted Payment Pages.

If you configured your WorldPay payment provider(s) using the deprecated secure payment processing flow (prior to August 2017), you will need to migrate to WorldPay's new Hosted Payment Pages before January 2018.

To migrate to WorldPay's Hosted Payment Pages:

1. Contact WorldPay to migrate your current account to use the new Hosted Payment Pages and obtain a new installation ID for your account.
2. Configure new WorldPay payment providers, as described in Configuring the payment provider in Edge, passing the installation ID in the authType field.
3. Configure the new payment provider(s) on your developer portal, as described in Configure Monetization in the Developer Portal.
4. If you set up automatic reload of a prepaid account using the payment provider, you need to re-configure the automatic reload to use the new provider ID, as described in Setting up automatic reload of prepaid account balances using the API.

Next steps

You can set credit limits for individual postpaid developers. Learn how in Manage postpaid balances.