REVERSE

Used to refund (aka reverse) an AM Cash Miles redemption.
POST /checkout/amcash/reverse

Take a look at our OpenAPI (Swagger-Spec) schema to learn more about the API calls.

Prior to requesting a “reversal”, a valid “redemption request”/“redemption response” must be exchanged in order to create the txnConfirmationNumber required for the “reversal”.

Reversal process

  1. The sales associate makes a REVERSAL request at checkout by submitting the redemptionConfirmationNumber for the transaction in question.
  2. The POS system will prompt the sales associate to accept the return and issue a full monetary refund.
  3. Once completed, a response message containing all relevant fields will be returned to the POS system.

Sample request

curl -X POST \
  https://cert.airmilesapis.ca/checkout/amcash/reverse \
  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ...' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
  "acquirerId": "100000",
  "cardEntryMode": "SWIPE",
  "collectorNumber": "84095202006",
  "dateTime": "1972-07-16T13:32:00+0400",
  "deviceId": "001",
  "redemptionConfirmationNum": "10000000000",
  "sponsorCode": "LOY1",
  "storeId": "0001",
  "traceId": "999999999999",
  "vendorId": "100087"
}'

Header parameters

Parameter Description
Authorization Token from authentication.
Content-Type Default value: application/json
cache-control Default value: no-cache

Query parameters

Parameter Description
none none

Body parameters

* Required field

Parameter Description
acquirerId* The acquirer ID identifies the party that sends the request, usually this is the partner. To be provided by AIR MILES
cardEntryMode* The method that was used to enter the AIR MILES account number.
collectorNumber* The customer’s AIR MILES account number.
dateTime* Date and time when the request was sent. (see ISO-8601)
deviceId* ID number used to identify the POS terminal currently in use.
redemptionConfirmationNum* Number used to identify the redemption transaction to reverse (void).
sponsorCode* Alpha-numeric value used to identify the Partner. To be provided by AIR MILES
storeId* Alpha-numeric value used to identify the Partner’s location. To be provided by Partner
traceId* Partner’s unique transaction tracking number. To be provided by Partner
vendorId* Number used to identify the Partner and for downstream financial payments. To be provided by AIR MILES

Sample response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 29 Oct 2018 15:27:34 GMT
{
    "acquirerId": "100000",
    "availableCashBalance": "95",
    "availableDollarAmount": "10",
    "cashBalance": "120",
    "collectorNumber": "80000000001",
    "dateTime": "2019-01-30T04:39:59.503-0400",
    "deviceId": "001",
    "dreamBalance": "550",
    "message": "Approved",
    "milesReversed": "95",
    "responseCode": "0000",
    "sponsorCode": "1234",
    "storeId": "0001",
    "traceId": "000012345678",
    "transDateTime": "2019-01-30T04:39:59",
    "txnConfirmationNumber": "0000",
    "unitsReversed": "1",
    "unitValueAMCash": "95",
    "unitValueDollars": "10",
    "vendorId": "1234567890"
}

Response model

Includes all “Request” parameters listed above, plus the additional ones below.

Parameter Description
availableCashBalance The remaining available daily limit of AM Cash redemptions, in Miles (post-transaction); or the Collector’s total Miles balance - whichever is lower. Standard default is $750 CAD or 7,125 Miles per day
availableDollarAmount The dollar ($) amount available that the Collector can redeem. This value is rounded down to the nearest $10
cashBalance The Collector’s AM Cash account balance in Miles (post-transaction).
dreamBalance The Collector’s “AIR MILES Dream” account balance.
message Text description of the response code.
milesReversed The number of AM Cash miles reversed (refunded).
responseCode Number indicating the result of the transaction.
transDateTime Date and time when the response was sent. (see ISO-8601)
txnConfirmationNumber The confirmation number returned upon a successful redemption. This value should be printed on the purchase receipt and is required to process a reversal. To be provided by AIR MILES
unitsReversed The number of AM Cash units reversed (refunded).
unitValueAMCash The number of AM Cash miles required for a single redemption unit.
unitValueDollars The dollar ($) value for a single unit of redemption.

