开发人员控制台
感谢您的访问。此页面目前仅提供英语版本。我们正在开发中文版本。谢谢您的理解。

Receive funds at brick and mortar sites

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.

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. 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
  2. Phone Number - 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.

↑ Back to top

Key Concepts

Barcode Account Type

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

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:

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

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:

  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 payload for transaction source in both XML and JSON format is shown below.

JSON Long Form
{
  "LoadAmazonBalanceRequest": {
    "account": {
      "id": 851432007016085741000205631269,
      "type": 1
    },
    "partnerId": "Bus21",
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "loadBalanceRequestId": "Bus21requestId1",
    "timestamp": 1464933146,
    "transactionSource": {
      "sourceDetails": "{ "institutionName": "Walgreens","Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101","Phone": "+12061232333"}"
    }
  }
}
XML Long Form
<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 0.01 - 5000.00 10 Years
Canada CAD 0.01 - 5000.00 N/A
France EUR 0.15 - 5000.00 10 Years
Netherlands EUR 1.00 - 5000.00 10 Years
Germany EUR 0.15 - 5000.00 10 Years
Italy EUR 0.01 - 5000.00 10 Years
Japan JPY 15.00 - 500000.00 10 Years
KSA SAR 1.00 - 5000.00 10 Years
Mexico MXN 5.00 - 5000.00 5 Years
Poland PLN 1.00 - 21000.00 10 Years
Spain EUR 0.15 - 5000.00 10 Years
Singapore SGD 0.01 - 500.00 10 Years
Sweden SEK 1.00 - 1000.00 10 Years
Turkey TRY 1.00 - 5000.00 10 Years
United Arab Emirates AED 1.00 - 6000.00 10 Years
United Kingdom GBP 0.01 - 5000.00 10 Years
United States USD 0.01 - 2000.00 N/A

↑ Back to top

Operations

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

↑ Back to top

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

↑ Back to top

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.

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

Example Request

Barcode
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>Bus21</partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
    <timestamp>1464933146000</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
 	 	<institutionId>example12344332</institutionId>
             <sourceDetails>
                 {"institutionName":"Walgreens", "Address":"1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101", "Phone":"+12061232333"}
             </sourceDetails>
 	</transactionSource>
</ValidateAccountForAmazonBalanceLoadRequest>
Phone
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>Bus21</partnerId>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <loadBalanceRequestId>Bus21requestId1</loadBalanceRequestId>
    <timestamp>1464933146000</timestamp>
    <transactionSource>
        <sourceId>12344332</sourceId>
        <institutionId>example12344332</institutionId>
        <sourceDetails>{ "institutionName": "Walgreens",
                         "Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
                         "Phone": "+12061232333"}
        </sourceDetails>
    </transactionSource>
</LoadAmazonBalanceRequest>
Barcode
{
  "ValidateAccountForAmazonBalanceLoadRequest": {
    "account": {
      "id": 851432007016085741000205631269,
      "type": 1
    },
    "partnerId": "Bus21",
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "timestamp": 1464933146000,
    "transactionSource": {
      "sourceId": 12344332,
      "institutionId": "example12344332",
      "sourceDetails": "{"institutionName":"Walgreens", "Address":"1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101", "Phone":"+12061232333"}"
    }
  }
}
Phone
{
  "LoadAmazonBalanceRequest": {
    "account": {
      "id": 2061231234,
      "type": 4
    },
    "partnerId": "Bus21",
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "loadBalanceRequestId": "Bus21RequestId1",
    "timestamp": 1464933146000,
    "transactionSource": {
      "sourceId": 12344332,
      "institutionId": "example12344332",
      "sourceDetails": "{ "institutionName": "Walgreens","Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101","Phone": "+12061232333"}"
    }
  }
}

↑ Back to top

Responses

Response Parameters

Request Parameter Constraints Type Description
status String Outcome of this operation. Success Value: SUCCESS
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)

Example Response

Barcode
<ValidateAccountForAmazonBalanceLoadResponse>
 	<account>
 	 	<id>851432007016085741001033001453</id>
 	 	<type>1</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
</ValidateAccountForAmazonBalanceLoadResponse>  
Phone
<ValidateAccountForAmazonBalanceLoadResponse>
 	<account>
 	 	<id>+12061231234</id>
 	 	<type>4</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
