Receive funds at brick and mortar sites

HAQM Balance Load (ABL) is a set of systems that lets you load funds directly into a customer’s HAQM Gift Card Balance in real-time, as long as the customer can identify themself as an active HAQM customer. An active HAQM customer as defined as a customer who has an HAQM account in the desired marketplace. For phone number implementations, they'll need to have the number associated with the HAQM account.

HAQM Cash uses the HAQM Balance Load service to let a customer add funds to their HAQM Gift Card Balance at a physical (brick and mortar) retail store within your network by providing a barcode or mobile phone number that identifies the HAQM customer account. When an active HAQM account cannot be found, a customer can get an HAQM Gift Card claim code on a printed receipt they can redeem later if your implementation allows this outcome.

• HAQM Cash
• Key Concepts
  • Barcode Account Type
  • Phone Number Account Type
  • Additional requirements at Brick and Mortar locations
  • Minimum and Maximum Amount per Transaction per Country
• Operations
  • Two-Step Balance Load Process
  • One-Step Balance Load Process
• ValidateAccountForHAQMBalanceLoad
  • Requests
  • Responses
• LoadHAQMBalance
  • Requests
  • Responses
• VoidHAQMBalanceLoad
  • Requests
  • Responses

HAQM Cash

The HAQM Cash service (name may differ by country) lets HAQM customers load funds to their HAQM Gift Card Balance or get a Gift Card claim code in real-time from a brick and mortar (B&M) location. This transaction is initiated within the distribution partner's network of B&M sites, which process the load requests and route those transactions directly to HAQM.

Two methods are available for a customer to represent their HAQM account at a partner's B&M location:

1. Barcode - Showing a personalized barcode generated by HAQM that is linked to the customer’s HAQM account (customers get their HAQM Cash barcode from the HAQM app or HAQM website), Or
2. Phone Number - Entering/providing the phone number that is linked to their HAQM account, at the point of sale.

In addition to the customer’s method of identification (barcode or phone number), the customer communicates the amount of funds they wish to load into their account to the store associate (minimum of $5 and maximum of $500 per load in the United States). This information is compiled and then transmitted to HAQM who subsequently responds with a confirmation or rejection of the load request. you can use either a two-step or one-step load request process as detailed below.

↑ Back to top

Key Concepts

Barcode Account Type

To integrate with the HAQM Cash product and support account type 1 (barcode based), your POS (point-of-sale) system must have barcode scanners that can scan barcodes on mobile phones and support 1D barcodes in Code 128 format.

Barcode Format

HAQM uses its own Product Code and IIN in the construction of the barcode. The HAQM barcode is 30 digits in length, composed of:

• 11 digits UPC
• 13 digits EAN or JAN
• 6 digits IIN
• 12 digits PAN
• 1 digit checksum

HAQM uses the LUHN algorithm to generate the checksum digit and the algorithm is applied to the IIN + PAN.

Find below HAQM’s product code (UPC/EAN/JAN) and IIN, plus a barcode example. Note that product code will vary per country.

Product Code (UPC 11, EAN 13, JAN 13)

1. Global Issuer Identification Number (IIN): 608574

Figure 3.1a Barcode Example- 30 digits

Figure 4.1b Barcode Example- 32 digits

Phone Number Account Type

Phone number is another supported account type 4. To integrate with the HAQM Cash product and support the phone number account type, your POS system must allow an operator to input phone number digits and print a receipt with claim code. In certain scenarios, the HAQM Cash transaction must return a paper receipt that contains a claim code that the customer can use online later to credit their account.

Phone Number Format

The phone number input must adhere to either one of the following formats:

E.164 numbers can have a maximum of fifteen digits and are formatted as:

[+] [country code] [subscriber number including area code]   

For example, +14155552671 (US Number), +442071838750 (UK Number).

Using the E.164 format provides more options for your integration in the future and is therefor the preferred method.

Receipt Requirements

Receipt requirements differ based on POS systems ability to change the content based on whether the LoadHAQMBalance call for phone form factor-based load applied the funds to the customer’s account (verified phone number) or issued a claim code (unverified phone number).

