Receive funds at brick-and-mortar sites

Please make sure to set up your Amazon Incentives API account before starting integration. Amazon Cash Onboarding Steps


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.

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. 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.

Integration with Amazon Balance Load

You can make synchronous requests to these operation endpoints specifying the amount of funds they want to load. Operations respond to each request with a status indicating the success or failure of the operation.

These APIs are available to partners who enter into a contractual agreement with Amazon to build a solution (typically a point-of-sale system) to load funds into an Amazon customer’s Gift Card balance.

Amazon Cash

Country Service name
United States, Mexico, Japan, Canada Amazon Cash
UK, United Arab Emirates Top up in store
Italy Ricarica in cassa
France Recharge près de chez vous
Spain Recargas en tienda
Germany Vor ort aufladen

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:

  1. 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
  2. Entering/providing the phone number that is linked to their Amazon account, at the point of sale.

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.

Onboarding

To get started with integration, see the step-by-step guide provided in the Amazon Cash Onboarding Steps.

When you're signed up, you will receive a unique, case-sensitive Partner ID. Your code will include this identifier in all requests to the Incentives API.

Minimum and Maximum Amount per Transaction per Country

Country Currency Minimum Transaction Maximum Transaction
Canada CAD C$ 5 C$ 500
France EUR € 5 € 500
Netherlands EUR € 1 € 5 000
Germany EUR € 0,01 € 5 000
Italy EUR € 5 € 500
Japan JPY ¥ 500 ¥ 49 000
Mexico MXN $ 100 $ 5 000
Spain EUR € 5 € 500
Turkey TRY ₺ 1 ₺ 5 000
United Arab Emirates AED 10 AED 500 AED
United Kingdom GBP £ 5 £ 250
United States USD $ 5 $ 500

Operations with examples

Below are the operations contained within the balance load API.

API Description
ValidateAccountForAmazonBalanceLoad Checks if a customer’s Amazon Account can be used with LoadAmazonBalance, and other checks.
LoadAmazonBalance 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.
VoidAmazonBalanceLoad Voids a previously successful LoadAmazonBalance request.

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:

  1. 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.
  2. The cashier enters the amount into the POS(Point-of-Sale) terminal and confirms with the customer.
  3. 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.
  4. 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.)
  5. 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.

Figure 1. two-step Balance Load process diagram

One-Step Balance Load Process

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:

  1. 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.
  2. The cashier enters the amount into the POS terminal, confirms with the customer and then takes the cash from the customer.
  3. The POS sends a LoadAmazonBalance request to Amazon using your network.
  4. 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 Amazon 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

Request Parameters

The parameters below can be found within each of the API operations, below is a brief overview of each of these.

account

The account parameter identifies an end customer as an active Amazon customer.

This is a composite structure that consists of id and type.

  • id: A unique identifier that can help Amazon locate a customer’s Amazon account. For Amazon Cash the id is either a barcode number or customer’s phone number.
  • type: Type of end customer’s account identifier. It supports customer identifiers such as barcode, phone number, email, etc.

Operations support two type values:

Value Description
1 barcode
4 phone number
2, 3 These values only apply to products irrelevant to Amazon Cash and should not be used.

partnerId

The partnerId parameter is a unique identifier provided by Amazon during the onboarding process. This value is assigned by Amazon’s Partner Integration Manager and uniquely identifies a Distribution Partner. This value is case-sensitive.


loadBalanceRequestId

A unique identifier you generate to represent a request. This value must be prefixed by the partnerId value and must be less than 40 characters.


amount

The amount parameter specifies the funds that needs to be loaded. It is a composite parameter consisting of currency code and value.

  • currencyCode: ISO-4217 currency code.
  • value: Requested amount value. This field is a whole number (Example: 100.23 as 10023). In a currency that does not support decimal there is no padding required. For example, in Japan, 231 Yen is 231, NOT 23100.

timestamp

UNIX UTC Timestamp in milliseconds since 1/1/1970 00:00 UTC when you initiated the request.

