Point of Sale Activation (POSA)

The Incentives API enables you to activate and distribute Amazon Gift Card claim codes on demand. Every gift card is associated with a unique pre-generated Web Activated Card (WAC) and denomination (numeric value). The gift card can be activated in real time. Once activated, the gift card associated with the WAC can be distributed, and the customer can use it towards purchases on Amazon.

The Incentives API Web Activation operations provide a programmatic interface you can use to activate/deactivate GCs in real time. You make synchronous requests to the endpoint that specifies the value of the WAC they want to activate for the non-denominated cards or provides the matching pre-denominated amount for the pre-denominated cards. The API responds with the success or failure status of the operation.

There are two types of Web Activated Cards(WAC):

• Denominated (fixed amount) – amount is already predetermined for the claim code
• Non-denominated (variable amount) – amount assigned when claim code is activated

Your Account Manager will provide the WAC numbers along with the associated claim codes as needed.

• Key Concepts
  • Web Activation Card Number (WAC)
• Operations
  • ActivateGiftCard
    • Requests
    • Response
  • DeactivateGiftCard
    • Request
    • Response
  • ActivationStatusCheck
    • Request
    • Response
• Additional requirements at Brick and Mortar locations
• Error Handling
  • Error Codes
• Activation FAQ

Key Concepts

Web Activation Card Number (WAC)

The 16-digit WAC number sent with the three digit checksum when making endpoint requests (example: 1400000005567585358). Since card numbers are typically issued over a range (example: 1400000005567585 - 1400000005568000), use the checksum to validate that the correct card number has been sent in your activation request. This check is particularly important if a card is activated manually, and card numbers are read off verbally. See the following example containing WACs, and note that Amazon will provide a similar format when providing WACs/Claim Codes for the Web Activation use case.

↑ Back to top

Operations

Your code makes signed HTTP POST requests to our endpoints to activate or de-activate claim codes. (We do not accept SOAP requests.) The body of your HTTP requests will contain JSON or XML. Every request to an Incentives API operation endpoint must be digitally signed using your Incentives API security credentials and the Signature Version 4 signature algorithm."

The following table describes concepts and elements you will use when calling these endpoints:

To keep the activationRequestId & statusCheckRequestId globally unique, follow these requirements:

• Generate an alphanumeric value that is unique within your system. This ID can have up to 40 alphanumeric characters.
• Begin the activationRequestId & statusCheckRequestId value with your partnerID.

ActivateGiftCard

The ActivateGiftCard operation puts a physical card into an active state. A physical card in an active state can be redeemed by a customer.

You send an activationRequestId that uniquely identifies that activation request, along with other details like the denomination, currency, etc. (in addition to the metadata about that request, authentication info, etc.)

To perform this operation, send an ActivateGiftCard request. Amazon checks for sufficient funds in your Amazon Payments account or other pre-payment account, and then deducts funds from the account and responds with a synchronous response message that includes the activation status, cardNumber, cardStatus, and activationRequestId. You must store the activationRequestId, amount, and currencyCode for all subsequent requests related to the same transaction. The response message also contains some metadata, along with the status of the execution. Currently, the Web Activated Card (WAC) statuses returned are either Activated, AwaitingActivation, or Invalidated.

This operation is idempotent, so if the Incentives API receives more than one request with the same activationRequestId, then the first request will result in the activation of a new WAC, while all subsequent responses will return the originally activated WAC, and will not be treated as separate transactions.

One ActivateGiftCard call results in only one activation. (Bulk activation is not supported at this time)

Requests

Request Parameters

Transaction Amount Limits Calls to ActivateGiftCard must specify a currency code authorized by your account, within the range allowed for the country of issuance.

Example Request

• XML
  Required Parameters Reseller Use Case Product Use Case Optional Parameters
• JSON
  Required Parameters Reseller Use Case Product Use Case Optional Parameters