Default Instruction Text

If the POS system cannot change the receipt content, this text should appear:

Additional requirements at Brick and Mortar locations

Every call to LoadHAQMBalance that occurs at a brick and mortar location must include details of the location where the transaction occurred. Requests to these endpoints can include a transactionSource object that describes the physical location of the event. These parameters can be found in the request parameters table below.

There are two options for sending store location data to HAQM:

1. Long form – partner provides specific store location data for each transaction (must include sourceId, institutionId and sourceDetails)
2. Short form – partner provides only the sourceId and institutionId in the API request. A separate location mapping file must be sent that maps these identifiers to physical locations. See Location Mapping file instructions in this spreadsheet.

Sample payload for transaction source in both XML and JSON format is shown below.

• Long Form
  JSON XML
• Short Form
  JSON XML

{
  "LoadHAQMBalanceRequest": {
    "account": {
      "id": 851432007016085741000205631269,
      "type": 1
    },
    "partnerId": "Bus21",
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "loadBalanceRequestId": "Bus21requestId1",
    "timestamp": 1464933146,
    "transactionSource": {
      "sourceDetails": "{ "institutionName": "Walgreens","Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101","Phone": "+12061232333"}"
    }
  }
}

<LoadHAQMBalanceRequest>
 	<account>
 	 	<id>851432007016085741000205631269</id>
 	 	<type>1</type>
 	</account>
 	<partnerId>Bus21</partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<loadBalanceRequestId>Bus21requestId1</loadBalanceRequestId>
 	<timestamp>1464933146</timestamp>
 	<transactionSource>
 	 	<sourceDetails>{ "institutionName": "Walgreens",
                         "Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
                         "Phone": "+12061232333"}
        </sourceDetails>
 	</transactionSource>
</LoadHAQMBalanceRequest>

{
  "loadBalanceRequestId": "Amxx134565",
  "partnerId": "Amxx1",
  "amount": {
    "currencyCode": "USD",
    "value": 1000
  },
  "account": {
    "id": "5551112222",
    "type": "4"
  },
  "timestamp": 1574704599588,
  "transactionSource": {
    "sourceId": "12345",
    "institutionId": "Example123344"
  },
  "externalReference": "serviceId:123",
  "notificationDetails": {
    "notificationMessage": "Thank you for loading balance at 12345!"
  }
}

<LoadHAQMBalanceRequest>
	<loadBalanceRequestId>Amxx134565</loadBalanceRequestId>
	<partnerId>Amxx1</partnerId>
	<amount>
		<currencyCode>USD</currencyCode>
		<value>1000</value>
	</amount>
	<account>
		<id>5551112222</id>
		<type>4</type>
	</account>
	<timestamp>1574704599588</timestamp>
	<transactionSource>
		<sourceId>12345</sourceId>
		<institutionId>Example123344</institutionId>
	</transactionSource>
	<externalReference>serviceId:123</externalReference>
	<notificationDetails>
		<notificationMessage>Thank you for loading balance at 12345!</notificationMessage>
	</notificationDetails>
</LoadHAQMBalanceRequest>

Minimum and Maximum Amount per Transaction per Country

↑ Back to top

Operations

Below are the operations contained within the balance load API.

Two-Step Balance Load Process

The two-step balance load process involves the use of two API’s: ValidateAccountForHAQMBalanceLoad and LoadHAQMBalance. The typical process is described below:

1. The Store cashier scans the customer’s HAQM Cash barcode or enters the customer’s phone number and asks how much cash the customer wants to load.
2. The cashier enters the amount into the POS(Point-of-Sale) terminal and confirms with the customer.
3. The POS sends a ValidateAccountForHAQMBalanceLoad request to HAQM. HAQM checks customer’s eligibility to load the requested amount to his/her HAQM Gift Card Balance.
4. If ValidateAccountForHAQMBalanceLoad response confirms the request, the cashier takes cash from the customer and the POS sends the LoadHAQMBalance request to HAQM via the Distribution Partner network. HAQM does not recommend pre-tender activations (i.e., calling LoadHAQMBalance before the store cashier has received money.)
5. HAQM processes the request, first checking the customer’s eligibility, and if eligible and if the HAQM account can be identified, loads the requested funds into the customer’s HAQM Gift Card Balance. A confirmation response is sent. If the account is ineligible, a rejection response is sent back. In the case of customer providing phone number for the Balance Load process, and if that phone number cannot be associated to any HAQM account, the operation will respond with a valid Gift Card Claim Code. In this case, the claim code has to be printed on the receipt and given to the customer.

