Disburse funds with Login and Receive

Set up your Amazon Incentives API account before starting integration. Create Incentives API account.


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:

  • You require immediate and guaranteed disbursements of currency to your customers through an existing web application.
  • You need to ensure that the monetary value is non-transferrable to meet legal or business obligations.
  • You want to send an email notification to customers to notify of a disbursement event.

This page describes how to call the Login and Receive API from your application, and documents the tasks that you can perform with Login and Receive.

Key concepts and basic flowgit status

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 the Login and Receive API. 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:

  1. A application user requests to credit the Gift Card Balance of their Amazon account.
  2. Your application displays a page in the Login with Amazon module that prompts the user for their Amazon credentials.
  3. New Amazon customers can sign up for a new account within the Login with Amazon workflow.
  4. 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.
  5. The module initiates an Authorization Request using the Login with Amazon API.
  6. An id value that uniquely identifies the user account is returned as a JSON object in the response.
  7. Your application calls the LoadAmazonBalance method with the id value in your request body.
  8. The LoadAmazonBalance operation updates the account's Gift Card balance.
  9. 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 the LoadAmazonBalance request.

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

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:

LoadAmazonBalance

The LoadAmazonBalance operation applies funds to the gift card balance of an Amazon customer. Below is a description of the request body parameters.

Request Parameter Description
loadBalanceRequestId A unique identifier to represent the request prefixed with a case sensitive partnerId (max 40 characters). Alphanumeric, should not contain characters
partnerId A case sensitive unique identifier to represent your account
amount The information that identifies an active Amazon customer provided by the Login with Amazon API. For Sandbox requests use amzn1.account.AFEM4VZRQQMBAAMVQEP3BPBH7OYQ
currencyCode The ISO-4217 currency code
value 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 The information that identifies an active Amazon customer provided by the Login with Amazon API. For Sandbox requests use amzn1.account.AFEM4VZRQQMBAAMVQEP3BPBH7OYQ
id 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 Specifies the type of identifier. Valid type value = 2 (Customer ID)
transactionSource Data to identify the transaction source
sourceId Identifier of the transaction. This metadata will display in the customers Amazon balance ledger. E.g. "Gift Card from (Max 40 Unicode chars)
externalReference A text field you can use to describe the request when viewed in the Incentives API Portal. (Max 100 Unicode characters)
notificationDetails Optional. A description of the reason for funds disbursement.
notificationMessage Optional. A string that will appear in the confirmation email (Max 250 Unicode characters).

Sample request

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

Sample response

{
    "status": "Success",
    "amount": {
        "currencyCode": "USD",
        "value": 9000
    },
    "account": {
        "id": "amz1.account.123512341234",
        "type": "2"
    },
    "loadBalanceRequestId": "Amazon123456"
}

#### 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](https://s3-us-west-2.amazonaws.com/incentives-api-setup/index.html#launch). 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.