POST /ActivateGiftCard HTTP/1.1
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140327T212600Z
x-amz-target:com.amazonaws.agcod.AGCODService.ActivateGiftCard
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20140327/us-east-1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target,
Signature=bb4acbe8b115e24e07627fb862d2b3ea21c4f043fd4344c6f24b0a4d39961d9c
<ActivateGiftCardRequest>
    <activationRequestId>Awssb0327141418PM</activationRequestId>
    <partnerId>Awssb</partnerId>
    <cardNumber>1700000005489413</cardNumber>
    <value>
        <currencyCode>USD</currencyCode>
        <amount>10</amount>
    </value>
</ActivateGiftCardRequest>

POST /ActivateGiftCard HTTP/1.1
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140327T212600Z
x-amz-target:com.amazonaws.agcod.AGCODService.ActivateGiftCard
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20140327/us-east-1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target,
Signature=bb4acbe8b115e24e07627fb862d2b3ea21c4f043fd4344c6f24b0a4d39961d9c
<ActivateGiftCardRequest>
    <activationRequestId>Awssb0327141418PM</activationRequestId>
    <partnerId>Awssb</partnerId>
    <cardNumber>1700000005489413</cardNumber>
    <value>
        <currencyCode>USD</currencyCode>
        <amount>10</amount>
    </value>
    <programId>ObY8ftkZQoG3lp2cmEleqg</programId>
</ActivateGiftCardRequest>

POST /ActivateGiftCard HTTP/1.1
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140327T212600Z
x-amz-target:com.amazonaws.agcod.AGCODService.ActivateGiftCard
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20140327/us-east-1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target,
Signature=bb4acbe8b115e24e07627fb862d2b3ea21c4f043fd4344c6f24b0a4d39961d9c
<ActivateGiftCardRequest>
    <activationRequestId>Awssb0327141418PM</activationRequestId>
    <partnerId>Awssb</partnerId>
    <cardNumber>1700000005489413</cardNumber>
    <value>
        <currencyCode>USD</currencyCode>
        <amount>10</amount>
    </value>
    <productType>bookPV</productType>
</ActivateGiftCardRequest>

POST /ActivateGiftCard HTTP/1.1
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140327T212600Z
x-amz-target:com.amazonaws.agcod.AGCODService.ActivateGiftCard
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20140327/us-east-1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target,
Signature=bb4acbe8b115e24e07627fb862d2b3ea21c4f043fd4344c6f24b0a4d39961d9c
<ActivateGiftCardRequest>
    <activationRequestId>Awssb0327141418PM</activationRequestId>
    <partnerId>Awssb</partnerId>
    <cardNumber>1700000005489413</cardNumber>
    <value>
        <currencyCode>USD</currencyCode>
        <amount>10</amount>
    </value>
    <externalReference>889jj14797<externalReference>
</ActivateGiftCardRequest>

POST /ActivateGiftCard HTTP/1.1
accept:application/json
content-type:application/jsonhost:agcod-v2-gamma.amazon.com
x-amz-date:20140327T211822Z
x-amz-target:com.amazonaws.agcod.AGCODService.ActivateGiftCard
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20140327/us-east-1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target,
Signature=519cd671dd26ab45cca71f8a1cbd56d07409b4649b0dbba0b2f5aa248a489b1c
{
  "activationRequestId": "Awssb0327141418PM",
  "partnerId": "Awssb",
  "cardNumber": "1700000005489413",
  "value": {
    "currencyCode": "USD",
    "amount": 10
  }
}

POST /ActivateGiftCard HTTP/1.1
accept:application/json
content-type:application/jsonhost:agcod-v2-gamma.amazon.com
x-amz-date:20140327T211822Z
x-amz-target:com.amazonaws.agcod.AGCODService.ActivateGiftCard
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20140327/us-east-1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target,
Signature=519cd671dd26ab45cca71f8a1cbd56d07409b4649b0dbba0b2f5aa248a489b1c
{
  "activationRequestId": "Awssb0327141418PM",
  "partnerId": "Awssb",
  "cardNumber": "1700000005489413",
  "value": {
    "currencyCode": "USD",
    "amount": 10,
  "programId":"ObY8ftkZQoG3lp2cmEleqg"
  }
}