Status/Response codes

Status Code Response Code Display Message Description
200 0000 Approved The transaction was successful. The POS terminal AND receipt should display the appropriate information.
202 0001 Approved - balance suppressed The transaction was successful, however the Collector opted to not view their rewards balances. The printed receipt MUST NOT show the Collector’s ‘Cash’/‘Dream’ balances, or the available “AM Cash” that can be redeemed.
401 0002 Collector account inactive The Collector account is not active. Please ask the Collector to visit the airmiles.ca self-serve page, online chat support, or contact our call-center.
408 0008 Transaction timeout The transaction timed out when a request was sent to the “Instant POS” Switch. The Partner’s Switch/POS Terminal should retry the request one (1) time. If a cashier receives this error, they should escalate the issue as indicated in the “AM Cash - Sponsor Escalation Guide”.
403 0009 Card not swiped or scanned Redemption offers will not be sent if the Collector Card is not presented. The Collector Card is physically required to perform instant cash redemptions. Please ask the Collector to visit the airmiles.ca self-serve page, online chat support, or contact our call-center to request a replacement card.
401 0025 Invalid collector number The Collector number is invalid. Please ask the Collector to visit the airmiles.ca self-serve page, online chat support, or contact our call-center to request a replacement card.
400 0035 Invalid request parameter A mistake was made when submitting the request. Please correct the error and try again.
202 0051 Insufficient AIR MILES reward Miles The Collector has not earned enough in their “AIR MILES Cash” balance for the requested redemption amount. Please ask the Collector to go to airmiles.ca and check their redemption/earning history.
400 0057 Invalid redemption confirmation number The redemptionConfirmationNumber submitted is invalid. Please resubmit the request with the correct Redemption Confirmation Number.
202 0065 Exceeded daily redemption limit The Collector has exceeded the daily redemption limit. The Collector’s account has exceeded the maximum daily redemption amount. Please ask the Collector to wait until the following day to redeem more Cash miles.
202 0066 Insufficient basket size The Collector’s basket size is too small to make a redemption. The purchase amount is not enough to make a redemption. Ask the customer if they wish to add more items to their basket in order to make an AM Cash redemption.
408 0067 Offer is temporarily unavailable The offer being requested is temporarily unavailable. Please advise the Collector to try redeeming this offer at a later time.
409 0080 Reversal window expired The reversal window for the redemption has expired; meaning a reversal can no longer be submitted for this transaction. This usually happens when a reversal is attempted after 3:00 AM the day after the original transaction. Any reversals that are attempted past the 3:00 AM time-frame should be refunded to the customer via in-store credit or gift card. Please DO NOT RETURN CASH to the customer.
503 0092 Scheduled outage The system is unavailable due to scheduled maintenance. No requests can be sent.
500 0096 Server error or no response An unknown error occurred while calling the “Instant POS” Switch". The Sponsor Switch/POS Terminal should retry one time and if the error persists, they should escalate the issue as indicated in the “AM Cash - Sponsor Escalation Guide”.
none none Missing or invalid “Bearer token” No valid “Bearer Token” present. Please generate a valid “Bearer” Token and submit to continue."

Handling timeouts

A request timeout has occurred if either of the following scenarios is true:

  • You received a “response code” of 0008
  • You received no response at all

Upon experiencing a request timeout, your POS terminal should immediately attempt a retry of the same transaction request. The “Retry Request” must match the initial request exactly.

If the new request does not match exactly with the initial request, the system will not recognize it as a “retry”, but will register it as a brand new transaction. If the request continues to timeout/fail, an error message should be displayed to the cashier and/or the customer, as suggested in the section Displaying the reversal result.

If at any time, our real-time checkout encounters an internal problem or network error while trying to return a “redemption response”; the redemption request will be automatically cancelled, thereby ensuring the customer is not charged for a redemption that could not be delivered.

For all other response codes; when a particular code is received (e.g., 0002, 0096, etc.), the appropriate message should be displayed to the cashier, as shown in POS Workflows > Redemption.