```json
{   
"loadBalanceRequestId":"Amazon123456",
    "partnerId":"Amazon",
    "amount":{
        "currencyCode":"USD",
        "value": 1000
    },
    "account":{
        "id":"amz1.account.123512341234",
        "type":"2"
    },
  "programId": "ObY8ftkZQoG3lp2cmEleqg",
    "externalReference":"serviceId:123",
    "notificationDetails":{
        "notificationMessage":"Thank you for your purchase!"
    }
}

Optional: external reference 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

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.

Parameter Description
loadBalanceRequestId The unique identifier used in a previously successful LoadAmazonBalance request
partnerId A case sensitive unique identifier to represent your account
amount The monetary amount that was provided in a LoadAmazonBalance request
currencyCode The ISO-4217 currency code used
value The monetary value of the original transaction to be removed from the Amazon customer GC balance 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 is 231 not 23100.
account The information that identifies an active Amazon customer provided by the Login with Amazon API. For Sandbox requests use amzn1.account.AFEM4VZRQQMBAAMVQEP3BPBH7OYQ
id The unique identification value for one Amazon customer account. Originally returned as a JSON HTTP response from the Login with Amazon API.
type Specifies the type of identifier. Must be set to 2 (Customer ID)

Sample request

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

Sample response

{
    "status":"Success",
    "amount":{
        "currencyCode":"USD",
        "value":1000
    },
    "account":{
        "id":"amz1.account.123512341234",
        "type":"2"
    },
    "loadBalanceRequestId":"Amazon123456"
}

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
}

Testing requests

To test your integration, you can simulate a response from the API by creating a mock request. The response from the mock request is controlled by the id parameter. For example, passing in id F0000 will simulate a Success response, whereas passing in id F1000 will simulate a general error. Refer to the Error Codes for a complete list of available responses. The following are the required (minimum) parameters to invoke a mock request:

{
  "loadBalanceRequestId": "Amazon123456",
  "account": {
    "id": "F2044",
    "type": "0"
  }
}

Sample mock request

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":"",
    "amount":{
        "currencyCode":"",
        "value":""
    },
    "account":{
        "id":"F2044",
        "type":"0"
    },
    "transactionSource":{
        "sourceId":""
    },
    "externalReference":"",
    "notificationDetails":{
        "notificationMessage":""
    }
}

Sample mock response

{
    "errorCode": "F2044",
    "errorMessage": "Source Id is too long. Received 41 characters. Maximum   
number of characters is 40",
    "errorType": "sourceIdTooLong",
    "status": "FAILURE"
}

Login and Receive Test Script

You can verify some components of your integration using the Sandbox environment. However, complete end-to-end testing of your applications user experience can only be completed using the production API account.

Sandbox: Simulate a response from the LoadAmazonBalance API by creating a "mock" request.

Production:

  • Use the Login with Amazon component to receive a valid customer.id value for an Amazon customer account.
  • Call the LoadAmazonBalance and VoidAmazonBalanceLoad endpoints.
  • Complete end-to-end testing of your application and user experience.
Test Action Expected Result
1. Create amazon.com (or local) test accounts Create a set of Amazon accounts in the region for testing the Load Balance API call. Accounts are created.
2. Validate Login with Amazon module 1. Validate successful login
2. Valid authorization token
3. Validate user.id is returned
For each account,
1. Login is successful
2. Authorization token is provided
3. A unique user.id value is provided
3. Validate/ LoadAmazonBalance Use your application UX workflow to invoke this method for a test account that you created in step (1) for a monetary value
2. Log into the Amazon account and select View the Gift Card Balance
4. Validate notification message displays on the confirmation email and matches the notificationMessage parameter inserted into the API request.
5. Validate email was sent to email address registered with amazon.com account
1. status = success is returned for each call to Load
2. Account gift card balance matches the loaded amount
3. Notification message matches provided message
4. Email message received
5. Value specified in amount.value debited from account in the Incentives API Portal
4. Validate/ LoadAmazonBalance idempotency 1. Invoke the method multiple times with the same loadBalanceRequestId and user.id
2. Log into amazon account
3. View gift card balance
1. status = success returned for each call
2. The amount.value from the first call is applied but subsequent calls to the LoadAmazonBalance method were ignored
5. Validate/ VoidAmazonBalanceLoad 1. Use previously created loadBalanceRequestId to void a transaction
2. Log into amazon.com account for applicable user.id
3. Balance has been voided
4. Validate email was sent to email address registered with amazon.com account
5. Log into Incentives API Portal and view transaction
1. status = success is returned for each call to Void
2. Account gift card balance matches the loaded amount
3. Notification message matches provided message
4. Email message received
5. Funds specified in amount.value refunded back to account in Incentives API Portal

Performance

The API is designed to process transactions at a maximum rate of 10 transactions per second (TPS).

Error Codes

We group types of errors into five groups. For example, when the cause is on the client side the API responds with an F2xx error.

Error Code Description
F100 Amazon Internal Error
F200 Invalid Request Error (something is incorrect in the request payload)
F300 Account related Error (typically due to onboarding, authentication, access related issues, etc.)
F400 Retry able Error (Temporary issue). See Error Handling
F500 Unknown Error
Error Type
Error Code / Mock Code
Description
GeneralError
F100 / F1000
Amazon internal error
BalanceLoadCannotBeVoided
F100 / F1001
Unable to void balance load due to Amazon internal error
InvalidRequestInput
F200 / F2000
The request body is null
InvalidPartnerIdInput
F200 / F2002
partnerId cannot be null
InvalidAmountInput
F200 / F2003
Amount cannot be null
InvalidAmountValue
F200 / F2004
Amount must be greater than 0
InvalidCurrencyCodeInput
F200 / F2005
Currency code cannot be null
InvalidRequestIdInput
F200 / F2006
loadBalanceRequestId cannot be null
MaxAmountExceeded
F200 / F2015
Amount greater than maximum value allowed in the national market segment (e.g. $500 in US)
FractionalAmountNotAllowed
F200 / F2017
Fractional amount not allowed in the currency (e.g. JP)
RequestIdTooLong
F200 / F2021
loadBalanceRequestId greater than 40 characters
RequestIdMustStartWithPartnerName
F200 / F2022
loadBalanceRequestId must begin with partnerId
InvalidAccountType
F200 / F2033
Account type provided in request is undefined
UndefinedAccountId
F200 / F2034
accountId provided in request does not exist in Amazon system
AccountIdNotInValidStatus
F200 / F2035
accountId not in valid status for requested operation (e.g. accountId is deactivated)
InvalidCurrencyInMarketplace
F200 / F2036
Currency code is not supported in national market segment where accountId is created
AmountBelowMinThreshold
F200 / F2037
Amount below minimum required amount
LoadBalanceRequestIdAlreadyUsed
F200 / F2038
loadBalanceRequestId provided in load API has already been used (e.g. when idempotency check of the given loadBalanceRequestId fails)
LoadBalanceRequestIdDoesNotExist
F200 / F2039
Load request with loadBalanceRequestId provided in the void API does not exist
RequestMismatchFromLoadRequest
F200 / F2040
Parameters passed in a void request do not match the parameters of a Load request
BalanceLoadCannotBeVoided
F200 / F2041
When the loaded balance has been used and voidIfUsed flag is false
ExternalReferenceTooLong
F200 / F2042
The value used exceeds the max number of Unicode characters
NotificationMessageTooLong
F200 / F2043
The value used in the notificationDetails parameter exceeds 250 Unicode characters
SourceIdTooLong
F200 / F2044
The value used in the sourceID field exceeded the max number of 40 Unicode characters
BalanceLoadCannotBeVoided
F200 / F2045
Unable to void balance, request arrived beyond the time limit
InvalidPartnerId
F300 / F3000
partnerId used in API request does not exist in Amazon system
InvalidAccessKey
F300 / F3001
Security access key used to sign the request does not exist in Amazon system (not applicable in China)
InvalidAccessKey
F300 / F3001
Access key (in China) used to sign API request does not exist in Amazon system
AccessDenied
F300 / F3002
The account is blocked
InsufficientFunds
F300 / F3003
The account does not have sufficient funds to issue the request amount (each partner is given certain credit limit and the partner can issue balance only up to the credit limit. Credit limit is reset when the partner makes a payment)
IssuanceCapExceeded
F300 / F3004
The balance issuance limit defined by the contract has been reached for the specified time period
OperationNotPermitted
F300 / F3006
The request is denied. Partner does not have permission to call the API (happens when non Amazon Balance Load distribution partner tries to call an Amazon Balance Load API before onboarding)
ActiveContractNotFound
F300 / F3009
Partner account set up is not complete
CustomerSurpassedDailyVelocityLimit
F300 / F3010
Customer has exceeded daily velocity limit
CustomerAccountBlocked
F300 / F3011
This Amazon account is not allowed to perform this transaction
SystemTemporarilyUnavailable
F400 / F4000
Amazon system is temporarily not available. See Error Handling
GeneralError
F500 / F5000
Unknown error

Last updated: May 26, 2021