Example: 2018-08-23T15:34:43+00:00 would be represented as 1535038483000


voidIfUsed

Boolean value to indicate whether a LoadAmazonBalance should be voided even if the end customer has already used the funds (all or partial).

Sample Use Case: For example, If the customer has used some of their loaded funds already but a void request is made, we will revoke any remaining funds from the original amount loaded.

For the Amazon Cash use case, LoadAmazonBalance must always be true.

Barcode Account Type

Pre-Requisites

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.

Product Code (UPC 11, EAN 13, JAN 13)

Country Example product code
United States 85143200701
Canada 85143200702
Mexico 85143200703
United Kingdom 85143200704
Germany 1230000042413
France 1230000042512
Italy 85143200707
Spain 1230000042727
Japan 4582274041003
  1. Global Issuer Identification Number (IIN): 608574

Figure 3.1a Barcode Example- 30 digits

Figure 4.1b Barcode Example- 32 digits

Phone Number Account Type

Pre-Requisites

Phone number is another supported account type (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 dynamic claim code. In certain scenarios, the Amazon Cash transaction must return a paper receipt that contains a dynamic 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:

Format Description
E.164 Format 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 paranthesis (-, ' ', 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 intregration in the future and is therefor the prefered method.

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.)
Funds have been added to your Amazon Balance.
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 Balance. 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. Funds 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 Balance.
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)
Funds have been added to your Amazon Balance.
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.

ValidateAccountForAmazonBalanceLoad

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.

Request Parameters

Figure 5 ValidAccountForAmazonBalance Request Parameters

Success Response, Partial Success Response

Figure 6 ValidAccountForAmazonBalanceLoad Success Response

Failure Response

These required strings appear in ValidateAccountForAmazonBalanceLoadException:

  • errorCode
  • errorType
  • errorMessage
  • status   Example 1: Request and success response for barcode-type account Request
POST /ValidateAccountForAmazonBalanceLoad HTTP/1.1 accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.amazon.com x-amz-date:20130910T221949Z x-amz-target:com.amazonaws.agcod.AGCODService.ValidateAccountForAmazonBalanceLoad
	Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790
Payload=

<ValidateAccountForAmazonBalanceLoadRequest>
 	<account>
 	 	<id>851432007016085741001033001453</id>
 	 	<type>1</type>
 	</account>
 	<partnerId>PartnerUS</partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
    <timestamp>1464933146000</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
 	 	<institutionId>A1234</institutionId>
             <sourceDetails>
                 {"institutionName":"Walgreens", "Address":"1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101", "Phone":"+12061232333"}
             </sourceDetails>
 	</transactionSource>
</ValidateAccountForAmazonBalanceLoadRequest>

Response

<ValidateAccountForAmazonBalanceLoadResponse>
 	<account>
 	 	<id>851432007016085741001033001453</id>
 	 	<type>1</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
</ValidateAccountForAmazonBalanceLoadResponse>  

  Example 2: Request and success response for Phone Number type account Request

POST /ValidateAccountForAmazonBalanceLoad HTTP/1.1 accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.amazon.com x-amz-date:20130910T221949Z x-amz-target:com.amazonaws.agcod.AGCODService.
ValidateAccountForAmazonBalanceLoad
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<LoadAmazonBalanceRequest>
    <account>
        <id>2061231234</id>
        <type>4</type>
    </account>
    <partnerId>PartnerUS</partnerId>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
    <timestamp>1464933146000</timestamp>
    <transactionSource>
        <sourceId>12344332</sourceId>
        <institutionId>A1234</institutionId>
        <sourceDetails>{ "institutionName": "Walgreens",
                         "Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
                         "Phone": "+12061232333"}
        </sourceDetails>
    </transactionSource>
</LoadAmazonBalanceRequest>

Response

<ValidateAccountForAmazonBalanceLoadResponse>
 	<account>
 	 	<id>+12061231234</id>
 	 	<type>4</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