Figure 1. two-step Balance Load process diagram

↑ Back to top

One-Step Balance Load Process

If you do not have the ability to send a ValidateAccountForHAQMBalanceLoad request, as described in the two-step instructions above, can choose to use just the LoadHAQMBalance request directly. This one-step Balance Load process is described here:

1. The store cashier scans the customer’s HAQM Cash barcode or enters the customer’s phone number and asks how much cash the customer wants to load.
2. The cashier enters the amount into the POS terminal, confirms with the customer and then takes the cash from the customer.
3. The POS sends a LoadHAQMBalance request to HAQM using your network.
4. To handle the request, HAQM checks the customer’s eligibility. If eligible and if the HAQM account can be identified, HAQM loads the requested funds into the customer’s Gift Card Balance. A confirmation response is sent. If the account is ineligible, a rejection response is sent back. If the customer provides a phone number, but that phone number cannot be associated to any unique account, the operation will respond with a valid Gift Card Claim Code. In this case, the claim code must be printed on the receipt and given to the customer.

Figure 2. One-step Balance Load Store Process Diagram

↑ Back to top

ValidateAccountForHAQMBalanceLoad

The ValidateAccountForHAQMBalanceLoad operation validates whether the intended amount is within the range allowed for this country, and checks if a customer’s HAQM account is eligible for the Balance Load process.

For barcode account type, the eligibility check validates that the barcode linked to an active HAQM customer account and is approved to add funds into their HAQM Gift Card balance.

For phone number account type, this validates that the phone number provided is a valid phone number. If the phone can be identified as linked to one HAQM customer account, this will also validate the customer eligibility status. Otherwise, the validation will NOT reject the unidentified phone number (that is not linked to any HAQM customer) and will treat this as a valid account. The operation will respond with a PARTIAL_SUCCESS in this case. For such unverified phone numbers, the LoadHAQMBalance operation will return a claim code for manual redemption by the customer later on.

Requests

Request Parameters

Example Request

• XML
  Barcode Phone
• JSON
  Barcode Phone

POST /ValidateAccountForHAQMBalanceLoad 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-gamma.haqm.com x-amz-date:20130910T221949Z x-amz-target:com.amazonaws.agcod.AGCODService.ValidateAccountForHAQMBalanceLoad
	Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790
Payload=

<ValidateAccountForHAQMBalanceLoadRequest>
 	<account>
 	 	<id>851432007016085741001033001453</id>
 	 	<type>1</type>
 	</account>
 	<partnerId>Bus21</partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
    <timestamp>1464933146000</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
 	 	<institutionId>example12344332</institutionId>
             <sourceDetails>
                 {"institutionName":"Walgreens", "Address":"1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101", "Phone":"+12061232333"}
             </sourceDetails>
 	</transactionSource>
</ValidateAccountForHAQMBalanceLoadRequest>

POST /ValidateAccountForHAQMBalanceLoad 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-gamma.haqm.com x-amz-date:20130910T221949Z x-amz-target:com.amazonaws.agcod.AGCODService.
ValidateAccountForHAQMBalanceLoad
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<LoadHAQMBalanceRequest>
    <account>
        <id>2061231234</id>
        <type>4</type>
    </account>
    <partnerId>Bus21</partnerId>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <loadBalanceRequestId>Bus21requestId1</loadBalanceRequestId>
    <timestamp>1464933146000</timestamp>
    <transactionSource>
        <sourceId>12344332</sourceId>
        <institutionId>example12344332</institutionId>
        <sourceDetails>{ "institutionName": "Walgreens",
                         "Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
                         "Phone": "+12061232333"}
        </sourceDetails>
    </transactionSource>
