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

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)

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.

Sequence Card Number Checksum Amount Claim Code
1 1400000005567585 358 $0 WA2W-A3CYCB-RDAMZ
2 1400000005567586 149 $0 WAS3-C8PP8R-MZMMD

↑ 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."

Operation Description
ActivateGiftCard Puts a physical card into an active state, so it can be redeemed by a customer.
DeactivateGiftCard Puts a physical card into an inactive state, so it cannot be redeemed.
ActivationStatusCheck Report's activation status of a physical gift card.

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

Item Description
partnerId A unique identifier (CASE SENSITIVE, 1st letter is capitalized and the next four are lower case) provided by the Amazon team. This value appears in the payload of every AGCOD Gateway request.
activationRequestId A unique identifier for every ActivateGiftCard / DeactivateGiftCard call that results in the activate / deactivate of a Web Activated Card (WAC). You must generate a new value for every Activate request (except for retries).
statusCheckRequestId An identifier used in an ActivationStatusCheck call to get the status of a WAC any time after a successful ActivateGiftCard request. This value must match the activationRequestId value used in the previous ActivateGiftCard call.
cardNumber The 16-digit WAC number (example: 1400000005567585358)
ActivateGiftCard response and DeactivateGiftCard response Each request to these endpoints returns a response your code must examine and may need to store.
Transaction A transaction is any request-response that results in the Activate/Deactivate of a gift card within Amazon systems.

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.
Example
If your partnerID is Amzn1, your activationRequestId & statusCheckRequestId must start with Amzn1 and any additional characters you would like in your ID (example: Amzn154321). Since the API is idempotent, if a request is sent in with a activationRequestId & statusCheckRequestId that was used prior, the Incentives API will return the original status that was activated the first time the activationRequestId & statusCheckRequestId was used.

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

Parameter Name Req. Constraints Type Description
activationRequestId Yes Max 40 Characters

Prefixed with partnerID

AlphaNumeric
String A unique identifier for every ActivateGiftCard request. You must generate a new value for every Activate request (except for retries). (See notes below.)
partnerID Yes Pre-defined value String A unique identifier (CASE SENSITIVE, 1st letter is capitalized and the next four are lower case) provided by the Amazon team. This value appears in the payload of every AGCOD Gateway request.
cardNumber Yes Pre-defined value Int The 16-digit WAC number (example: 1400000005567585358)
value Yes Object Object that holds the currencyCode and amount parameters.
currencyCode Yes ISO-4217 Currency Code String A ISO-4217 currency code that specifies the currency of the card.
amount Yes Long Card amount, in card currency.
transactionSource B&M Only Object Object that holds the sourceID, institutionID and sourceDetails parameters.
sourceID B&M Only Max 20 characters String Identifier of a transaction source entity (Example: Store Number or Store ID).
institutionID B&M Only Max 20 characters String Identifier of a parent entity of a transaction source (Example: Merchant Id). If parent entity does not exist, copy sourceId.
sourceDetails B&M Only Max 200 characters JSON String string to provide further information about transaction source. It must contain institutionName key with value as name of the source (e.g. Merchant Name). Other information such as source location, phone-number, etc. should be included.
programID Reseller Only Pre-defined value String You can use the programID field to help track client and use case transactions. The programID is an approved identifier provided by Amazon through a submission process. You must first submit client and use case information through your account manager.
productType PV Use Case Only Pre-defined value String required for the creation of an Amazon Product Voucher Claim Code. You must receive authorization to use this field. Available productType options can be found here.
externalReference Optional Max 100 characters String The externalReference field may be used to store a convenient mapping to assist you with tracking. For example, you might specify insurance claims, kiosks, customer cases, order Ids, reseller customer accounts, or store information within the externalReference field.

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

Country Currency Code Range Expiration
Australia AUD 0.01 - 5000.00 10 Years
Canada CAD 0.01 - 5000.00 N/A
Egypt EGP 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
Sweden SEK 1.00 - 1000.00 10 Years
Turkey TRY 1.00 - 5000.00 10 Years
United Arab Emirates 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

Example Request

Required 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>
Reseller Use Case
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>
Product Use Case
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>
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>
    <externalReference>889jj14797<externalReference>
</ActivateGiftCardRequest>
Required Parameters
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
  }
}
Reseller Use Case
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"
  }
}
Product Use Case
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"
  }
}
Optional Parameters
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

Parameter Name Constraints Type Description
activationRequestId Max 40 Characters

Prefixed with partnerID

AlphaNumeric
String A unique identifier for every ActivateGiftCard request. You must generate a new value for every Activate request (except for retries). (See notes below.)
cardInfo Object Object that contains cardNumber, cardStatus, expirationDate, value parameters.
cardNumber Pre-defined value Int The 16-digit WAC number (example: 1400000005567585358)
cardStatus String Status of card after this operation. Success value: Fulfilled
expirationDate Not provided on cards issued in NA, CA & AU Unix-Date Expiration date. Card cannot be claimed by customer after this date. (Never present for cards issued in the United States, Canada, or Australia.)
value Object Object that holds the currencyCode and amount parameters.
currencyCode ISO-4217 Currency Code String A ISO-4217 currency code that specifies the currency of the card.
amount Long Card amount, in card currency.
status String Outcome of this operation. Success value: SUCCESS

Example Responses

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

Parameter Name Req. Constraints Type Description
activationRequestId Yes Max 40 Characters

