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:

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:

Query Parameter Description
all Flag that specifies whether to return all API packages. If set to false, the number of API packages returned per page is defined by the size query parameter. Defaults to false.
size Number of API packages returned per page. Defaults to 20. If the all query parameter is set to true, this parameter is ignored.
page Number of the page that you want to return (if content is paginated). If the all query parameter is set to true, this parameter is ignored.
currencyId ID of the currency for which you want to view prepaid account balances.

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:

Query Parameter Description
all Flag that specifies whether to return all API packages. If set to false, the number of API packages returned per page is defined by the size query parameter. Defaults to false.
size Number of API packages returned per page. Defaults to 20. If the all query parameter is set to true, this parameter is ignored.
page Number of the page that you want to return (if content is paginated). If the all query parameter is set to true, this parameter is ignored.
currencyId ID of the currency for which you want to view prepaid account balances.

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.

Worldpay payment provider flow

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

Step Description
0 Prerequisite steps
As the API provider, to set up a third-party payment provider, such as Worldpay, you must:
1 To trigger the flow, an API consumer performs one of the following tasks in the developer portal:
  • Adds money to an account
  • Accepts a rate plan with insufficient funds
2 Developer portal initiates payment through Edge for the developer, with the provider ID, reload amount, and currency. For information about using the API to initiate payment, see Initiating payment to a prepaid account using a payment provider.
3 Edge finds provider by ID, determines that it is a Worldpay account.
4 Edge generates an order code.
5 Edge creates the payment order on Worldpay.
6 Worldpay returns a reference ID for the order and a time-limited URL to fulfill it.
7 Worldpay’s response is converted into a generic Edge /payment API response, which is returned back to the developer portal to complete the call initiated in step 2. For example:
{
    "isRecurring": "false",
    "orderCode": "1234",
    "referenceId": "3042815493",
    "referenceUrl": "https://secure.worldpay.com/wcc/dispatcher?OrderKey=MERCH_CODE_FROM_PROVIDER%5E1234",
    "success": "true"
}
8 Developer portal appends callback URLs (for success, failure, and so on) as query parameters to URL.
9 Developer portal responds to request in step 1 by redirecting the API consumer's browser to the modified URL.
10 API consumer completes the application form and initiates processing with Worldpay.
11 Worldpay captures billing information and processes the payment. On success, Worldpay generates a Message Authentication Code (MAC) using the MAC Secret configured on both Worldpay and the developer portal.
12 Worldpay redirects the API consumer's browser to the successful callback URL (from step 8), appending the MAC as a query parameter, and the amount.
13 Browser calls URL on developer portal with the requested amount and MAC.
14 Portal verifies the MAC against the MAC secret. The MAC prevents a person from arbitrarily claiming that successful payments have been made.
15 Developer portal sends request to Edge to reload the prepaid account balance. For information about using the API to reload the account balance, see Reloading a prepaid account balance using the API.

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

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:

Parameter Description Required
authType Installation ID provided by the payment provider. Yes
credential Base64-encoded credentials (username:XMLpassword) for your Worldpay merchant account; username is equivalent to the merchant code (in all caps) and XMLpassword specifies the XML password you set in the previous step, when setting up your Worldpay merchant account. Yes
description Description of the payment provider. No
endpoint Endpoint to access the payment provider
  • For test accounts, use: https://secure-test.worldpay.com/jsp/merchant/xml/paymentService.jsp
  • For production accounts, use: https://secure.worldpay.com/jsp/merchant/xml/paymentService.jsp
Yes
merchantCode Merchant code provided by the payment provider to the API consumer Yes
name Name to use for the provider.

Apigee Edge Private Cloud customers only: For global payment providers, ensure that the name is unique across all Edge organizations. It is recommended that you include WorldPay (case-insensitive) in the provider name for easy identification. For example: WorldPay test or WorldPay prod. Spaces in provider names will be converted to underscores.

Yes

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:

Name Description Default Required?
amount

Amount applied to the prepaid balance (in the applicable currency).

N/A Yes
supportedCurrency

Currency used for the prepaid balance. This is the currency that was set up for the plan in the API package that the developer purchased.

N/A Yes

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.

Name Description Default Required?
providerId

ID of the payment provider.

N/A Yes
chargePerUsage false No
isRecurring

Flag that specifies whether automatic reload is enabled (true). To disable automatic reload, set this flag to false.

N/A Yes
replenishAmount

Threshold that the prepaid account balance must drop below in order to trigger automatic reload.

N/A Yes
recurringAmount

Amount to add to the prepaid account balance when automatic reload is triggered.

N/A Yes

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.