Send Docs Feedback

Manage prepaid account balances

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

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 a prepaid account balance 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.

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 a prepaid account balance 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.

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.

Configuring the payment provider in Edge

The next step is to configure the payment provider in Edge. Payment providers are configured globally and apply across organizations.

The following sections describe the steps required to set up a merchant account with a third-party payment provider (Worldpay, in this case) in Edge. Steps vary based on whether you are using Apigee Edge Cloud or Apigee Edge for Private Cloud.

Apigee Edge Cloud

For Apigee Edge Cloud customers, Apigee will assist you in setting up the third-party payment provider. Contact your Apigee customer support representative for assistance.

Apigee Edge Private Cloud

The following monetization API requires that your Edge account has sysadmin privileges.

For Apigee Edge for Private Cloud customers, to set up a merchant account with a third-party payment provider, issue a POST request to the following resource:

/config/providers

You must specify the following information in the request body:

  • Name to use for the provider
    Note: Ensure that the name is unique across all Edge organizations.
  • Description (optional)
  • 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
  • Authorization media type (application/xml)
  • 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
  • Merchant code provided by the payment provider to the API consumer

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": "application/xml",
    "credential": "dXNlcm5hbWU6cGFzc3dvcmQ=",
    "merchantCode": "MERCHANTCODE"
  }]
}
' \
"https://host/v1/config/providers" \
-u email:password

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" : "application/xml",
    "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" : "application/xml",
    "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

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 {developer_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

Next steps

You can post refunds (for purchase transactions only) using monetization. Learn how in Post refunds.

Help or comments?