Prefixed with partnerID

AlphaNumeric
String A unique identifier for every ActivateGiftCard request. You must generate a new value for every Activate request (except for retries). (See notes below.)
partnerID Yes Pre-defined value String A unique identifier (CASE SENSITIVE, 1st letter is capitalized and the next four are lower case) provided by the Amazon team. This value appears in the payload of every AGCOD Gateway request.
cardNumber Yes Pre-defined value Int The 16-digit WAC number (example: 1400000005567585358)
externalReference Optional Max 100 characters String The externalReference field may be used to store a convenient mapping to assist you with tracking. For example, you might specify insurance claims, kiosks, customer cases, order Ids, reseller customer accounts, or store information within the externalReference field.

Example Request

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

Parameter Name Constraints Type Description
activationRequestId Max 40 Characters

Prefixed with partnerID

AlphaNumeric
String A unique identifier for every ActivateGiftCard request. You must generate a new value for every Activate request (except for retries). (See notes below.)
cardInfo Object Object that contains cardNumber, cardStatus, expirationDate, value parameters.
cardNumber Pre-defined value Int The 16-digit WAC number (example: 1400000005567585358)
cardStatus String Status of card after this operation. Success value: Fulfilled
expirationDate Not provided on cards issued in NA, CA & AU Unix-Date Expiration date. Card cannot be claimed by customer after this date. (Never present for cards issued in the United States, Canada, or Australia.)
value Object Object that holds the currencyCode and amount parameters.
currencyCode ISO-4217 Currency Code String A ISO-4217 currency code that specifies the currency of the card.
amount Long Card amount, in card currency.
status String Outcome of this operation. Success value: SUCCESS

Example Response

XML
<DeactivateGiftCardResponse>
    <cardInfo>
        <cardStatus>AwaitingActivation</cardStatus>
        <cardNumber>1700000005489413</cardNumber>
    </cardInfo>
    <status>SUCCESS</status>
    <activationRequestId>Awssb0327141418PM</activationRequestId>
</DeactivateGiftCardResponse>
JSON
{
  "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

Parameter Name Req. Constraints Type Description
statusCheckRequestId Yes Max 40 Characters

Prefixed with partnerID

AlphaNumeric
String A unique identifier for every ActivationStatusCheck request. You must generate a new value for every Activated request (except for retries). (See notes below.)
partnerID Yes Pre-defined value String A unique identifier (CASE SENSITIVE, 1st letter is capitalized and the next four are lower case) provided by the Amazon team. This value appears in the payload of every AGCOD Gateway request.
cardNumber Yes Pre-defined value Int The 16-digit WAC number (example: 1400000005567585358)
externalReference Optional Max 100 characters String The externalReference field may be used to store a convenient mapping to assist you with tracking. For example, you might specify insurance claims, kiosks, customer cases, order Ids, reseller customer accounts, or store information within the externalReference field.

Example Request

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

Parameter Name Constraints Type Description
statusCheckRequestId Max 40 Characters

Prefixed with partnerID

AlphaNumeric
String A unique identifier for every ActivationStatusCheck request. You must generate a new value for every Activation request (except for retries). (See notes below.)
cardInfo Object Object that contains cardNumber, cardStatus, expirationDate, value parameters.
cardNumber Pre-defined value Int The 16-digit WAC number (example: 1400000005567585358)
cardStatus String Status of card after this operation. Success value: Fulfilled
expirationDate Not provided on cards issued in NA, CA & AU Unix-Date Expiration date. Card cannot be claimed by customer after this date. (Never present for cards issued in the United States, Canada, or Australia.)
value Object Object that holds the currencyCode and amount parameters.
currencyCode ISO-4217 Currency Code String A ISO-4217 currency code that specifies the currency of the card.
amount Long Card amount, in card currency.
status String Outcome of this operation. Success value: SUCCESS
Active
<ActivationStatusCheckResponse>
    <cardInfo>
        <cardStatus>Activated</cardStatus>
        <cardNumber>1700000005489413</cardNumber>
    </cardInfo>
    <status>SUCCESS</status>< statusCheckRequestId> Awssb0327141418PM
</statusCheckRequestId>undefined</ActivationStatusCheckResponse>
Not Active
<ActivationStatusCheckResponse>
    <cardInfo>
        <cardStatus>AwaitingActivation</cardStatus>
        <cardNumber>1700000005489413</cardNumber>
    </cardInfo>
    <status>SUCCESS</status>
    <statusCheckRequestId>Awssb0327141418PM</statusCheckRequestId>
</ActivationStatusCheckResponse>
Active
{
  "cardInfo": {
    "cardNumber": "1700000005489413",
    "cardStatus": "Activated",
    "value": null
  },
  "status": "SUCCESS",
  "statusCheckRequestId": " Awssb0327141418PM"
}
Not Active
{
  "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.

JSON Long Form
{
  "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"}"
  }
}
XML Long Form
<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>
JSON Short Form
{
  "value": {
    "currencyCode": "USD",
    "amount": 150
  },
  "activationRequestId": "Awssb0327141418PM",
  "cardNumber": "6215366885893081",
  "partnerId": "Apppt",
  "externalReference": "{"promoCode":"855238"}",
  "transactionSource": {
    "id": "{"institutionId" : "97263700007" , "sourceId" : "84000000109", "UPC" : "ABC1234"}"
  }
}
XML Short Form
<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


Last updated: Jul 18, 2022