Amazon Balance Load (ABL) is a set of systems that lets you load funds directly into a customer’s Amazon Gift Card Balance in real-time, as long as the customer can identify themself as an active Amazon customer. An active Amazon customer as defined as a customer who has an Amazon account in the desired marketplace. For phone number implementations, they'll need to have the number associated with the Amazon account.
Amazon Cash uses the Amazon Balance Load service to let a customer add funds to their Amazon Gift Card Balance at a physical (brick and mortar) retail store within your network by providing a barcode or mobile phone number that identifies the Amazon customer account. When an active Amazon account cannot be found, a customer can get an Amazon Gift Card claim code on a printed receipt they can redeem later if your implementation allows this outcome.
The Amazon Cash service (name may differ by country) lets Amazon customers 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 transaction is initiated within the distribution partner's network of B&M sites, which process the load requests and route those transactions directly to Amazon.
Two methods are available for a customer to represent their Amazon account at a partner's B&M location:
Barcode - Showing a personalized barcode generated by Amazon that is linked to the customer’s Amazon account (customers get their Amazon Cash barcode from the Amazon app or Amazon website),
Or
Phone Number - Entering/providing the phone number that is linked to their Amazon account, at the point of sale.
Note: Support for account identification formats and other details may vary by country.
In addition to the customer’s method of identification (barcode or phone number), the customer communicates the amount of funds they wish to load into their account to the store associate (minimum of $5 and maximum of $500 per load in the United States). This information is compiled and then transmitted to Amazon who subsequently responds with a confirmation or rejection of the load request. you can use either a two-step or one-step load request process as detailed below.
To integrate with the Amazon Cash product and support account type 1 (barcode based), your POS (point-of-sale) system must have barcode scanners that can scan barcodes on mobile phones and support 1D barcodes in Code 128 format.
Barcode Format
Amazon uses its own Product Code and IIN in the construction of the barcode. The Amazon barcode is 30 digits in length, composed of:
11 digits UPC
13 digits EAN or JAN
6 digits IIN
12 digits PAN
1 digit checksum
Amazon uses the LUHN algorithm to generate the checksum digit and the algorithm is applied to the IIN + PAN.
Find below Amazon’s product code (UPC/EAN/JAN) and IIN, plus a barcode example. Note that product code will vary per country.
Phone number is another supported account type 4. To integrate with the Amazon Cash product and support the phone number account type, your POS system must allow an operator to input phone number digits and print a receipt with claim code. In certain scenarios, the Amazon Cash transaction must return a paper receipt that contains a claim code that the customer can use online later to credit their account.
Phone Number Format
The phone number input must adhere to either one of the following formats:
E.164 is the international telephone numbering plan that ensures each device on the PSTN (public switched telephone network) has a globally unique number.
Local Number Format
Strictly numerical, for example, must not contain any dashes, spaces, or parentheses (-, ' ', or ()). The number must be a valid local number and must include the area code. For example, in the US, a valid local number would be 10 digits, set across like 2066231234.
E.164 numbers can have a maximum of fifteen digits and are formatted as:
[+] [country code] [subscriber number including area code]
For example, +14155552671 (US Number), +442071838750 (UK Number).
Using the E.164 format provides more options for your integration in the future and is therefor the preferred method.
Note: Currently, we only support the use of a local phone number in the corresponding nation where the transaction is taking place. Hence, if a customer attempts to use a Mexican phone number at a US kiosk/store, the transaction will be rejected at the POS.
Receipt Requirements
Receipt requirements differ based on POS systems ability to change the content based on whether the LoadAmazonBalance call for phone form factor-based load applied the funds to the customer’s account (verified phone number) or issued a claim code (unverified phone number).
Scenario
Should claim code appear on the receipt?
Instruction text (if POS can change receipt text)
Verified phone number
No. (Funds are auto-applied to the customer’s account. LoadAmazonBalance response does not include claim code.)
An Amazon Gift Card have been added to your Amazon Account. Amazon Cash transactions are non-refundable, except as required by law. Hold onto this receipt until you receive confirmation that funds have been added to your Amazon Account. Other restrictions apply. For full terms and conditions, see www.amazon.com/gc-legal
Unverified phone number
Yes. (LoadAmazonBalance will issue a claim code)
Claim code: AR7E-VJTKKU-TFJ Your transaction is not complete. An Amazon Gift Card will not be added until you visit www.amazon.com/gc/redeem and enter the claim code printed on this receipt to add funds to your Amazon Account. Amazon Cash transactions are non-refundable, except as required by law. Other restrictions apply. For full terms and conditions, see www.amazon.com/gc-legal
Valid barcode
No. (Funds are auto-applied to the customer’s account. LoadAmazonBalance response does not include claim code)
An Amazon Gift Card have been added to your Amazon Account. Amazon Cash transactions are non-refundable, except as required by law. Hold onto this receipt until you receive confirmation that funds have been added to your Amazon Account. Other restrictions apply. For full terms and conditions, see www.amazon.com/gc-legal
Invalid barcode
No. (Transaction will fail. LoadAmazonBalance response does not include claim code.)
(No receipt needs to be printed or a transaction failed receipt needs to be printed.)
Default Instruction Text
If the POS system cannot change the receipt content, this text should appear:
Example
Hold on to this receipt until you receive confirmation that funds have been added to your Amazon Balance
If the funds were not automatically applied to your account, you can visit www.amazon.com/gc/redeem to complete the transaction.
Amazon Cash transactions are non-refundable, except as required by law. Other restrictions apply. For full terms and conditions, see www.amazon.com/gc-legal.
Additional requirements at Brick and Mortar locations
Every call to LoadAmazonBalance that occurs at a brick and mortar location must include details of the location where the transaction occurred. Requests to these endpoints can include a transactionSource object that describes the physical location of the event. These parameters can be found in the request parameters table below.
There are two options for sending store location data to Amazon:
Long form – partner provides specific store location data for each transaction (must include sourceId, institutionId and sourceDetails)
Short form – partner provides only the sourceId and institutionId in the API request. A separate location mapping file must be sent that maps these identifiers to physical locations. See Location Mapping file instructions in this spreadsheet.
Note:sourceDetails must be formatted as a JSON blob. In the JSON example, the JSON blob uses the backslash to escape quotation marks.)
Sample payload for transaction source in both XML and JSON format is shown below.
<LoadAmazonBalanceRequest><account><id>851432007016085741000205631269</id><type>1</type></account><partnerId>Bus21</partnerId><amount><currencyCode>USD</currencyCode><value>4570</value></amount><loadBalanceRequestId>Bus21requestId1</loadBalanceRequestId><timestamp>1464933146</timestamp><transactionSource><sourceDetails>{ "institutionName": "Walgreens",
"Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
"Phone": "+12061232333"}
</sourceDetails></transactionSource></LoadAmazonBalanceRequest>
JSON
{"loadBalanceRequestId":"Amxx134565","partnerId":"Amxx1","amount":{"currencyCode":"USD","value":1000},"account":{"id":"5551112222","type":"4"},"timestamp":1574704599588,"transactionSource":{"sourceId":"12345","institutionId":"Example123344"},"externalReference":"serviceId:123","notificationDetails":{"notificationMessage":"Thank you for loading balance at 12345!"}}
XML
<LoadAmazonBalanceRequest><loadBalanceRequestId>Amxx134565</loadBalanceRequestId><partnerId>Amxx1</partnerId><amount><currencyCode>USD</currencyCode><value>1000</value></amount><account><id>5551112222</id><type>4</type></account><timestamp>1574704599588</timestamp><transactionSource><sourceId>12345</sourceId><institutionId>Example123344</institutionId></transactionSource><externalReference>serviceId:123</externalReference><notificationDetails><notificationMessage>Thank you for loading balance at 12345!</notificationMessage></notificationDetails></LoadAmazonBalanceRequest>
Minimum and Maximum Amount per Transaction per Country
Country
Currency Code
Range
Expiration
Australia
AUD
1.00 - 5000.00
10 Years
Belgium
EUR
1.00 - 5000.00
10 Years
Canada
CAD
1.00 - 5000.00
N/A
Egypt
EGP
50.00 - 6000.00
10 Years
France
EUR
1.00 - 5000.00
10 Years
Netherlands
EUR
1.00 - 5000.00
10 Years
Germany
EUR
1.00 - 5000.00
10 Years
Italy
EUR
1.00 - 5000.00
10 Years
Japan
JPY
100.00 - 300000.00
10 Years
KSA
SAR
5.00 - 5000.00
10 Years
Mexico
MXN
20.00 - 40000.00
5 Years
Poland
PLN
5.00 - 21000.00
10 Years
Spain
EUR
1.00 - 5000.00
10 Years
Singapore
SGD
1.00 - 500.00
10 Years
South Africa
ZAR
20.00 - 6000.00
10 Years
Sweden
SEK
10.00 - 10000.00
10 Years
Turkey
TRY
50.00 - 5000.00
10 Years
United Arab Emirates
AED
5.00 - 6000.00
10 Years
United Kingdom
GBP
1.00 - 5000.00
10 Years
United States
USD
1.00 - 2000.00
N/A
Note: If your integration is for a country not listed, please check with your account manager for the minimum and maximum load amounts.
Note: A recipient from Ireland should be able able to redeem their gift card from United Kingdom and Germany retail websites and use it for shopping on Amazon. Both these marketplaces deliver to Ireland.
Loads funds into a customer’s Amazon gift card balance. When Amazon account cannot be matched, issues a gift card claim code that the customer can redeem online later.
Voids a previously successful LoadAmazonBalance request.
Note: Looking for endpoints? You can find them here
Two-Step Balance Load Process
The two-step balance load process involves the use of two API’s: ValidateAccountForAmazonBalanceLoad and LoadAmazonBalance. The typical process is described below:
The Store cashier scans the customer’s Amazon Cash barcode or enters the customer’s phone number and asks how much cash the customer wants to load.
The cashier enters the amount into the POS(Point-of-Sale) terminal and confirms with the customer.
The POS sends a ValidateAccountForAmazonBalanceLoad request to Amazon. Amazon checks customer’s eligibility to load the requested amount to his/her Amazon Gift Card Balance.
If ValidateAccountForAmazonBalanceLoad response confirms the request, the cashier takes cash from the customer and the POS sends the LoadAmazonBalance request to Amazon via the Distribution Partner network. Amazon does not recommend pre-tender activations (i.e., calling LoadAmazonBalance before the store cashier has received money.)
Amazon processes the request, first checking the customer’s eligibility, and if eligible and if the Amazon account can be identified, loads the requested funds into the customer’s Amazon Gift Card Balance. A confirmation response is sent. If the account is ineligible, a rejection response is sent back. In the case of customer providing phone number for the Balance Load process, and if that phone number cannot be associated to any Amazon account, the operation will respond with a valid Gift Card Claim Code. In this case, the claim code has to be printed on the receipt and given to the customer.
If you do not have the ability to send a ValidateAccountForAmazonBalanceLoad request, as described in the two-step instructions above, can choose to use just the LoadAmazonBalance request directly. This one-step Balance Load process is described here:
The store cashier scans the customer’s Amazon Cash barcode or enters the customer’s phone number and asks how much cash the customer wants to load.
The cashier enters the amount into the POS terminal, confirms with the customer and then takes the cash from the customer.
The POS sends a LoadAmazonBalance request to Amazon using your network.
To handle the request, Amazon checks the customer’s eligibility. If eligible and if the Amazon account can be identified, Amazon loads the requested funds into the customer’s Gift Card Balance. A confirmation response is sent. If the account is ineligible, a rejection response is sent back. If the customer provides a phone number, but that phone number cannot be associated to any unique account, the operation will respond with a valid Gift Card Claim Code. In this case, the claim code must be printed on the receipt and given to the customer.
Figure 2. One-step Balance Load Store Process Diagram
The ValidateAccountForAmazonBalanceLoad operation validates whether the intended amount is within the range allowed for this country, and checks if a customer’s Amazon account is eligible for the Balance Load process.
For barcode account type, the eligibility check validates that the barcode linked to an active Amazon customer account and is approved to add funds into their Amazon Gift Card balance.
For phone number account type, this validates that the phone number provided is a valid phone number. If the phone can be identified as linked to one Amazon customer account, this will also validate the customer eligibility status. Otherwise, the validation will NOT reject the unidentified phone number (that is not linked to any Amazon customer) and will treat this as a valid account. The operation will respond with a PARTIAL_SUCCESS in this case. For such unverified phone numbers, the
LoadAmazonBalance operation will return a claim code for manual redemption by the customer later on.
Note: This operation is preferred but NOT a prerequisite to perform a successful LoadAmazonBalance operation later on.
Note: You can find barcodes and numbers for testing here.
Requests
Request Parameters
Request Parameter
Req
Constraints
Type
Description
loadBalanceRequestId
Yes
Max 40 Characters
Prefixed with partnerID
AlphaNumeric
String
A unique identifier to represent the request prefixed with a case sensitive partnerId (max 40 characters). Alphanumeric.
partnerId
Yes
Pre-defined value
String
A case sensitive unique identifier to represent your account
amount
Yes
Object
currencyCode and value parameters
currencyCode
Yes
ISO-4217 Currency Code
String
The ISO-4217 currency code
value
Yes
Long
The monetary value to be disbursed specified as a whole number e.g. 100.23 = 10023. In a region where currency does not support decimal no padding is required. E.g. In Japan, 231 Yen = 231 not 23100
account
Yes
Pre-defined value
Object
The information that identifies an active Amazon customer provided by the barcode or phone number. For Sandbox requests use can use any production user.
id
Yes
Pre-defined value
String
The information that identifies an active Amazon customer provided by the barcode or phone number. For Sandbox requests use can use any production user.
type
Yes
Pre-defined value
Int
Specifies the type of identifier. Valid type value = 1 (Barcode), 4 (Phone Number)
timestamp
Yes
In Millisecond
Timestamp
A timestamp of the transaction. Based on your system time.
transactionSource
Yes
Object
Data to identify the transaction source. Contains the sourceID, sourceDetails and institutionID.
sourceId
Yes
Max 20 characters
String
Identifier of the transaction. This metadata will display in the customers Amazon balance ledger. E.g. "Gift Card from (Max 40 Unicode chars)
sourceDetails
B&M Only
Max 200 characters
JSON String
string to provide further information about transaction source. It must contain institutionName key with value as name of the source (e.g. Merchant Name). Other information such as source location, business phone-number, etc. should be included.
institutionID
B&M Only
Max 20 characters
String
Identifier of a parent entity of a transaction source (Example: Merchant Id). If parent entity does not exist, copy sourceId.
externalReference
Optional
Max 100 characters
String
A text field you can use to identify the request when viewed in the Incentives API Portal. (Max 100 Unicode characters)
notificationDetails
Optional
Max 100 characters
String
A description of the reason for funds disbursement.
notificationMessage
Optional
Max 250 characters
String
A string that will appear in the confirmation email (Max 250 Unicode characters).
The monetary value to be disbursed specified as a whole number e.g. 100.23 = 10023. In a region where currency does not support decimal no padding is required. E.g. In Japan, 231 Yen = 231 not 23100
account
Pre-defined value
Object
The information that identifies an active Amazon customer provided by the Login with Amazon API. For Sandbox requests use amzn1.account.AFEM4VZRQQMBAAMVQEP3BPBH7OYQ
id
Pre-defined value
String
A unique customer account identification value which identifies the user’s Amazon account returned as a JSON HTTP response from the Login with Amazon API
type
Pre-defined value
Int
Specifies the type of identifier. Valid type value = 1 (Barcode), 4 (Phone Number)
The LoadAmazonBalance operation loads funds into a customer’s Amazon Gift Card Balance or returns a valid Gift Card Claim Code (in the case when the given phone number is Unverified, for example, the phone number is not verified on an Amazon account. This operation is idempotent, in the sense that if Amazon receives multiple LoadAmazonBalance requests with the same loadBalanceRequestId, the same response from the first call will be returned. The loadBalanceRequestId you provide can have a maximum length of 40 characters, must be prefixed with your partnerId, and must be unique.
Note: You can find barcodes and numbers for testing here.
Requests
Request Parameters
Request Parameter
Req
Constraints
Type
Description
loadBalanceRequestId
Yes
Max 40 Characters
Prefixed with partnerID
AlphaNumeric
String
A unique identifier to represent the request prefixed with a case sensitive partnerId (max 40 characters). Alphanumeric, should not contain characters
partnerId
Yes
Pre-defined value
String
A case sensitive unique identifier to represent your account
amount
Yes
Object
currencyCode and value parameters
currencyCode
Yes
ISO-4217 Currency Code
String
The ISO-4217 currency code
value
Yes
Long
The monetary value to be disbursed specified as a whole number e.g. 100.23 = 10023. In a region where currency does not support decimal no padding is required. E.g. In Japan, 231 Yen = 231 not 23100
account
Yes
Pre-defined value
Object
The information that identifies an active Amazon customer provided by the Login with Amazon API. For Sandbox requests use amzn1.account.AFEM4VZRQQMBAAMVQEP3BPBH7OYQ
id
Yes
Pre-defined value
String
A unique customer account identification value which identifies the user’s Amazon account returned as a JSON HTTP response from the Login with Amazon API
type
Yes
Pre-defined value
Int
Specifies the type of identifier. Valid type value = 1 (Barcode), 4 (Phone Number)
timestamp
Yes
In Millisecond
Timestamp
A timestamp of the transaction. Based on your system time.
transactionSource
Yes
Object
Data to identify the transaction source. Contains the sourceID, sourceDetails and institutionID.
sourceId
Yes
Max 20 characters
String
Identifier of the transaction. This metadata will display in the customers Amazon balance ledger. E.g. "Gift Card from (Max 40 Unicode chars)
sourceDetails
B&M Only
Max 200 characters
JSON String
string to provide further information about transaction source. It must contain institutionName key with value as name of the source (e.g. Merchant Name). Other information such as source location, phone-number, etc. should be included.
institutionID
B&M Only
Max 20 characters
String
Identifier of a parent entity of a transaction source (Example: Merchant Id). If parent entity does not exist, copy sourceId.
externalReference
Optional
Max 100 characters
String
A text field you can use to describe the request when viewed in the Incentives API Portal. (Max 100 Unicode characters)
notificationDetails
Optional
Max 100 characters
String
A description of the reason for funds disbursement.
notificationMessage
Optional
Max 250 characters
String
A string that will appear in the confirmation email (Max 250 Unicode characters).
{"account":{"id":"851432007046085742001152342537","type":"1"},"partnerId":"AMB11","amount":{"currencyCode":"USD","value":1000},"loadBalanceRequestId":"AMB111123446","timestamp":1658413475356,"transactionSource":{"institutionId":"12344332","sourceId":"12344332"},"externalReference":"serviceId:123","notificationDetails":{"notificationMessage":"Thank you for your purchase!"}}
Phone
{"account":{"id":"2061231234","type":"4"},"partnerId":"AMB11","amount":{"currencyCode":"USD","value":1000},"loadBalanceRequestId":"AMB111123446","timestamp":1658413475356,"transactionSource":{"institutionId":"12344332","sourceId":"12344332"},"externalReference":"serviceId:123","notificationDetails":{"notificationMessage":"Thank you for your purchase!"}}
A unique identifier to represent the request prefixed with a case sensitive partnerId (max 40 characters). Alphanumeric, should not contain characters
amount
Object
currencyCode and value parameters
currencyCode
ISO-4217 Currency Code
String
The ISO-4217 currency code
value
Long
The monetary value to be disbursed specified as a whole number e.g. 100.23 = 10023. In a region where currency does not support decimal no padding is required. E.g. In Japan, 231 Yen = 231 not 23100
account
Pre-defined value
Object
The information that identifies an active Amazon customer provided by the Login with Amazon API. For Sandbox requests use amzn1.account.AFEM4VZRQQMBAAMVQEP3BPBH7OYQ
id
Pre-defined value
String
A unique customer account identification value which identifies the user’s Amazon account returned as a JSON HTTP response from the Login with Amazon API
type
Pre-defined value
Int
Specifies the type of identifier. Valid type value = 1 (Barcode), 4 (Phone Number)
When a POS cannot guarantee that a request was run successfully, for instance because of a missed message due to network issues, the POS and/or Distribution Partner must run a VoidAmazonBalanceLoad request to ensure that the funds will not be added to the customer’s Amazon Gift Card Balance. In case of any failure at the POS, the cashier always returns the cash to the end customer. Hence, the importance of the void is to ensure that funds are removed promptly from the customer’s Amazon Gift Card Balance in case funds were added successfully but the confirmation message was never received by the POS.
The VoidAmazonBalanceLoad operation will void a successful LoadAmazonBalance request only within 15 minutes of the original request. The original loadBalanceRequestId used to load funds from a successful LoadAmazonBalance request is required for the void operation. The currencyCode, value, sourceId and institutionId fields must match the respective values provided in the original LoadAmazonBalance request. The void operation is idempotent.
Note: You can find barcodes and numbers for testing here.
Requests
Request Parameters
Request Parameter
Req
Constraints
Type
Description
loadBalanceRequestId
Yes
Max 40 Characters
Prefixed with partnerID
AlphaNumeric
String
A unique identifier to represent the request prefixed with a case sensitive partnerId (max 40 characters). Alphanumeric, should not contain characters
partnerId
Yes
Pre-defined value
String
A case sensitive unique identifier to represent your account
amount
Yes
Object
currencyCode and value parameters
currencyCode
Yes
ISO-4217 Currency Code
String
The ISO-4217 currency code
value
Yes
Long
The monetary value to be disbursed specified as a whole number e.g. 100.23 = 10023. In a region where currency does not support decimal no padding is required. E.g. In Japan, 231 Yen = 231 not 23100
account
Yes
Pre-defined value
Object
The information that identifies an active Amazon customer provided by the Login with Amazon API. For Sandbox requests use amzn1.account.AFEM4VZRQQMBAAMVQEP3BPBH7OYQ
id
Yes
Pre-defined value
String
A unique customer account identification value which identifies the user’s Amazon account returned as a JSON HTTP response from the Login with Amazon API
type
Yes
Pre-defined value
Int
Specifies the type of identifier. Valid type value = 1 (Barcode), 4 (Phone Number)
timestamp
Yes
In Millisecond
Timestamp
A timestamp of the transaction. Based on your system time.
transactionSource
Yes
Object
Data to identify the transaction source. Contains the sourceID, sourceDetails and institutionID.
sourceId
Yes
Max 20 characters
String
Identifier of the transaction. This metadata will display in the customers Amazon balance ledger. E.g. "Gift Card from (Max 40 Unicode chars)
voidIfUsed
Yes
Boolean
Boolean (True/False) value to indicate whether a LoadAmazonBalance should be voided even if the end customer has already used the funds (all or partial).
sourceDetails
B&M Only
Max 200 characters
JSON String
string to provide further information about transaction source. It must contain institutionName key with value as name of the source (e.g. Merchant Name). Other information such as source location, phone-number, etc. should be included.
institutionID
B&M Only
Max 20 characters
String
Identifier of a parent entity of a transaction source (Example: Merchant Id). If parent entity does not exist, copy sourceId.
externalReference
Optional
Max 100 characters
String
A text field you can use to describe the request when viewed in the Incentives API Portal. (Max 100 Unicode characters)
notificationDetails
Optional
Max 100 characters
String
A description of the reason for funds disbursement.
notificationMessage
Optional
Max 250 characters
String
A string that will appear in the confirmation email (Max 250 Unicode characters).
A unique identifier to represent the request prefixed with a case sensitive partnerId (max 40 characters). Alphanumeric, should not contain characters
amount
Object
currencyCode and value parameters
currencyCode
ISO-4217 Currency Code
String
The ISO-4217 currency code
value
Long
The monetary value to be disbursed specified as a whole number e.g. 100.23 = 10023. In a region where currency does not support decimal no padding is required. E.g. In Japan, 231 Yen = 231 not 23100
account
Pre-defined value
Object
The information that identifies an active Amazon customer provided by the Login with Amazon API. For Sandbox requests use amzn1.account.AFEM4VZRQQMBAAMVQEP3BPBH7OYQ
id
Pre-defined value
String
A unique customer account identification value which identifies the user’s Amazon account returned as a JSON HTTP response from the Login with Amazon API
type
Pre-defined value
Int
Specifies the type of identifier. Valid type value = 1 (Barcode), 4 (Phone Number)
You are visitor 01402503 — GeezerVison does not store the pages you look up. Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.