</LoadHAQMBalanceRequest>

{
  "ValidateAccountForHAQMBalanceLoadRequest": {
    "account": {
      "id": "851432007016085741000205631269",
      "type": "1"
    },
    "partnerId": "Bus21",
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "timestamp": 1464933146000,
    "transactionSource": {
      "sourceId": "12344332",
      "institutionId": "example12344332",
    }
  }
}

{
  "LoadHAQMBalanceRequest": {
    "account": {
      "id": "2061231234",
      "type": "4"
    },
    "partnerId": "Bus21",
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "loadBalanceRequestId": "Bus21RequestId1",
    "timestamp": 1464933146000,
    "transactionSource": {
      "sourceId": "12344332",
      "institutionId": "example12344332",
    }
  }
}

↑ Back to top

Responses

Response Parameters

Example Response

• XML
  Barcode Phone Phone (Partial)
• JSON
  Barcode Phone Phone (Partial)

<ValidateAccountForHAQMBalanceLoadResponse>
 	<account>
 	 	<id>851432007016085741001033001453</id>
 	 	<type>1</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
</ValidateAccountForHAQMBalanceLoadResponse>  

<ValidateAccountForHAQMBalanceLoadResponse>
 	<account>
 	 	<id>+12061231234</id>
 	 	<type>4</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
</ValidateAccountForHAQMBalanceLoadResponse>

<ValidateAccountForHAQMBalanceLoadResponse>
 	<account>
 	 	<id>+12061231235</id>
 	 	<type>4</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>PARTIAL_SUCCESS</status>
</ValidateAccountForHAQMBalanceLoadResponse>  

{
  "ValidateAccountForHAQMBalanceLoadResponse": {
    "account": {
      "id":851432007016085741000205631269,
      "type": 1
    },
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "status": "SUCCESS"
  }
}

{
  "ValidateAccountForHAQMBalanceLoadResponse": {
    "account": {
      "id": 12061231234,
      "type": 4
    },
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "status": "SUCCESS"
  }
}

{
  "ValidateAccountForHAQMBalanceLoadResponse": {
    "account": {
      "id": 12061231235,
      "type": 4
    },
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "status": "PARTIAL_SUCCESS"
  }
}

↑ Back to top  

LoadHAQMBalance

