Disburse funds with Login and Receive
This page describes the processes of integrating into the Amazon Gift Card On Demand(AGCOD) using our LoadAmazonBalance
service combined within Login with Amazon We call this process Login and Receive.
The Login and Receive web service provides an API to disburse funds to a new or existing Amazon customer. A disbursement adds a monetary value to the Gift Card Balance portion of an Amazon customer's account in real time. This REST-based web service is part of the Incentives API, which is a set of services that support operations for Amazon Gift Cards.
Call Login and Receive for the following use cases:
Key Concepts
Basic Login with Amazon workflow
The Login and Receive API uses the Login with Amazon web service, which allows users to authenticate their Amazon account using their Amazon account credentials within your browser-based or mobile application. Once authentication is complete, the Login with Amazon service provides your application with a user identifier you can use as an input parameter to LoadAmazonBalance
. Together, these services allow a seamless experience for end users.
Login with Amazon offers customizations to align with your preferred user experience, including an SDK. Visit Login with Amazon in the Developer Portal for more information.
Below is a description of the application workflow for Login and Receive:
- An application user requests to credit the Gift Card Balance of their Amazon account.
- Your application displays a page in the Login with Amazon module that prompts the user for their Amazon credentials.
- New Amazon customers can sign up for a new account within the Login with Amazon workflow.
- If your code requests the Amazon customer's name, email address, or postal/zip code, the Login with Amazon workflow seeks the Amazon customer's consent to share this information with your service.
- The module initiates an Authorization Request using the Login with Amazon API.
- An
id
value that uniquely identifies the user account is returned as a JSON object in the response. - Your application calls the
LoadAmazonBalance
method with theid
value in your request body. - The
LoadAmazonBalance
operation updates the account's Gift Card balance. - Amazon sends an email confirmation to the email address associated with the Amazon customer account when the funds have been successfully applied or voided in the customer’s Account gift card balance. This email will contain text specified in the
notificationMessage
parameter of theLoadAmazonBalance
request.
Cancel
or by closing the popup window (if this UX method is used).Transaction Amount Limits
Country | Currency Code | Range | Expiration |
---|---|---|---|
Australia | AUD | 0.01 - 5000.00 | 10 Years |
Belgium | EUR | 1.00 - 5000.00 | 10 Years |
Canada | CAD | 0.01 - 5000.00 | N/A |
Egypt | EUR | 1.00 - 6000.00 | 10 Years |
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 | 1.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 |
South Africa | ZAR | 1.00 - 6000.00 | 10 Years |
Sweden | SEK | 1.00 - 10000.00 | 10 Years |
Turkey | TRY | 1.00 - 5000.00 | 10 Years |
United Arab Emirates (see Note below) | 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 |
Prerequisites
Complete these setup steps to use Login and Receive:
- Follow instructions in the Incentives API Integration setup guide to establish an account and agree to a contract with Amazon Incentives.
- Integrate your web or mobile application with the Login with Amazon web service to provide authentication and (optionally) access to user profile data. To learn more about how to integrate your application with Login with Amazon, follow steps in the Login with Amazon Developer Center. To use Login with Amazon in your mobile app, you must use the Login with Amazon mobile SDK. While a browser-based interaction is technically possible from a mobile app, we prohibit this for security reasons.
- The Sandbox is a test environment you will use when developing and testing your application. Contact your Amazon account manager to get access credentials for a Sandbox. Once Sandbox access has been granted, you can begin development and testing using the Partner ID value they provide. Endpoint base URLs to access the Sandbox are provided in the Regions and Endpoints section. With Sandbox access, you can develop and test your code by following instructions in the Amazon Incentives API Integration setup guide.
Performance
The API is designed to process transactions at a maximum rate of 10 transactions per second (TPS).
Login and Receive API
Your application interacts with Login and Receive by making synchronous requests to the web service. This section describes the structure of a request and the available operations. Invoking an operation consists of sending an HTTP request to an Incentives API endpoint and waiting for the response. A REST HTTP request to the gateway contains a request method, URI, headers, and a body presented in either XML or JSON. The response contains an HTTP status code, response headers, and a response body. Each API call will need to be signed using your security credentials and the AWS Signature Version 4 Signing Process.
Below is a description of each API operation, request headers and associated parameters.
Operations
The following operations are supported:
Operation | Description |
---|---|
LoadAmazonBalance |
Puts funds directly into the users Gift Card Balance portion of an Amazon customer's account in real time. |
VoidAmazonBalanceLoad |
Within 15 minutes of a LoadAmazonBalance call, you can void the balance load if the balance is unused |
LoadAmazonBalance
The LoadAmazonBalance operation applies funds to the gift card balance of an Amazon customer. Below is a description of the request body parameters.
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 | String | Specifies the type of identifier. Valid type value = 2 (Customer ID) | ||
transactionSource
|
Yes | Object | Data to identify the transaction source | |||
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) | ||
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
<LoadAmazonBalanceRequest>
<loadBalanceRequestId>Amazon123456</loadBalanceRequestId>
<partnerId>Amazon</partnerId>
<amount>
<currencyCode>USD</currencyCode>
<value>1000</value>
</amount>
<account>
<id>amz1.account.123512341234</id>
<type>2</type>
</account>
<transactionSource>
<sourceId>Customer Service</sourceId>
</transactionSource>
<externalReference>serviceId:123</externalReference>
<notificationDetails>
<notificationMessage>Thank you for your purchase!</notificationMessage>
</notificationDetails>
</LoadAmazonBalanceRequest>
POST
/LoadAmazonBalance HTTP/1.1
accept:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance
Authorization:AWS4-HMAC-SHA256 Credential=AKIAIGHKAVYIDBOH3O3A/20170111/us-east-1/AGCODService/aws4_request,SignedHeaders=accept;host;x-amz-date;x-amz-target, Signature=ec86661c1d39f74b5891666505bb7656b172b0d060d911bee3b6a1c29ae17657
{ "loadBalanceRequestId":"Amazon123456",
"partnerId":"Amazon",
"amount":{
"currencyCode":"USD",
"value": 1000
},
"account":{
"id":"amz1.account.123512341234",
"type":"2"
},
"transactionSource":{
"sourceId":"Customer Service"
},
"externalReference":"serviceId:123",
"notificationDetails":{
"notificationMessage":"Thank you for your purchase!"
}
}
Response
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 | String | Specifies the type of identifier. Valid type value = 2 (Customer ID) |
Example Response
<LoadAmazonBalance>
<status>Success</status>
<amount>
<currencyCode>USD</currencyCode>
<value>9000</value>
</amount>
<account>
<id>amz1.account.123512341234</id>
<type>2</type>
</account>
<loadBalanceRequestId>Amazon123456</loadBalanceRequestId>
</LoadAmazonBalance>
{
"status": "Success",
"amount": {
"currencyCode": "USD",
"value": 9000
},
"account": {
"id": "amz1.account.123512341234",
"type": "2"
},
"loadBalanceRequestId": "Amazon123456"
}
VoidAmazonBalanceLoad
This operation voids a previously successful LoadAmazonBalance request if the issued Claim Code funds have not already been used by the receiving Amazon customer. This operation can be run up to 15 minutes from the original call to LoadAmazonBalance. After that time, a call to VoidAmazonBalanceLoad will do nothing.
Your application must call this operation when you cannot confirm that a previous AmazonBalanceLoad request was successful. For example, if your call to LoadAmazonBalance does not return any result, call VoidAmazonBalanceLoad to ensure that no funds are added to the Amazon customer’s gift card balance.
Below is a description of the request body parameters.
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 | String | Specifies the type of identifier. Valid type value = 2 (Customer ID) |
Sample request
<VoidAmazonBalanceLoadRequest>
<loadBalanceRequestId>Amazon123456</loadBalanceRequestId>
<partnerId>Amazon</partnerId>
<amount>
<currencyCode>USD</currencyCode>
<value>1000</value>
</amount>
<account>
<id>amz1.account.123512341234</id>
<type>2</type>
</account>
</VoidAmazonBalanceLoadRequest>
POST
/VoidAmazonBalanceLoad HTTP/1.1
accept:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.VoidAmazonBalanceLoad
Authorization:AWS4-HMAC-SHA256 Credential=AKIAIGHKAVYIDBOH3O3A/20170111/us-east-1/AGCODService/aws4_request,SignedHeaders=accept;host;x-amz-date;x-amz-target, Signature=ec86661c1d39f74b5891666505bb7656b172b0d060d911bee3b6a1c29ae17657
{
"loadBalanceRequestId": "Amazon123456",
"partnerId": "Amazon",
"amount": {
"currencyCode": "USD",
"value": 1000
},
"account": {
"id": "amz1.account.123512341234",
"type": "2"
}
}
Response
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 | Sting | Specifies the type of identifier. Valid type value = 2 (Customer ID) |
Example Response
<VoidAmazonBalanceLoad>
<status>Success</status>
<amount>
<currencyCode>USD</currencyCode>
<value>1000</value>
</amount>
<account>
<id>amz1.account.123512341234</id>
<type>2</type>
</account>
<loadBalanceRequestId>Amazon123456</loadBalanceRequestId>
</VoidAmazonBalanceLoad>
{
"status":"Success",
"amount":{
"currencyCode":"USD",
"value":1000
},
"account":{
"id":"amz1.account.123512341234",
"type":"2"
},
"loadBalanceRequestId":"Amazon123456"
}
Next
- Prepare to launch with our Test Plan Guide
Last updated: Dec 16, 2022