</ValidateAccountForAmazonBalanceLoadResponse>  

  Example 3: Request and Partial_Success response for Phone Number type account Request

POST /ValidateAccountForAmazonBalanceLoad HTTP/1.1 accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.amazon.com x-amz-date:20130910T221949Z x-amz-target:com.amazonaws.agcod.AGCODService.
ValidateAccountForAmazonBalanceLoad
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<ValidateAccountForAmazonBalanceLoadRequest>
 	<account>
 	 	<id>2061231235</id>
 	 	<type>4</type>
 	</account>
 	<partnerId>PartnerUS</partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
       <timestamp>1464933146000</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
	 	 	<institutionId>A1234</institutionId>
             <sourceDetails>
                 {"institutionName":"Walgreens", "Address":"1234 Sample
Ave N, Unit #10, Seattle, WA, US, 98101", "Phone":"+12061232333"}
             </sourceDetails>
 	</transactionSource>
</ValidateAccountForAmazonBalanceLoadRequest>

Response

<ValidateAccountForAmazonBalanceLoadResponse>
 	<account>
 	 	<id>+12061231235</id>
 	 	<type>4</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>PARTIAL_SUCCESS</status>
</ValidateAccountForAmazonBalanceLoadResponse>  

  Example 4: Failure Response

Failure Response

<ValidateAccountForAmazonBalanceLoadException>
 	<errorCode>F200</errorCode>
 	<errorType>InvalidRequestInput</errorType>
 	<errorMessage>API request body is null/empty</errorMessage>
 	<status>FAILURE</status>
</ValidateAccountForAmazonBalanceLoadException>  

Example 5: Failure Response Resend

Failure Response

<ValidateAccountForAmazonBalanceLoadException>
 	<errorCode>F400</errorCode>
 	<errorType>SystemTemporarilyUnavailable</errorType>  	<errorMessage>Amazon system is temporarily not available</errorMessage>
 	<status>RESEND</status>
</ValidateAccountForAmazonBalanceLoadException>

An F400 error requires careful retry handling to assure no unintended disbursements occur. See Error Handling.

  Example 6: Comparison of responses (For Barcode and Phone Number Types)

Responses for Phone Number Type (type value 4) when phone number is Verified

Verified Phone (phone tied and verified to Amazon account)

<ValidateAccountForAmazonBalanceLoadResponse>
    <account>
        <id>+14252134543</id>
        <type>4</type>
    </account>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <status>SUCCESS</status>
</ValidateAccountForAmazonBalanceLoadResponse>

Unverified Phone (phone NOT tied/verified to Amazon account)

<ValidateAccountForAmazonBalanceLoadResponse>
    <account>
        <id>+14252134543</id>
        <type>4</type>
    </account>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <status>SUCCESS</status>
</ValidateAccountForAmazonBalanceLoadResponse>
<ValidateAccountForAmazonBalanceLoadResponse>
    <account>
        <id>+12061231234</id>
        <type>4</type>
    </account>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <status>PARTIAL_SUCCESS</status>
</ValidateAccountForAmazonBalanceLoadResponse>

Rewsponses for Barcode Type (type value 1)

Valid/active barcode

<ValidateAccountForAmazonBalanceLoadResponse>
    <account>
        <id>851432007016085741001033001453</id>
        <type>1</type>
    </account>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <status>SUCCESS</status>
</ValidateAccountForAmazonBalanceLoadResponse>

Invalid/inactive barcode

<ValidateAccountForAmazonBalanceLoadException>
    <errorCode>F200</errorCode>
    <errorType>UndefinedAccountId</errorType>
    <errorMessage>AccountId provided in request does not exist in Amazon system</errorMessage>
    <status>FAILURE</status>
</ValidateAccountForAmazonBalanceLoadException>

LoadAmazonBalance

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 with all matching parameters (account, partnerId, amount, and transactionSource), 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.

Request Parameters

Figure 8 LoadBalanceRequest Parameters

Success Response for Barcode Account Type

Figure 9 LoadBalanceResponse success

Success Response for Phone Number Account Type

LoadAmazonBalance Response Parameters

Parameter Name Required Constraints Type
account Yes Object
loadBalanceRequestId Yes Prefixed with partnerId, max 40 Characters String
amount Yes Object
status Yes String
additionalInfo Yes Object

The additionalInfo field is text in JSON format and contains information such as claim code. See example for detail.

Failure Response

LoadAmazonBalanceException includes 4 string parameters:

  • errorCode
  • errorType
  • errorMessage
  • status

LoadAmazonBalance Failure Response example:

<LoadAmazonBalanceException>
 	<errorCode>F100</errorCode>
 	<errorType>GeneralError</errorType>
 	<errorMessage>Amazon Internal Error</errorMessage>
 	<status>FAILURE</status>
</LoadAmazonBalanceException>

Example 1: LoadAmazonBalance request and success response for Barcode type account

Request

POST /LoadAmazonBalance HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.amazon.com x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<LoadAmazonBalanceRequest>
 	<account>
 	 	<id>851432007016085741001033001453</id>
 	 	<type>1</type>
 	</account>
 	<partnerId>PartnerUS</partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
 	<timestamp>1464933146000</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
 	 	<institutionId>A1234</institutionId>
 	 	<sourceDetails>{ "institutionName": "Walgreens",
                         "Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
                         "Phone": "+12061232333"}
        </sourceDetails>
 	</transactionSource>
</LoadAmazonBalanceRequest>

Response

<LoadAmazonBalanceResponse>
    <account>
        <id>851432007016085741001033001453</id>
        <type>1</type>
    </account>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <status>SUCCESS</status>
    <loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
</LoadAmazonBalanceResponse>

Example 2: LoadAmazonBalance request and success response (Phone Number Account Type) with unverified phone number (claim-code need to be manually claimed)

Request

POST /LoadAmazonBalance HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.amazon.com x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<LoadAmazonBalanceRequest>
 	<account>
 	 	<id>2061231234</id>
 	 	<type>4</type>
 	</account>
 	<partnerId>PartnerUS</partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
 	<timestamp>1464933146000</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
 	 	<institutionId>A1234</institutionId>
 	 	<sourceDetails>{ "institutionName": "Walgreens",
                         "Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
                         "Phone": "+12061232333"}
        </sourceDetails>
 	</transactionSource>
</LoadAmazonBalanceRequest>

Success Response

<LoadAmazonBalanceResponse>
 	<account>
 	 	<id>+12061231234</id>
 	 	<type>4</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
 	<additionalInfo>
{"claimcode":"ABCD-EFGH-JK123"}
</additionalInfo>
</LoadAmazonBalanceResponse>

Failure Response

<LoadAmazonBalanceException>
 	<errorCode>F100</errorCode>
 	<errorType>GeneralError</errorType>
 	<errorMessage>Amazon Internal Error</errorMessage>
 	<status>FAILURE</status>
</LoadAmazonBalanceException>

Example 3: LoadAmazonBalance request and success response (Phone Number Account Type) with verified phone number (funds automatically applied/claimed)

Request

POST /LoadAmazonBalance HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.amazon.com x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<LoadAmazonBalanceRequest>
 	<account>
 	 	<id>2061231234</id>
 	 	<type>4</type>
 	</account>
 	<partnerId>PartnerUS</partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
 	<timestamp>1464933146000</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
 	 	<institutionId>A1234</institutionId>
 	 	<sourceDetails>
{"institutionName":"Walgreens", "Address":"1234 Sample Ave N, Unit #10,
Seattle, WA, US, 98101", "Phone":"+12061232333"}
             </sourceDetails>
 	</transactionSource>
</LoadAmazonBalanceRequest>

Response

<LoadAmazonBalanceResponse>
 	<account>
 	 	<id>+12061231234</id>
 	 	<type>4</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
 	<additionalInfo>{"claimcode":"XXXX-XXXXXX-XXXX"}</additionalInfo>
</LoadAmazonBalanceResponse>

LoadAmazonBalance Failure Response example:

Failure Response

<LoadAmazonBalanceException>
 	<errorCode>F100</errorCode>
 	<errorType>GeneralError</errorType>
 	<errorMessage>Amazon Internal Error</errorMessage>
 	<status>FAILURE</status>
</LoadAmazonBalanceException>

LoadAmazonBalance Resend Response example:

Failure Response

<LoadAmazonBalanceException>
    <errorCode>F400</errorCode>
    <errorType>SystemTemporarilyUnavailable</errorType>
    <errorMessage>Amazon system is temporarily not available</errorMessage>
    <status>RESEND</status>
</LoadAmazonBalanceException>

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.

Field in transactionSource Description
sourceId Identifier of a transaction source entity (Example: Store Number or Store ID).
institutionId Identifier of a parent entity of a transaction source (Example: Merchant Id). If parent entity does not exist, copy sourceId.
sourceDetails 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.
institutionParentCompany Name of the parent company for instituitionName. If there is no parent company, institutionName should be repeated.

There are two options for sending store location data to Amazon:

  1. Long form – partner provides specific store location data for each transaction (must include sourceId, institutionId and sourceDetails)
  2. 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.

Sample "long form" payload for transaction source in both XML and JSON format is shown below. Note that sourceDetails must be formatted as a JSON blob. In the JSON example, the JSON blob uses the backslash to escape quotation marks.

Long form example of XML body (note that the sourceDetails value must be formatted as a JSON blob):

<LoadAmazonBalanceRequest>
 	<account>
 	 	<id>851432007016085741001033001453</id>
 	 	<type>1</type>
 	</account>
 	<partnerId>PartnerUS</partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
 	<timestamp>1464933146</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
 	 	<institutionId>A1234</institutionId>
 	 	<sourceDetails>{ "institutionName": "Walgreens",
                         "Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
                         "Phone": "+12061232333"}
        </sourceDetails>
 	</transactionSource>
</LoadAmazonBalanceRequest>

Short form example of transactionSource in JSON body:

{
  "loadBalanceRequestId": "Amxx134565",
  "partnerId": "Amxx1",
  "amount": {
    "currencyCode": "USD",
    "value": 1000
  },
  "account": {
    "id": "5551112222",
    "type": "4"
  },
  "timestamp": 1574704599588,
  "transactionSource": {
    "sourceId": "12345",
    "institutionId": "A123"
  },
  "externalReference": "serviceId:123",
  "notificationDetails": {
    "notificationMessage": "Thank you for loading balance at 12345!"
  }
}

Required for Resellers Only – ProgramID

You can use the programID field to assist in better tracking of client and use case transactions. The programID is an approved identifier provided by Amazon through a submission process where you submit client and use case information through the Incentives API Portal. Approved submissions will receive a reference number that will be added to each transaction call to the API. The programID is alphanumeric and can be up to 100 characters in length.

The below sample message highlights the modifications needed to accommodate the programID field.

<ActivateGiftCardRequest>
  <activationRequestId>Awssb0327141418PM</activationRequestId>
  <partnerId>Awssb</partnerId>
  <cardNumber>1700000005489413</cardNumber>
  <value>
    <currencyCode>USD</currencyCode>
    <amount>10</amount>
  </value>
  <programId>ObY8ftkZQoG3lp2cmEleqg</programId>
</ActivateGiftCardRequest>

Optional: externalReference attribute

You can use the externalReference field to pass your own reference identifier as a string when making claim code requests (up to 100 Unicode characters). The externalReference field may be used to store a convenient mapping to assist you with tracking. For example, you might specify insurance claims, kiosks, customer cases, order Ids, reseller customer accounts, or store information within the externalReference field.

The identifier passed in the externalReference field appears with the transaction in the Incentives API Portal, in the Detailed Activity download.

The following example includes an externalReference field.

POST /CreateGiftCard HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-eu-gamma.amazon.com
x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790
<CreateGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
   <value>
	      <currencyCode>EUR</currencyCode>
	      <amount>1.00</amount>
	  </value>
   <externalReference>889jj14797<externalReference>
</CreateGiftCardRequest>

VoidAmazonBalanceLoad

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.

Request Parameters

Figure 12 VoidAmazonBalanceLoad request diagram

Success Response

Figure 13 VoidAmazonBalanceLoad success response diagram

Failure Response

When the void request fails, a VoidAmazonBalanceLoad exception with these string parameters is returned:

  • errorCode
  • errorType
  • errorMessage
  • status

Example 1: VoidAmazonBalanceLoad request and success response (Barcode Account Type):

Request

POST /VoidAmazonBalance HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.amazon.com x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.VoidAmazonBalance
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<VoidAmazonBalanceLoadRequest>
 	<account>
 	 	<id>851432007016085741001033001453</id>
 	 	<type>1</type>
 	</account>
	 	<partnerId>PartnerUS</partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
 	<timestamp>1464933146000</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
 	 	<institutionId>A1234</institutionId>
 	 	<sourceDetails{"institutionName":"Walgreens",
"Address":"1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
"Phone":"+12061232333"}</sourceDetails>
 	</transactionSource>
 	<voidIfUsed>true</voidIfUsed>
</VoidAmazonBalanceLoadRequest>

Response

<VoidAmazonBalanceLoadResponse>
 	<account>
 	 	<id>851432007016085741001033001453</id>
 	 	<type>1</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
</VoidAmazonBalanceLoadResponse>

  Example 2: VoidAmazonBalanceLoad request and success response (Phone Number Account Type):

Request

POST /VoidAmazonBalance HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.amazon.com x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.VoidAmazonBalance
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<VoidAmazonBalanceLoadRequest>
    <account>
        <id>7574662233</id>
        <type>4</type>
    </account>
    <partnerId>PartnerUS</partnerId>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
    <timestamp>1464933146000</timestamp>
    <transactionSource>
        <sourceId>12344332</sourceId>
        <institutionId>A1234</institutionId>
        <sourceDetails>{"institutionName":"Walgreens",
          "Address":"1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
          "Phone":"+12061232333"}</sourceDetails>
    </transactionSource>
    <voidIfUsed>true</voidIfUsed>
</VoidAmazonBalanceLoadRequest>

Response

<VoidAmazonBalanceLoadResponse>
 	<account>
 	 	<id>+17574662233</id>
 	 	<type>4</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
</VoidAmazonBalanceLoadResponse>

Example 3: VoidAmazonBalanceLoad Failure Response Example:

Failure Response

<VoidAmazonBalanceLoadException>
    <errorCode>F200</errorCode>
    <errorType>LoadBalanceRequestIdDoesNotExist</errorType>
    <errorMessage>Balance Load with provided loadBalanceRequestId does not exist</errorMessage>
    <status>FAILURE</status>
</VoidAmazonBalanceLoadException>

Example 4: VoidAmazonBalanceLoad Resend Response Example:

Failure Response

<VoidAmazonBalanceLoadException>
    <errorCode>F400</errorCode>
    <errorType>SystemTemporarilyUnavailable</errorType>
    <errorMessage>Amazon system is temporarily not available</errorMessage>
    <status>RESEND</status>
</VoidAmazonBalanceLoadException>

GetAvailableFunds

The GetAvailableFunds operation returns the amount of funds currently available in your Amazon Incentives account. It provides an alternative to logging into the Incentives API Portal to view available funds. You can use this operation to monitor your balance and raise alerts.

Request Parameter Description
partnerId A case sensitive unique identifier assigned to your account by Amazon
Response Parameter Description
amount The value of funds currently available in your prepay/postpay account. Note: the Sandbox environment will always return a zero value.
currencyCode The ISO-4217 currency code
status The status of the request. In normal operation, this value is success.
timestamp Date returned in UTC yyyy-MM-dd HH:mm:ss

Sample request

POST
/GetAvailableFunds HTTP/1.1

accept:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.GetAvailableFunds
Authorization:AWS4-HMAC-SHA256 Credential=AKIAIGHKAVYIDBOH3O3A/20170111/us-east-1/AGCODService/aws4_request,SignedHeaders=accept;host;x-amz-date;x-amz-target, Signature=ec86661c1d39f74b5891666505bb7656b172b0d060d911bee3b6a1c29ae17657
{"partnerId": "Aptuk"}

Sample response

{
  "availableFunds":{
    "amount":10.0,
    "currencyCode":"USD"
  },
  "status":"SUCCESS",
  "timestamp":20170915T200959Z
}

Test Data

In order to help with testing during development, we have created test (amazon.com) accounts. Separate accounts are available for the Sandbox and Production environments. See these tokens at https://s3.amazonaws.com/AGCOD/tech_spec/amazon-test-tokens.txt.

Also see mock codes you can use to test how your code handles common request failures.

Digital Signatures – Signing Process

Every request to an Incentives API operation must be digitally signed using your Incentives API security credentials and the Signature Version 4 signature algorithm.

AWS V4 Signing Example

(in us-east-1 region)

Payload to sign:

{
  "account": {
    "id": "0360002414571003423331033001453",
    "type": "1"
  },
  "partnerId": "PartnerUS",
  "amount": {
    "currencyCode": "USD",
    "value": 4570
  },
  "loadBalanceRequestId": "PartnerUSrequestId1",
  "timestamp": 1464933146000,
  "transactionSource": {
    "sourceId": "12344332",
    "institutionId": "A1234",
    "sourceDetails": "{'name': 'Store'}"
  }
}

Hashed Payload

24921f8ae68d62e1d96fd98e33f28da3e52826f43c5fa0389bfa33817e2711a1

Canonical request (include empty lines)

POST
/LoadAmazonBalance
 accept:application/json content-type:application/json host:agcod-v2-gamma.amazon.com x-amz-date:20160708T073147Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance

accept;content-type;host;x-amz-date;x-amz-target
24921f8ae68d62e1d96fd98e33f28da3e52826f43c5fa0389bfa33817e2711a1

Hashed Canonical request

a6a2e4283152cbcc7114409dfbc3dda721663f4bb14b6e34f8e1f71c374f9c14

String to sign

AWS4-HMAC-SHA256
20160708T073147Z
20160708/us-east-1/AGCODService/aws4_request
a6a2e4283152cbcc7114409dfbc3dda721663f4bb14b6e34f8e1f71c374f9c14

Derived signing key

 780860beb9efce461eaee56c38d7f904cf1b803cd9ea6f2c3402415b92af9453

Signature

(Your signature will be different as you have different AWS credentials.)

66bd6a9ee258bcc34b7c0084ef871f2cb734e579b26f62ffce3ca1a33c06074a  

Signed payload

POST /LoadAmazonBalance HTTP/1.1
accept:application/json content-type:application/json host:agcod-v2-gamma.amazon.com x-amz-date:20160708T073147Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance Authorization:AWS4-HMAC-SHA256 Credential=<Access Key Id used for signing>/20160708/useast-1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target,
Signature=66bd6a9ee258bcc34b7c0084ef871f2cb734e579b26f62ffce3ca1a33c06074a
{
  "account": {
    "id": "0360002414571003423331033001453",
    "type": "1"
  },
  "partnerId": "PartnerUS",
  "amount": {
    "currencyCode": "USD",
    "value": 4570
  },
  "loadBalanceRequestId": "PartnerUSrequestId1",
  "timestamp": 1464933146000,
  "transactionSource": {
    "sourceId": "12344332",
    "institutionId": "A1234",
    "sourceDetails": "{'name': 'Store'}"
  }
}

Last updated: May 26, 2021