The LoadHAQMBalance operation loads funds into a customer’s HAQM Gift Card Balance or returns a valid Gift Card Claim Code (in the case when the given phone number is Unverified, for example, the phone number is not verified on an HAQM account. This operation is idempotent, in the sense that if HAQM receives multiple LoadHAQMBalance requests with the same loadBalanceRequestId, the same response from the first call will be returned. The loadBalanceRequestId you provide can have a maximum length of 40 characters, must be prefixed with your partnerId, and must be unique.

Requests

Request Parameters

Example Request

• XML
  Barcode Phone
• JSON
  Barcode Phone

POST /LoadHAQMBalance 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-gamma.haqm.com x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadHAQMBalance
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<LoadHAQMBalanceRequest>
 	<account>
 	 	<id>851432007016085741001033001453</id>
 	 	<type>1</type>
 	</account>
 	<partnerId>Bus21</partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<loadBalanceRequestId>Bus21requestId1</loadBalanceRequestId>
 	<timestamp>1464933146000</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
 	 	<institutionId>example12344332</institutionId>
 	 	<sourceDetails>{ "institutionName": "Walgreens",
                         "Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
                         "Phone": "+12061232333"}
        </sourceDetails>
 	</transactionSource>
</LoadHAQMBalanceRequest>

POST /LoadHAQMBalance 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-gamma.haqm.com x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadHAQMBalance
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<LoadHAQMBalanceRequest>
 	<account>
 	 	<id>2061231234</id>
 	 	<type>4</type>
 	</account>
 	<partnerId>Bus21</partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<loadBalanceRequestId>Bus21requestId1</loadBalanceRequestId>
 	<timestamp>1464933146000</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
 	 	<institutionId>example12344332</institutionId>
 	 	<sourceDetails>{ "institutionName": "Walgreens",
                         "Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
                         "Phone": "+12061232333"}
        </sourceDetails>
 	</transactionSource>
</LoadHAQMBalanceRequest>

{
  "account": {
    "id": "851432007046085742001152342537",
    "type": "1"
  },
  "partnerId": "AMB11",
  "amount": {
    "currencyCode": "USD",
    "value": 1000
  },
  "loadBalanceRequestId": "AMB111123446",
  "timestamp": 1658413475356,
  "transactionSource": {
    "institutionId": "12344332",
    "sourceId": "12344332"
  },
  "externalReference": "serviceId:123",
  "notificationDetails": {
    "notificationMessage": "Thank you for your purchase!"
  }
}

{
  "account": {
    "id": "2061231234",
    "type": "4"
  },
  "partnerId": "AMB11",
  "amount": {
    "currencyCode": "USD",
    "value": 1000
  },
  "loadBalanceRequestId": "AMB111123446",
  "timestamp": 1658413475356,
  "transactionSource": {
    "institutionId": "12344332",
    "sourceId": "12344332"
  },
  "externalReference": "serviceId:123",
  "notificationDetails": {
    "notificationMessage": "Thank you for your purchase!"
  }
}

↑ Back to top

Responses

Response Parameters

Example Response

• XML
  Barcode Phone Phone (Partial)
• JSON
  Barcode Phone Phone (Partial)

<LoadHAQMBalanceResponse>
    <account>
        <id>851432007016085741001033001453</id>
        <type>1</type>
    </account>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <status>SUCCESS</status>
    <loadBalanceRequestId>Bus21requestId1</loadBalanceRequestId>
</LoadHAQMBalanceResponse>

<LoadHAQMBalanceResponse>
 	<account>
 	 	<id>+12061231234</id>
 	 	<type>4</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
 	<loadBalanceRequestId>Bus21requestId1</loadBalanceRequestId>
 	<additionalInfo>{"claimcode":"ABCD-EFGH-JK123"}</additionalInfo>
</LoadHAQMBalanceResponse>

<LoadHAQMBalanceResponse>
 	<account>
 	 	<id>+12061231234</id>
 	 	<type>4</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
 	<loadBalanceRequestId>Bus21requestId1</loadBalanceRequestId>
 	<additionalInfo>{"claimcode":"XXXX-XXXXXX-XXXX"}</additionalInfo>
</LoadHAQMBalanceResponse>

{
  "LoadHAQMBalanceResponse": {
    "account": {
      "id": 851432007016085741000205631269,
      "type": 1
    },
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "status": "SUCCESS",
    "loadBalanceRequestId": "Bus21requestId1"
  }
}

{
  "LoadHAQMBalanceResponse": {
    "account": {
      "id": 12061231234,
      "type": 4
    },
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "status": "SUCCESS",
    "loadBalanceRequestId": "Bus21requestId1",
    "additionalInfo": "{"claimcode":"XXXX-XXXXXX-XXXX"}"
  }
}

{
  "LoadHAQMBalanceResponse": {
    "account": {
      "id": 12061231234,
      "type": 4
    },
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "status": "SUCCESS",
    "loadBalanceRequestId": "Bus21requestId1",
    "additionalInfo": "{"claimcode":"XXXX-XXXXXX-XXXX"}"
  }
}

↑ Back to top  

VoidHAQMBalanceLoad

When a POS cannot guarantee that a request was run successfully, for instance because of a missed message due to network issues, the POS and/or Distribution Partner must run a VoidHAQMBalanceLoad request to ensure that the funds will not be added to the customer’s HAQM Gift Card Balance. In case of any failure at the POS, the cashier always returns the cash to the end customer. Hence, the importance of the void is to ensure that funds are removed promptly from the customer’s HAQM Gift Card Balance in case funds were added successfully but the confirmation message was never received by the POS.

The VoidHAQMBalanceLoad operation will void a successful LoadHAQMBalance request only within 15 minutes of the original request. The original loadBalanceRequestId used to load funds from a successful LoadHAQMBalance request is required for the void operation. The currencyCode, value, sourceId and institutionId fields must match the respective values provided in the original LoadHAQMBalance request. The void operation is idempotent.

Requests

Request Parameters

Example Request

• XML
  Barcode Phone
• JSON
  Barcode Phone

POST /VoidHAQMBalance 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-gamma.haqm.com x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.VoidHAQMBalance
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<VoidHAQMBalanceLoadRequest>
 	<account>
 	 	<id>851432007016085741001033001453</id>
 	 	<type>1</type>
 	</account>
	 	<partnerId>Bus21</partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<loadBalanceRequestId>Bus21requestId1</loadBalanceRequestId>
 	<timestamp>1464933146000</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
 	 	<institutionId>example12344332</institutionId>
 	 	<sourceDetails>{"institutionName":"Walgreens","Address":"1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101","Phone":"+12061232333"}</sourceDetails>
 	</transactionSource>
 	<voidIfUsed>true</voidIfUsed>
</VoidHAQMBalanceLoadRequest>

POST /VoidHAQMBalance 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-gamma.haqm.com x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.VoidHAQMBalance
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<VoidHAQMBalanceLoadRequest>
    <account>
        <id>7574662233</id>
        <type>4</type>
    </account>
    <partnerId>Bus21</partnerId>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <loadBalanceRequestId>Bus21requestId1</loadBalanceRequestId>
    <timestamp>1464933146000</timestamp>
    <transactionSource>
        <sourceId>12344332</sourceId>
        <institutionId>example12344332</institutionId>
        <sourceDetails>{"institutionName":"Walgreens","Address":"1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101","Phone":"+12061232333"}</sourceDetails>
    </transactionSource>
    <voidIfUsed>true</voidIfUsed>
</VoidHAQMBalanceLoadRequest>

{
  "VoidHAQMBalanceLoadRequest": {
    "account": {
      "id": "851432007016085741000205631269",
      "type": "1"
    },
    "partnerId": "Bus21",
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "loadBalanceRequestId": "Bus21requestId1",
    "timestamp": 1464933146000,
    "transactionSource": {
      "sourceId": "12344332",
      "institutionId": "example12344332"
    },
    "voidIfUsed": true
  }
}

{
  "VoidHAQMBalanceLoadRequest": {
    "account": {
      "id": "7574662233",
      "type": "4"
    },
    "partnerId": "Bus21",
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "loadBalanceRequestId": "Bus21requestId1",
    "timestamp": 1464933146000,
    "transactionSource": {
      "sourceId": "12344332",
      "institutionId": "example12344332"
    },
    "voidIfUsed": true
  }
}

↑ Back to top

Responses

Response Parameters

Example Response

• XML
  Barcode Phone
• JSON
  Barcode Phone

<VoidHAQMBalanceLoadResponse>
 	<account>
 	 	<id>851432007016085741001033001453</id>
 	 	<type>1</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
 	<loadBalanceRequestId>Bus21requestId1</loadBalanceRequestId>
</VoidHAQMBalanceLoadResponse>

<VoidHAQMBalanceLoadResponse>
 	<account>
 	 	<id>+17574662233</id>
 	 	<type>4</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
 	<loadBalanceRequestId>Bus21requestId1</loadBalanceRequestId>
</VoidHAQMBalanceLoadResponse>

{
  "VoidHAQMBalanceLoadResponse": {
    "account": {
      "id": 851432007016085741000205631269,
      "type": 1
    },
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "status": "SUCCESS",
    "loadBalanceRequestId": "Bus21requestId1"
  }
}

{
  "VoidHAQMBalanceLoadResponse": {
    "account": {
      "id": 17574662233,
      "type": 4
    },
    "amount": {
      "currencyCode": "USD",
      "value": 4570
    },
    "status": "SUCCESS",
    "loadBalanceRequestId": "Bus21requestId1"
  }
}

↑ Back to top

Next

• Prepare to launch with our Test Plan Guide

Last updated: Oct 12, 2021