</ValidateAccountForAmazonBalanceLoadResponse> 
Phone (Partial)
<ValidateAccountForAmazonBalanceLoadResponse>
 	<account>
 	 	<id>+12061231235</id>
 	 	<type>4</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>PARTIAL_SUCCESS</status>
</ValidateAccountForAmazonBalanceLoadResponse>  
Barcode
{
  "ValidateAccountForAmazonBalanceLoadResponse": {
    "account": {
      "id":851432007016085741000205631269,
      "type": 1
    },
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "status": "SUCCESS"
  }
}
Phone
{
  "ValidateAccountForAmazonBalanceLoadResponse": {
    "account": {
      "id": 12061231234,
      "type": 4
    },
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "status": "SUCCESS"
  }
}
Phone (Partial)
{
  "ValidateAccountForAmazonBalanceLoadResponse": {
    "account": {
      "id": 12061231235,
      "type": 4
    },
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "status": "PARTIAL_SUCCESS"
  }
}

↑ Back to top

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

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

Example Request

Barcode
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>Bus21</partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<loadBalanceRequestId>Bus21requestId1</loadBalanceRequestId>
 	<timestamp>1464933146000</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
 	 	<institutionId>example12344332</institutionId>
 	 	<sourceDetails>{ "institutionName": "Walgreens",
                         "Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
                         "Phone": "+12061232333"}
        </sourceDetails>
 	</transactionSource>
</LoadAmazonBalanceRequest>
Phone
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>Bus21</partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<loadBalanceRequestId>Bus21requestId1</loadBalanceRequestId>
 	<timestamp>1464933146000</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
 	 	<institutionId>example12344332</institutionId>
 	 	<sourceDetails>{ "institutionName": "Walgreens",
                         "Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
                         "Phone": "+12061232333"}
        </sourceDetails>
 	</transactionSource>
</LoadAmazonBalanceRequest>
Barcode
{
  "LoadAmazonBalanceRequest": {
    "account": {
      "id":851432007016085741000205631269,
      "type": 1
    },
    "partnerId": "Bus21",
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "loadBalanceRequestId": "Bus21requestId1",
    "timestamp": 1464933146000,
    "transactionSource": {
      "sourceId": 12344332,
      "institutionId": "example12344332",
      "sourceDetails": "{ "institutionName": "Walgreens","Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101","Phone": "+12061232333"}"
    }
  }
}
Phone
{
  "LoadAmazonBalanceRequest": {
    "account": {
      "id": 2061231234,
      "type": 4
    },
    "partnerId": "Bus21",
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "loadBalanceRequestId": "Bus21requestId1",
    "timestamp": 1464933146000,
    "transactionSource": {
      "sourceId": 12344332,
      "institutionId": "example12344332",
      "sourceDetails": "{ "institutionName": "Walgreens","Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101","Phone": "+12061232333"}"
    }
  }
}

↑ Back to top

Responses

Response Parameters

Request Parameter Constraints Type Description
status String Outcome of this operation. Success Value: SUCCESS
loadBalanceRequestId 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
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)

Example Response

Barcode
<LoadAmazonBalanceResponse>
    <account>
        <id>851432007016085741001033001453</id>
        <type>1</type>
    </account>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <status>SUCCESS</status>
    <loadBalanceRequestId>Bus21requestId1</loadBalanceRequestId>
</LoadAmazonBalanceResponse>
Phone
<LoadAmazonBalanceResponse>
 	<account>
 	 	<id>+12061231234</id>
 	 	<type>4</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
 	<loadBalanceRequestId>Bus21requestId1</loadBalanceRequestId>
 	<additionalInfo>{"claimcode":"ABCD-EFGH-JK123"}</additionalInfo>
</LoadAmazonBalanceResponse>
Phone (Partial)
<LoadAmazonBalanceResponse>
 	<account>
 	 	<id>+12061231234</id>
 	 	<type>4</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
 	<loadBalanceRequestId>Bus21requestId1</loadBalanceRequestId>
 	<additionalInfo>{"claimcode":"XXXX-XXXXXX-XXXX"}</additionalInfo>
