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
  • Transaction Amount Limits
  • Prerequisites
  • Performance
• Login and Receive API
• Operations
  • LoadAmazonBalance
    • Requests
    • Response
  • VoidAmazonBalanceLoad
    • Requests
    • Response

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

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:

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

Example Request

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

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

Example Response

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

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

Sample request

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

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

Example Response

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

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

↑ Back to top

Next

• Prepare to launch with our Test Plan Guide

Last updated: Dec 16, 2022