POST /ActivateGiftCard HTTP/1.1
accept:application/json
content-type:application/jsonhost:agcod-v2-gamma.amazon.com
x-amz-date:20140327T211822Z
x-amz-target:com.amazonaws.agcod.AGCODService.ActivateGiftCard
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20140327/us-east-1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target,
Signature=519cd671dd26ab45cca71f8a1cbd56d07409b4649b0dbba0b2f5aa248a489b1c
{
  "activationRequestId": "Awssb0327141418PM",
  "partnerId": "Awssb",
  "cardNumber": "1700000005489413",
  "value": {
    "currencyCode": "USD",
    "amount": 10,
  "productType":"bookPV"
  }
}

POST /ActivateGiftCard HTTP/1.1
accept:application/json
content-type:application/jsonhost:agcod-v2-gamma.amazon.com
x-amz-date:20140327T211822Z
x-amz-target:com.amazonaws.agcod.AGCODService.ActivateGiftCard
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20140327/us-east-1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target,
Signature=519cd671dd26ab45cca71f8a1cbd56d07409b4649b0dbba0b2f5aa248a489b1c
{
  "activationRequestId": "Awssb0327141418PM",
  "partnerId": "Awssb",
  "cardNumber": "1700000005489413",
  "value": {
    "currencyCode": "USD",
    "amount": 10,
  "externalReference":"889jj14797"
  }
}

Response

Response Parameters

Example Responses

• XML
• JSON

<ActivateGiftCardResponse>
    <cardInfo>
        <value>
            <amount>10.0</amount>
            <currencyCode>USD</currencyCode>
        </value>
        <cardStatus>Activated</cardStatus>
        <cardNumber>1700000005489413</cardNumber>
    </cardInfo>
    <status>SUCCESS</status>
    <activationRequestId>Awssb0327141418PM</activationRequestId>
</ActivateGiftCardResponse>

{
  "activationRequestId": "Awssb0327141418PM",
  "cardInfo": {
    "cardNumber": "1700000005489413",
    "cardStatus": "Activated",
    "expirationDate": null,
    "value": {
      "amount": 10,
      "currencyCode": "USD"
    }
  },
  "status": "SUCCESS"
}

This operation is idempotent, so if the Incentives API receives more than one request with the same activationRequestId, only the first request will result in the creation of a new gift card, and all subsequent responses will return the same original gift card. They will not be treated as different transactions.

↑ Back to top

DeactivateGiftCard

The DeactivateGiftCard operation puts a physical card into an inactive state. An inactive card cannot be redeemed by a customer. You can deactivate a WAC under the following conditions:

• The claim code associated with the WAC is not claimed by an Amazon customer.
• The WAC is not in Invalidated state.
• The WAC was previously activated by the same partner. Both the original activationRequestId used for activating the WAC and the card number must be supplied for a DeactivateGiftCard operation.

To perform this operation, send a DeactivateGiftCard request. The Incentives API responds with a synchronous DeactivateGiftCardResponse. This operation is idempotent, so if the Incentives API receives more than one request with the same activationRequestId, then the first request will result in the deactivation of the WAC, while all subsequent responses will do nothing (they will not be treated as a different transaction).

Request

Request Parameters

Example Request

• XML
• JSON

POST /DeactivateGiftCard HTTP/1.1
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140327T213942Z
x-amz-target:com.amazonaws.agcod.AGCODService.DeactivateGiftCard
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20140327/us-east-1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target,
Signature=0ace0a2eaefc9ecf62e1224c7e59abe46af934a8e772b808c18dccdfdab009a5
<DeactivateGiftCardRequest>
    <activationRequestId>Awssb0327141418PM</activationRequestId>
    <partnerId>Awssb</partnerId>
    <cardNumber>1700000005489413</cardNumber>
</DeactivateGiftCardRequest>

POST /DeactivateGiftCard HTTP/1.1
accept:application/json
content-type:application/jsonhost:agcod-v2-gamma.amazon.com
x-amz-date:20140327T213727Z
x-amz-target:com.amazonaws.agcod.AGCODService.DeactivateGiftCard
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20140327/us-east-1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target,
Signature=86a6ce1bfdb1e0e5842b5e351ad87058b673bdc6f7fd770c6fdb8349a1de1bde
{
  "activationRequestId": "Awssb0327141418PM",
  "partnerId": "Awssb",
  "cardNumber": "1700000005489413"
}