</LoadAmazonBalanceResponse>
Barcode
{
  "LoadAmazonBalanceResponse": {
    "account": {
      "id": 851432007016085741000205631269,
      "type": 1
    },
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "status": "SUCCESS",
    "loadBalanceRequestId": "Bus21requestId1"
  }
}
Phone
{
  "LoadAmazonBalanceResponse": {
    "account": {
      "id": 12061231234,
      "type": 4
    },
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "status": "SUCCESS",
    "loadBalanceRequestId": "Bus21requestId1",
    "additionalInfo": "{"claimcode":"XXXX-XXXXXX-XXXX"}"
  }
}
Phone (Partial)
{
  "LoadAmazonBalanceResponse": {
    "account": {
      "id": 12061231234,
      "type": 4
    },
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "status": "SUCCESS",
    "loadBalanceRequestId": "Bus21requestId1",
    "additionalInfo": "{"claimcode":"XXXX-XXXXXX-XXXX"}"
  }
}

↑ Back to top

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.

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

Example Request

Barcode
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>Bus21</partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<loadBalanceRequestId>Bus21requestId1</loadBalanceRequestId>
 	<timestamp>1464933146000</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
 	 	<institutionId>example12344332</institutionId>
 	 	<sourceDetails>{"institutionName":"Walgreens","Address":"1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101","Phone":"+12061232333"}</sourceDetails>
 	</transactionSource>
 	<voidIfUsed>true</voidIfUsed>
</VoidAmazonBalanceLoadRequest>
Phone
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>Bus21</partnerId>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <loadBalanceRequestId>Bus21requestId1</loadBalanceRequestId>
    <timestamp>1464933146000</timestamp>
    <transactionSource>
        <sourceId>12344332</sourceId>
        <institutionId>example12344332</institutionId>
        <sourceDetails>{"institutionName":"Walgreens","Address":"1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101","Phone":"+12061232333"}</sourceDetails>
    </transactionSource>
    <voidIfUsed>true</voidIfUsed>
</VoidAmazonBalanceLoadRequest>
Barcode
{
  "VoidAmazonBalanceLoadRequest": {
    "account": {
      "id": 851432007016085741000205631269,
      "type": 1
    },
    "partnerId": "Bus21",
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "loadBalanceRequestId": "Bus21requestId1",
    "timestamp": 1464933146000,
    "transactionSource": {
      "sourceId": 12344332,
      "institutionId": "example12344332",
      "sourceDetails": "{"institutionName":"Walgreens","Address":"1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101","Phone":"+12061232333"}"
    },
    "voidIfUsed": true
  }
}
Phone
{
  "VoidAmazonBalanceLoadRequest": {
    "account": {
      "id": 7574662233,
      "type": 4
    },
    "partnerId": "Bus21",
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "loadBalanceRequestId": "Bus21requestId1",
    "timestamp": 1464933146000,
    "transactionSource": {
      "sourceId": 12344332,
      "institutionId": "example12344332",
      "sourceDetails": "{"institutionName":"Walgreens","Address":"1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101","Phone":"+12061232333"}"
    },
    "voidIfUsed": true
  }
}

↑ Back to top

Responses

Response Parameters

Request Parameter Constraints Type Description
status String Outcome of this operation. Success Value: SUCCESS
loadBalanceRequestId 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
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)

Example Response

Barcode
<VoidAmazonBalanceLoadResponse>
 	<account>
 	 	<id>851432007016085741001033001453</id>
 	 	<type>1</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
 	<loadBalanceRequestId>Bus21requestId1</loadBalanceRequestId>
</VoidAmazonBalanceLoadResponse>
Phone
<VoidAmazonBalanceLoadResponse>
 	<account>
 	 	<id>+17574662233</id>
 	 	<type>4</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
 	<loadBalanceRequestId>Bus21requestId1</loadBalanceRequestId>
</VoidAmazonBalanceLoadResponse>
Barcode
{
  "VoidAmazonBalanceLoadResponse": {
    "account": {
      "id": 851432007016085741000205631269,
      "type": 1
    },
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "status": "SUCCESS",
    "loadBalanceRequestId": "Bus21requestId1"
  }
}
Phone
{
  "VoidAmazonBalanceLoadResponse": {
    "account": {
      "id": 17574662233,
      "type": 4
    },
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "status": "SUCCESS",
    "loadBalanceRequestId": "Bus21requestId1"
  }
}

↑ Back to top


Next


Last updated: Oct 12, 2021