Send Docs Feedback

Manage prepaid account balances

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

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. For more information, see Migrating to Worldpay's Hosted Payment Pages.

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 /mint/organizations/{org_name}/developers/{developer_id}/developer-balances, where {developer_id} is the identification of the developer. If the developer is a prepaid developer, the request retrieves the developer's current prepaid account balance. If the developer is a postpaid developer, the request retrieves the developer's 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.

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.

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

Worldpay is the only payment provider that is supported at this time.

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 (whitelist):

    Note: If you don't know the IP of the Apigee Edge management server, contact your Apigee support representative.

    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

Note: Organization-specific payment providers take precedence over global payment providers that are configured with the same name.

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.

Take note of the id value; you will need to provide this value when configuring the developer portal. The id value is derived from the name of the payment provider, converted to all lower-case. For example, the name of the payment provider is Worldpay-myorg and its corresponding ID is worldpay-myorg.

{
  "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 Enabling and configuring Monetization and Worldpay modules 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 ID 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 ID 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.

If a problem is encountered with an automatic reload, for example if an API consumer credit card expires, the automatic reload will fail without warning. This option is not typically employed for Enterprise-level accounts.

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 ID of the developer. Optionally, you can pass the supportedCurrencyID query parameter to specify the currency.

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)

    To disable automatic reload, set isRecurring to false.

  • Threshold that the prepaid account balance must drop below in order to trigger automatic reload (replenishAmount)
  • Amount to add automatically to the account (recurringAmount)

    It is recommended that you set recurringAmount to a value that is large enough to cover fees incurred for the next 24-hour period. This value must be greater than the minimum reload value configured for the specified currency (supportedCurrencyId query parameter).

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 \
'{ 
    "developerBalance: : [
    {
        "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. Optionally, you can pass the supportedCurrencyID query parameter to specify the currency.

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)

    To disable automatic reload, set isRecurring to false.

  • Threshold that the prepaid account balance must drop below in order to trigger automatic reload (replenishAmount)
  • Amount to add automatically to the account (recurringAmount)

    It is recommended that you set recurringAmount to a value that is large enough to cover fees incurred for the next 24-hour period. This value must be greater than the minimum reload value configured for the specified currency (supportedCurrencyId query parameter).

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 \
'{ 
    "developerBalance: : [
    {
        "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

Note: This attribute is deprecated and should always be set to false.

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.

Note: It is recommended that you set recurringAmount to a value large enough to cover fees incurred for the next 24-hour period. This value must be greater than the minimum reload value configured for the specified currency (supportedCurrencyId query parameter).

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.

Note: To verify whether your are using the deprecated secure payment processing flow, view the third-party payment providers configured for your organization, as described in Viewing third-party payment providers. If authType is set to application/xml, you are using the deprecated flow and must migrate your payment providers to the new Hosted Payment Pages.

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. Note: Use unique names for the new payment providers to ensure that your current payment providers will continue to work for the short term, until they expire.
  3. Configure the new payment provider(s) on your developer portal, as described in Enabling and configuring Monetization and Worldpay modules in the developer portal.
  4. If you set up automatic reload of a prepaid account using the payment provider, you need to re-configure teh 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.

Help or comments?