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
• Key Concepts
  • Barcode Account Type
  • Phone Number Account Type
  • Additional requirements at Brick and Mortar locations
  • Minimum and Maximum Amount per Transaction per Country
• Operations
  • Two-Step Balance Load Process
  • One-Step Balance Load Process
• ValidateAccountForAmazonBalanceLoad
  • Requests
  • Responses
• LoadAmazonBalance
  • Requests
  • Responses
• VoidAmazonBalanceLoad
  • Requests
  • Responses

Amazon Cash

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)

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:

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

Default Instruction Text

If the POS system cannot change the receipt content, this text should appear:

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.

• Long Form
  JSON XML
• Short Form
  JSON XML

{
  "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"}"
    }
  }
}

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

{
  "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!"
  }
}

<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

↑ Back to top

Operations

Below are the operations contained within the balance load API.

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

Example Request

• XML
  Barcode Phone
• JSON
  Barcode 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=

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

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>

{
  "ValidateAccountForAmazonBalanceLoadRequest": {
    "account": {
      "id": "851432007016085741000205631269",
      "type": "1"
    },
    "partnerId": "Bus21",
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "timestamp": 1464933146000,
    "transactionSource": {
      "sourceId": "12344332",
      "institutionId": "example12344332",
    }
  }
}

{
  "LoadAmazonBalanceRequest": {
    "account": {
      "id": "2061231234",
      "type": "4"
    },
    "partnerId": "Bus21",
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "loadBalanceRequestId": "Bus21RequestId1",
    "timestamp": 1464933146000,
    "transactionSource": {
      "sourceId": "12344332",
      "institutionId": "example12344332",
    }
  }
}

↑ Back to top

Responses

Response Parameters

Example Response

• XML
  Barcode Phone Phone (Partial)
• JSON
  Barcode Phone Phone (Partial)

<ValidateAccountForAmazonBalanceLoadResponse>
 	<account>
 	 	<id>851432007016085741001033001453</id>
 	 	<type>1</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>SUCCESS</status>
</ValidateAccountForAmazonBalanceLoadResponse>

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

{
  "ValidateAccountForAmazonBalanceLoadResponse": {
    "account": {
      "id":851432007016085741000205631269,
      "type": 1
    },
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "status": "SUCCESS"
  }
}

{
  "ValidateAccountForAmazonBalanceLoadResponse": {
    "account": {
      "id": 12061231234,
      "type": 4
    },
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "status": "SUCCESS"
  }
}

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

Example Request

• XML
  Barcode Phone
• JSON
  Barcode 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>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>

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>

{
  "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!"
  }
}

{
  "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!"
  }
}

↑ Back to top

Responses

Response Parameters

Example Response

• XML
  Barcode Phone Phone (Partial)
• JSON
  Barcode Phone Phone (Partial)

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

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

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

{
  "LoadAmazonBalanceResponse": {
    "account": {
      "id": 851432007016085741000205631269,
      "type": 1
    },
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "status": "SUCCESS",
    "loadBalanceRequestId": "Bus21requestId1"
  }
}

{
  "LoadAmazonBalanceResponse": {
    "account": {
      "id": 12061231234,
      "type": 4
    },
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "status": "SUCCESS",
    "loadBalanceRequestId": "Bus21requestId1",
    "additionalInfo": "{"claimcode":"XXXX-XXXXXX-XXXX"}"
  }
}

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

Example Request

• XML
  Barcode Phone
• JSON
  Barcode 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>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>

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>

{
  "VoidAmazonBalanceLoadRequest": {
    "account": {
      "id": "851432007016085741000205631269",
      "type": "1"
    },
    "partnerId": "Bus21",
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "loadBalanceRequestId": "Bus21requestId1",
    "timestamp": 1464933146000,
    "transactionSource": {
      "sourceId": "12344332",
      "institutionId": "example12344332"
    },
    "voidIfUsed": true
  }
}

{
  "VoidAmazonBalanceLoadRequest": {
    "account": {
      "id": "7574662233",
      "type": "4"
    },
    "partnerId": "Bus21",
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "loadBalanceRequestId": "Bus21requestId1",
    "timestamp": 1464933146000,
    "transactionSource": {
      "sourceId": "12344332",
      "institutionId": "example12344332"
    },
    "voidIfUsed": true
  }
}

↑ Back to top

Responses

Response Parameters

Example Response

• XML
  Barcode Phone
• JSON
  Barcode Phone

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

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

{
  "VoidAmazonBalanceLoadResponse": {
    "account": {
      "id": 851432007016085741000205631269,
      "type": 1
    },
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "status": "SUCCESS",
    "loadBalanceRequestId": "Bus21requestId1"
  }
}

{
  "VoidAmazonBalanceLoadResponse": {
    "account": {
      "id": 17574662233,
      "type": 4
    },
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "status": "SUCCESS",
    "loadBalanceRequestId": "Bus21requestId1"
  }
}

↑ Back to top

Next

• Prepare to launch with our Test Plan Guide

Last updated: Oct 12, 2021