Console sviluppatore
Ti ringraziamo per la visita. Questa pagina è per il momento disponibile solo in inglese.

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:

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

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.

↑ Back to top

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

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

XML
<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>
JSON
{
    "status": "Success",
    "amount": {
        "currencyCode": "USD",
        "value": 9000
    },
    "account": {
        "id": "amz1.account.123512341234",
        "type": "2"
    },
    "loadBalanceRequestId": "Amazon123456"
}

↑ Back to top

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

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

XML
<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>
JSON
{
    "status":"Success",
    "amount":{
        "currencyCode":"USD",
        "value":1000
    },
    "account":{
        "id":"amz1.account.123512341234",
        "type":"2"
    },
    "loadBalanceRequestId":"Amazon123456"
}

↑ Back to top


Next


Last updated: Dec 16, 2022