Disburse funds with Login and Receive

This page describes the processes of integrating into the HAQM Gift Card On Demand(AGCOD) using our LoadHAQMBalance service combined within Login with HAQM We call this process Login and Receive.

The Login and Receive web service provides an API to disburse funds to a new or existing HAQM customer. A disbursement adds a monetary value to the Gift Card Balance portion of an HAQM 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 HAQM Gift Cards.

Call Login and Receive for the following use cases:

• Key Concepts
  • Basic Login with HAQM workflow
  • Transaction Amount Limits
  • Prerequisites
  • Performance
• Login and Receive API
• Operations
  • LoadHAQMBalance
    • Requests
    • Response
  • VoidHAQMBalanceLoad
    • Requests
    • Response

Key Concepts

Basic Login with HAQM workflow

The Login and Receive API uses the Login with HAQM web service, which allows users to authenticate their HAQM account using their HAQM account credentials within your browser-based or mobile application. Once authentication is complete, the Login with HAQM service provides your application with a user identifier you can use as an input parameter to LoadHAQMBalance. Together, these services allow a seamless experience for end users.

Login with HAQM offers customizations to align with your preferred user experience, including an SDK. Visit Login with HAQM 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 HAQM account.
2. Your application displays a page in the Login with HAQM module that prompts the user for their HAQM credentials.
3. New HAQM customers can sign up for a new account within the Login with HAQM workflow.
4. If your code requests the HAQM customer's name, email address, or postal/zip code, the Login with HAQM workflow seeks the HAQM customer's consent to share this information with your service.
5. The module initiates an Authorization Request using the Login with HAQM 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 LoadHAQMBalance method with the id value in your request body.
8. The LoadHAQMBalance operation updates the account's Gift Card balance.
9. HAQM sends an email confirmation to the email address associated with the HAQM 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 LoadHAQMBalance 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 HAQM Incentives.
• Integrate your web or mobile application with the Login with HAQM web service to provide authentication and (optionally) access to user profile data. To learn more about how to integrate your application with Login with HAQM, follow steps in the Login with HAQM Developer Center. To use Login with HAQM in your mobile app, you must use the Login with HAQM 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 HAQM 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 HAQM 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:

LoadHAQMBalance

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

Requests

Request Parameters

Example Request

• JSON
• XML

<LoadHAQMBalanceRequest>
	<loadBalanceRequestId>HAQM123456</loadBalanceRequestId>
	<partnerId>HAQM</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>
</LoadHAQMBalanceRequest>

POST
/LoadHAQMBalance HTTP/1.1

accept:application/json
host:agcod-v2-gamma.haqm.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadHAQMBalance
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":"HAQM123456",
    "partnerId":"HAQM",
    "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

<LoadHAQMBalance>
	<status>Success</status>
	<amount>
		<currencyCode>USD</currencyCode>
		<value>9000</value>
	</amount>
	<account>
		<id>amz1.account.123512341234</id>
		<type>2</type>
	</account>
	<loadBalanceRequestId>HAQM123456</loadBalanceRequestId>
</LoadHAQMBalance>

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

↑ Back to top

VoidHAQMBalanceLoad

This operation voids a previously successful LoadHAQMBalance request if the issued Claim Code funds have not already been used by the receiving HAQM customer. This operation can be run up to 15 minutes from the original call to LoadHAQMBalance. After that time, a call to VoidHAQMBalanceLoad will do nothing.

Your application must call this operation when you cannot confirm that a previous HAQMBalanceLoad request was successful. For example, if your call to LoadHAQMBalance does not return any result, call VoidHAQMBalanceLoad to ensure that no funds are added to the HAQM customer’s gift card balance.

Below is a description of the request body parameters.

Requests

Request Parameters

Sample request

• JSON
• XML

<VoidHAQMBalanceLoadRequest>
	<loadBalanceRequestId>HAQM123456</loadBalanceRequestId>
	<partnerId>HAQM</partnerId>
	<amount>
		<currencyCode>USD</currencyCode>
		<value>1000</value>
	</amount>
	<account>
		<id>amz1.account.123512341234</id>
		<type>2</type>
	</account>
</VoidHAQMBalanceLoadRequest>

POST
/VoidHAQMBalanceLoad HTTP/1.1

accept:application/json
host:agcod-v2-gamma.haqm.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.VoidHAQMBalanceLoad
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": "HAQM123456",
    "partnerId": "HAQM",
    "amount": {
        "currencyCode": "USD",
        "value": 1000
    },
    "account": {
        "id": "amz1.account.123512341234",
        "type": "2"
    }
}

Response

Response Parameters

Example Response

• JSON
• XML

<VoidHAQMBalanceLoad>
	<status>Success</status>
	<amount>
		<currencyCode>USD</currencyCode>
		<value>1000</value>
	</amount>
	<account>
		<id>amz1.account.123512341234</id>
		<type>2</type>
	</account>
	<loadBalanceRequestId>HAQM123456</loadBalanceRequestId>
</VoidHAQMBalanceLoad>

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

↑ Back to top

Next

• Prepare to launch with our Test Plan Guide

Last updated: Dec 16, 2022