Amazon Cash API | Integration

Amazon Cash (name may differ by country) is a product in Amazon Balance Load that allows end customers to load funds to their Amazon Gift Card Balance or get a Gift Card claim code in real-time from a brick and mortar (B&M) location. This is initiated within the Distribution Partner’s network of B&M endpoints, which process the load requests and route those transactions directly to Amazon. Customers can use one of two methods to load a balance to their Amazon account from a partner’s B&M location:

  1. Showing a personalized bar code generated by Amazon that is linked to the customer’s Amazon account
  2. Entering/providing the phone number that is linked to their Amazon account, at the point of sale
If you have any questions please visit our frequently asked questions (FAQs) or email our integration team at balanceload-api@amazon.com. Please be sure to include your Partner ID in all correspondence.

Overview of the Amazon Balance Load integration process

  1. Complete the getting started steps
  2. Develop your application
  3. Fund your account
  4. Certify the integration
  5. Launch your application

Step 1: Getting started


(a) Create a new Amazon account

An Amazon account is required to access the API Portal to view transactions, notify us of payments, receive account alerts, and manage your API security credentials.

  1. US clients: Register in about 30 seconds by clicking here.
  2. International clients: Go to amazon.com (or replace '.com' with respective country suffix for international clients). For example, if you want access to the Japan portal, go to amazon.co.jp for your new account.
  3. Create a new account for your company using your company email address
    Important: This should not be tied to your personal Amazon account.
  4. Note: You will also need to set an account to be used as an admin user at your organization. This can be the same account created in the previous step, or it can be a separate account if you prefer to onboard with two users (one with regular credentials, and one with elevated permissions to access security-related features in the Portal).
(b) Email your account details to Amazon

Email the following information to balanceload-api@amazon.com and receive confirmation of your sandbox environment within 24-48 hours.

Click here for an email template to send to the API team.

  1. Your Amazon account email address created in part (a) of step 1.
  2. Amazon account email address for an admin user account at your organization to be used for security purposes. This should be an IT administrator or someone else who will be handling API credentials and other sensitive settings. It can be the same as the address used in (1).
  3. An email alias that we can use for security and system notifications. We will use this address to contract your technical team. This address should be an alias, distribution list, or any other email not tied to any individual user account.
  4. Your Partner ID

Step 2: Develop your application

Integrate with the API operations detailed in the Integration Guides for PIN on receipt, Point of Sale Activation (POSA), or Balance Load into your application and test using the sandbox environment. Each API call must be signed using your AWS credentials and the AWS Signature v4 process.


Step 3: Certify the integration

Once code complete, begin the certification process.

  1. Complete the test cases for Barcode and/or Phone Entry
  2. Send the results to balanceload-api@amazon.com and copy your account manager
  3. Amazon will verify the results within two business days and send you confirmation of certification
Note: If you are an existing customer adding another load method, please certify only the new integration with us. You do not need to certify your existing application again.

Step 4: Fund your account

To ensure timely activation of your API account, please include “New API” followed by your partner ID within the wire transfer details for your first wire payment. The details may be entered into an optional field within your bank’s transfer page labeled “Description,” “Memo,” “Message to Recipient,” or a similar descriptor.

This is only necessary for your first payment and future wire payments should include the Payment Matching ID for faster payment processing. Your Payment Matching ID can be found on the“How to send a payment” page in the API Portal. Note that IDs are specific to an account balance.

Incentives API Portal by region: US | CA | MX | FR | IT | ES | DE | UK | JP


Step 5: Launch your application

Work with your account manager to ensure that basic test scenarios are tested in production (with test accounts) to ensure a successful activation after which your integration will be live in production.

Note: If you have already launched an existing Partner ID with Amazon, the production activation does not apply.


API Access Keys

Access keys are credentials for your AGCOD API account. You use them to sign your requests to the API, and they consist of two parts: an access key ID (for example, AKIAIOSFODNN7EXAMPLE) and a secret access key (for example, wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY). Like a user name and password, you must use both the access key ID and secret access key together to authenticate all your requests. Manage your access keys as securely as you do your user name and password for other services.

Managing access keys

You can use the AGCOD credentials page within the API portal to manage your account's access keys.

To create, modify, or delete your access keys

  1. Sign into the API portal and open the AGCOD credentials page at US | CA | MX | FR | IT | ES | DE | UK | JP.
  2. Select the environment (Production or Sandbox).
  3. In the access keys section, do any of the following
    • To create an access key, choose Create new access key and store the Access key ID and Secret access key in a secure location. You will not have access to the secret key again after this dialog box closes. When you create an access key, the key pair is active by default, and you can use the pair right away.
    • To disable an active access key, choose Deactivate.
    • To re-enable an inactive access key, choose Activate.
    • To delete an access key, choose Delete. Select Delete key in the dialog box to confirm. When you delete an access key, it's gone forever and cannot be retrieved. However, you can always create new keys. Only inactive keys can be deleted.
    • Note! You should only have one active access key at a time, except for when you are rotating your keys.

Rotating access keys

As a security best practice, we recommend that you regularly rotate (change) your access keys. You can do so within the AGCOD credentials page within the API portal. If you are unable to see the page, please reach out to an administrator at your company because only admin users have access to these features.

Changing access keys on a regular schedule is a well-known security best practice because it shortens the period an access key is active and thereby reduces the business impact if they are compromised. Having an established process that is ran regularly also ensures the operational steps around key rotation are verified, so changing a key is never a scary step for your organization.

We recommend changing your access keys at a minimum of once every 180 days (or 6 months). You will receive an email 30 days before the keys should be rotated as a reminder to initiate the process. If you have questions please contact your account manager or incentives-api@amazon.com.

To rotate access keys, you should follow these steps:
  1. Create a second access key in addition to the one in use.
  2. Update all your applications to use the new access key and validate that you are able to make successful AGCOD requests.
  3. Change the state of the previous access key to inactive.
  4. Validate that your applications are still working as expected. Be sure to take care during this step because once an access key is deleted, it cannot be recovered.
  5. Delete the inactive access key.
Both access keys will be supported while in the process of rotating.

Contact Us

If you have questions please contact your account manager or balanceload-api@amazon.com