Response

Example Response

• XML
• JSON

<DeactivateGiftCardResponse>
    <cardInfo>
        <cardStatus>AwaitingActivation</cardStatus>
        <cardNumber>1700000005489413</cardNumber>
    </cardInfo>
    <status>SUCCESS</status>
    <activationRequestId>Awssb0327141418PM</activationRequestId>
</DeactivateGiftCardResponse>

{
  "activationRequestId": "Awssb0327141418PM",
  "cardInfo": {
    "cardNumber": "1700000005489413",
    "cardStatus": "AwaitingActivation",
    "expirationDate": null,
    "value": null
  },
  "status": "SUCCESS"
}

↑ Back to top

ActivationStatusCheck

Use the ActivationStatusCheck operation to verify the status of the WAC after executing the ActivateGiftCard/DeactivateGiftCard call, Amazon will respond with a synchronous ActivationStatusCheckResponse that provides the current status of the WAC. The WAC statuses returned are Activated, AwaitingActivation, or Invalidated.

Request

Request Parameters

Example Request

• XML
• JSON

POST /ActivationStatusCheck HTTP/1.1
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140327T234634Z
x-amz-target:com.amazonaws.agcod.AGCODService.ActivationStatusCheck
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20140327/us-east-1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target,
Signature=96025ab925782595bffde21366bcd1927406ce5ddb723e89088f2cb0026040e8
<ActivationStatusCheckRequest>
    <statusCheckRequestId>Awssb0327141418PM</statusCheckRequestId>
    <partnerId>Awssb</partnerId>
    <cardNumber>1700000005489413</cardNumber>
</ActivationStatusCheckRequest>

POST /ActivationStatusCheck HTTP/1.1
accept:application/json
content-type:application/jsonhost:agcod-v2-gamma.amazon.com
x-amz-date:20140327T234321Z
x-amz-target:com.amazonaws.agcod.AGCODService.ActivationStatusCheck
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20140327/us-east-1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target,
Signature=ae3aa76cdc3043d45ca962a3a85ea9b95c6202a87f9700e7fe04b4c8d956ca31
{
  "statusCheckRequestId": "Awssb0327141418PM",
  "partnerId": "Awssb",
  "cardNumber": "1700000005489413"
}

Response

• XML
  Active Not Active
• JSON
  Active Not Active

<ActivationStatusCheckResponse>
    <cardInfo>
        <cardStatus>Activated</cardStatus>
        <cardNumber>1700000005489413</cardNumber>
    </cardInfo>
    <status>SUCCESS</status>< statusCheckRequestId> Awssb0327141418PM
</statusCheckRequestId>undefined</ActivationStatusCheckResponse>

<ActivationStatusCheckResponse>
    <cardInfo>
        <cardStatus>AwaitingActivation</cardStatus>
        <cardNumber>1700000005489413</cardNumber>
    </cardInfo>
    <status>SUCCESS</status>
    <statusCheckRequestId>Awssb0327141418PM</statusCheckRequestId>
</ActivationStatusCheckResponse>

{
  "cardInfo": {
    "cardNumber": "1700000005489413",
    "cardStatus": "Activated",
    "value": null
  },
  "status": "SUCCESS",
  "statusCheckRequestId": " Awssb0327141418PM"
}

{
  "cardInfo": {
    "cardNumber": "1700000005489413",
    "cardStatus": "AwaitingActivation",
    "expirationDate": null,
    "value": null
  },
  "status": "SUCCESS",
  "statusCheckRequestId": "Awssb0327141418PM"
}

↑ Back to top

Additional requirements at Brick and Mortar locations

Every call to ActivateGiftCard 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 Amazon:

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

{
  "value": {
    "currencyCode": "USD",
    "amount": 150
  },
  "activationRequestId": "Awssb0327141418PM",
  "cardNumber": "6215366885893081",
  "partnerId": "Apppt",
  "externalReference": "{"promoCode":"855238"}",
  "transactionSource": {
    "sourceDetails": "{"institutionName" : "Fred Meyer", "institutionParentCompany" : "Kroger", "address1" : "2041 148th Ave NE", "address2" : "", "city" : "Bellevue", "state" : "Washington", "zip" : "98007", "phoneNumber" : "+14258658560", "UPC" : "ABC1234"}"
  }
}

<ActivateGiftCardRequest>
   <value>
      <currencyCode>USD</currencyCode>
      <amount>150</amount>
   </value>
   <activationRequestId>Awssb0327141418PM</activationRequestId>
   <cardNumber>6215366885893081</cardNumber>
   <partnerId>Apppt</partnerId>
   <externalReference>{"promoCode":"855238"}</externalReference>
   <transactionSource>
      <sourceDetails>{"institutionName" : "Fred Meyer", "institutionParentCompany" : "Kroger", "address1" : "2041 148th Ave NE", "address2" : "", "city" : "Bellevue", "state" : "Washington", "zip" : "98007", "phoneNumber" : "+14258658560", "UPC" : "ABC1234"}</sourceDetails>
   </transactionSource>
</ActivateGiftCardRequest>

{
  "value": {
    "currencyCode": "USD",
    "amount": 150
  },
  "activationRequestId": "Awssb0327141418PM",
  "cardNumber": "6215366885893081",
  "partnerId": "Apppt",
  "externalReference": "{"promoCode":"855238"}",
  "transactionSource": {
    "id": "{"institutionId" : "97263700007" , "sourceId" : "84000000109", "UPC" : "ABC1234"}"
  }
}

<ActivateGiftCardRequest>
   <value>
      <currencyCode>USD</currencyCode>
      <amount>150</amount>
   </value>
   <activationRequestId>Awssb0327141418PM</activationRequestId>
   <cardNumber>6215366885893081</cardNumber>
   <partnerId>Apppt</partnerId>
   <externalReference>{"promoCode":"855238"}</externalReference>
   <transactionSource>
      <id>{"institutionId" : "97263700007" , "sourceId" : "84000000109", "UPC" : "ABC1234"}</id>
   </transactionSource>
</div>

Error Handling

Every response sent from the Incentives API has a status element that describes the execution status for the particular operation; there are three statusCode values: SUCCESS, FAILURE, and RESEND. See Error Handling for details.

Error Codes

We have provided mock error request IDs to simulate certain error responses with the (Activate/Deactivate) calls. When simulating an error response, the mock error request ID will need to be passed in to the creationRequestId field, similar to a normal request ID. The values passed in for the rest of the fields will simply be echoed in the response. To simulate a successful response, the value of F1000 can be passed in for the mock error request ID. See Mocking test examples and Error Handling for details.

↑ Back to top

Activation FAQ

Q - How should I use the Activate and Deactivate APIs?

Use the ActivateGiftCard operation to activate a gift card by providing the activationRequestId and amount (denominated or pre-denominated amount depending on the card type). If you have already successfully activated a GC, and need to cancel it, you need to provide the original activationRequestId, amount, and currency values you used in the successful ActivateGiftCard operation. If you see a timeout from the AGCOD Gateway when making a ActivateGiftCard or DeactivateGiftCard operation, and are unsure if your call succeeded, then invoke ActivationStatusCheck to check the card status.

Q - I am getting “The card was already activated with a different request id” error when making an ActivateGiftCard call.

This might be caused by the same Card Serial Number activated with a different activationRequestId. Find the original activationRequestId and try the call again.

Q - Are there time limits from when an ActivateGiftCard request is made and when a DeactivateGiftCard will be accepted?

There is currently no time limit. Calls to DeactivateGiftCard will fail after a usage transaction has been processed for the gift card. For example, if the gift card has been claimed by your end customer, a call to DeactivateGiftCard will fail. In addition, an activated gift card cannot be deactivated after its expiration date. Gift cards issued in the United States, Canada, and Australia do not expire.

Next

• Prepare to launch with our Test Plan Guide

Last updated: Jul 18, 2022