AIR MILES Cash

• 1. Authentication & Authorization
• 2. API Library
• 2.1. ECHO
• 2.2. INQUIRE
• 2.3. REDEEM
• 2.4. REVERSE
• 3. AIR MILES Cash API Docs
• 4. Point-of-Sale Terminal Workflows
• 5. File Reconciliation
• 6. OpenAPI (Swagger-Spec)

1 - Authentication & Authorization

For more information on “Auth0” and the various authentication flows, click the button below.

Which Authentication Flow Should I Use?

2 - API Library

This section includes the four (4) AIR MILES Cash API endpoints listed below. Each page offers a brief summary of the API endpoint in question, common use-case scenarios, and sample request/response messages with response codes.

API endpoints

ECHO

Used to test and confirm that the real-time checkout platform is up and ready to process requests.

INQUIRE

Used to retrieve account balances and AIR MILES Cash offer information.

REDEEM

Used to redeem AIR MILES Cash Miles from a Collector’s account to be used towards their purchase.

REVERSE

Used to refund (aka reverse) an AM Cash Miles redemption.

Idempotent requests

All the API calls shown above (excluding ECHO & INQUIRY) support idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to redeem miles from a Collector does not receive a response due to a network connection error, you can retry the request with the same idempotency key to guarantee that additional miles aren’t accidentally redeemed from the Collector’s account.

What is an “Idempotency Key”

An “Idempotency Key” is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions.

Sample header with Idempotency

curl -X POST https://cert.airmilesapis.ca/checkout/amcash/echo \
    -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ...' \
    -H 'Content-Type: application/json' \
    -H 'Idempotency-Key: 123e4567-e89b-12d3-a456-426655440000' \
    -d '{

Handling request/response messages

As described above, the RESTful specification defines a transaction as a pair of request and response messages that are used for information interchange.

Handling request timeouts

A request timeout has likely occurred if either of the following are true.

• You received a Response Code of 0008
• You didn’t receive any response at all

Upon experiencing a request timeout, your POS terminal should immediately attempt to retry the same request. The reattempted request MUST be identical to the initial request.

If at any time, AIR MILES real-time encounters an internal problem or network error while trying to return a “redemption response” to the partner, the redemption request will be automatically cancelled. Thereby ensuring the customer is not charged for a redemption that could not be redeemed.

Status/response codes

2.1 - ECHO

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

This test ensures there are no known connectivity issues between AIR MILES and our partners. The ECHO call functions similarly to a standard ‘ping’ request, determining if a client or host is online and accessible. To receive a “Bearer Token” and authorize your request, use the client_id/client_secret provided to you by AIR MILES.

Sample request

curl -X POST \
  https://cert.airmilesapis.ca/checkout/amcash/echo \
  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ...' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
  "deviceId": "001",
  "sponsorCode": "LOY1",
  "storeId": "0001",
  "traceId": "000012345678",
  "vendorId": "100087"
}'

Header parameters

Query parameters

Body parameters

* Required field

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
{
  "deviceId": "001",
  "message": "Approved",
  "responseCode": "0000",
  "sponsorCode": "1234",
  "storeId": "0001",
  "traceId": "000012345678",
  "transDateTime": "2019-01-30T03:59:03",
  "vendorId": "1234567890"
}

Response model

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

Status/Response codes

2.2 - INQUIRE

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

Used to retrieve account balances and AIR MILES Cash offer information. Once a Partner receives a response, the POS terminal can acquire the reward miles Cash/Dream balances.

Sample request

curl -X POST \
  https://cert.airmilesapis.ca/checkout/amcash/inquire \
  -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",
  "instantMessage": "en-CA",
  "postTaxBasketAmount": "16.12",
  "sponsorCode": "LOY1",
  "storeId": "0001",
  "traceId": "999999999999",
  "vendorId": "100087"
}'

Header parameters

Query parameters

Body parameters

* Required field

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",
    "availableOfferUnits": "1",
    "cashBalance": "120",
    "collectorNumber": "1234567890123456789",
    "dailyOfferLimit": "10",
    "dateTime": "2019-01-30T04:39:59.503-0400",
    "deviceId": "001",
    "dreamBalance": "545",
    "message": "Approved",
    "offerDescEn": "Sample offer description in English.",
    "offerDescFr": "Exemple de description de l'offre en français.",
    "offerId": "1111111111",
    "offerType": "RGL",
    "responseCode": "0000",
    "sponsorCode": "1234",
    "storeId": "0001",
    "traceId": "000012345678",
    "transDateTime": "2019-01-30T11:41:55",
    "unitValueAMCash": "95",
    "unitValueDollars": "10.00",
    "vendorId": "555555"
}

Response model

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

Conditional parameters

The optional data elements contain information required to show the number of miles that can be redeemed and the discount that would be applied towards the purchase.

Status/Response codes

2.3 - REDEEM

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

To redeem Miles, the Collector’s card must be either scanned, swiped, or pre-registered (e.g., e-commerce site).

Redemption process

1. The sales associate makes a redemption request at checkout by submitting a dollarRedeemRequest.
2. The maximum redemption amount is displayed on-screen, which is less than or equal to the postTaxBasketAmount.
3. The sales associate selects the appropriate redemption amount (unitsRedeemed) before completing the transaction.

Sample request

curl -X POST \
  https://cert.airmilesapis.ca/checkout/amcash/redeem \
  -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",
  "dollarRedeemRequest": "16.12",
  "instantMessage": "en-CA",
  "originalPostTaxBasketAmount": "16.12",
  "originalPreTaxAmount": "16.12",
  "postTaxBasketAmount": "16.12",
  "sponsorCode": "LOY1",
  "storeId": "0001",
  "traceId": "999999999999",
  "vendorId": "100087"
}'

Header parameters

Query parameters

Body parameters

* Required field

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",
    "dailyOfferLimit": "10",
    "dateTime": "2019-01-30T04:39:59.503-0400",
    "deviceId": "001",
    "dreamBalance": "550",
    "message": "Approved",
    "milesRedeemed": "95",
    "offerDescEn": "Sample offer description in English.",
    "offerDescFr": "Exemple de description de l'offre en français.",
    "offerId": "1111111111",
    "offerType": "RGL",
    "responseCode": "0000",
    "sponsorCode": "1234",
    "storeId": "0001",
    "traceId": "000012345678",
    "transDateTime": "2018-10-27T02:25:10",
    "txnConfirmationNumber": "0000",
    "unitsRedeemed": "1",
    "unitValueAMCash": "95",
    "unitValueDollars": "10.00",
    "vendorId": "555555"
}

Response model

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

Status/Response codes

2.4 - 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

Query parameters

Body parameters

* Required field

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.

Status/Response codes

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.

3 - AIR MILES Cash API Docs

4 - Point-of-Sale Terminal Workflows

Display Types

Pop-up displays

From here onward, we are assuming that your terminals can display a pop-up window over the main terminal display. However if your terminals have a more limited display functionality, a similar display interface can be built by integrating the new “AIR MILES Cash” elements into the main display area; this is shown in figure 1 below.

Text-based displays

There are also display mockups for text-based POS terminals. These mockups assume that the POS terminal has at least twenty (20) columns and four (4) rows. Throughout this section, the two mockups will be shown side-by-side where possible, to contrast the different interfaces.

Processing a Redemption

Upon receiving an AM Cash Inquiry response, the POS terminal should display relevant offer information to the Collector, which at a minimum should include the remaining daily limit of AM Cash units the Collector can request.

AIR MILES Cash Inquiry

In the example above, the AM Cash “Inquiry” screen displays the following key values:

As previously stated, an offer is returned ONLY if the Collector has enough reward Miles to redeem at least a single unit AND have not reached their daily redemption cap. If no offer is returned, the POS terminal won’t display any of the information shown above.

The Collector can redeem for a minimum of 95 reward Miles (which is equivalent to $10.00 CAD.), as well as further increments of 95 reward Miles.

If the AM Cash inquiry response has an offer available for the Collector, the POS terminal should give the cashier a visual cue, so they can ask the Collector for redemption.

We recommend using one of the following options:

Preferred method

Pop-up window with AIR MILES Cash information.

For embedded interfaces

Blinking cue for embedded AIR MILES Cash section.

Alternative method

If there is no way to do either of the above, have the cashier click an on-screen button to activate the AIR MILES Cash section.

Displaying on a text-based POS

Similar to the GUI-based screens shown above, a text-based terminal should display the minimum and increment values together with the maximum allowed (based on the qualifying amount). The Collector at this point has the option to either enter an amount or cancel and proceed with the remaining purchase flow.

Here’s an example of what a text-based display would look like.

Displaying the Redemption

After the redemption request is sent and a response is received by the POS terminal, the redemption information can be shown as follows.

The POS terminal should display the following:

Transaction confirmation number

txnConfirmationNumber

Number of reward Miles redeemed

unitValueAMCash * unitsredeemed

Remaining reward Miles for redemption

cashBalance / unitValueAMCash

Displaying on a text-based POS

A text-based POS terminal could display the redemption information as follows.

Following this screen, the rest of the payment flow continues normally.

Printing the receipt

This section provides a mockup of what a receipt could look like.

The receipt shown above follows the examples that has been used so far and shows the following:

Common basket details

1. Partner details (business name, address, phone # etc.).
2. Purchase details (item/basket info - includes a negative balance if returning a product).
3. Sub-total, added sales tax, and total.
4. Transaction confirmation number together with the dollar/monetary amount of the redemption.

AIR MILES specific basket details

1. Masked Collector number (at least 3-digits in the middle must be masked, and the last four digits visible).
2. Base and bonus AIR MILES reward Miles redeemed.
3. Available “AIR MILES Cash” Rewards Miles balance.
4. Available “AIR MILES Dream” Rewards Miles balance.

Processing a Reversal

In order to reverse a redemption all that is needed is the original redemption confirmation number, as the redemption is fully reversed (no partial reversals are done).

This is demonstrated in figure 7 below:

The AM Cash reversal function should be made available to the cashier by way of a button or on-screen-display. Once this screen is displayed the cashier will need to enter the transaction confirmation number (txnConfirmationNumber) and press a key to process the reversal (such as the Void button shown in the figure above).

Displaying the reversal

After a reversal request has been processed, a response containing a new transaction confirmation number should be received.

This is demonstrated in figure 8 below.

The POS terminal should display the total Miles refunded (milesReversed), the available reward Miles (cashBalance) and the new reversal confirmation number (txnConfirmationNumber).

Printing the receipt

This section provides a mockup of how a receipt showing balances and redemption information could be organized.

See figure 9 below for more details:

The receipt shown above follows the examples that has been used so far and shows the following:

Common basket details

1. Partner details (business name, address, phone # etc.).
2. Purchase details (item/basket info - includes a negative balance if returning a product).
3. Sub-total, added sales tax, and total.
4. Transaction confirmation number together with the dollar/monetary amount of the redemption.

AIR MILES specific basket details

1. Masked Collector number (at least 3-digits in the middle must be masked, and the last four digits visible).
2. Base and bonus AIR MILES reward Miles voided/reversed (calculated by the partner).
3. Available “AIR MILES Cash” Rewards Miles balance.
4. Available “AIR MILES Dream” Rewards Miles balance.

5 - File Reconciliation

A Reconciliation process has been established to ensure that successful “Redemption” and “Reverse” transactions match in both the partner’s systems and AIR MILES systems. This matching ensures that the number of transactions in both systems and the transaction values (e.g., amounts, dates) are identical.

What are reconciliation files

The Reconciliation files are sent to the Partner at regular intervals, and contain all successful Redemptions and Reversals that were reconciled on a given day.

The following sections describe the Reconciliation process, files, formats, and file transfer methods.

File formats and schedules

Each Reconciliation file contains the following:

• Header Records x2
• Trailer Records x2
• Detailed Records 0 or more

Reconciliation files are text-based and have a specific format (described below), use delimiters to separate fields, and are uncompressed & un-encrypted. Records within the reconciliation file use the standard ASCII character set, where fields within a record are separated by double percent characters (%%), and records are separated by a new line character at the end of each line.

Since fields in the file records are delimited with percentage characters (%%) there is no need for fillers or padding. As an example, the “amount” field is defined as Numeric and 4 characters in length, so in order to send 190 Miles, it is enough to send just those three digits (i.e., there is no need to send 0190). Similarly, the “Card Terminal ID” is defined as Alphanumeric and 16 characters in length, so in order to send the characters SPON000101 there is no need to append filler spaces at the end of those characters.

During normal processing times, reconciliation files will be created at regular intervals. For resubmissions, the files may contain more (or less) than 24-hours of transactions, and may include a different time range. However, in all instances the “Local Transaction Date/Time” of all records within the file must be between the BeginExtractDate and EndExtractDate values in the “Header” and “Trailer” records (see an example of the file format below).

Files sent to the partner

The naming of the reconciliation file uses the following format:

RECON_LMG_YYYYMMDD.txt

As an example, a reconciliation file created on July 19, 2020 would be named RECON_LMG_20200719.txt.

Sample file contents

H%%20100718070925%%20100718221523
S%%95001%%20100718070925%%20100718221523
D%%2210%%80000000001%%190%%358%%162824%%20100718%%39000000883%%SPON000101%%20.00
D%%2210%%80000000001%%190%%344%%070925%%20100718%%39000000842%%SPON001101%%20.00
D%%2210%%80000000001%%190%%355%%221523%%20100718%%39000000750%%SPON000121%%20.00
D%%2430%%80000000001%%190%%359%%162940%%20100718%%39000000883%%SPON000105%%20.00
D%%2210%%80000000001%%190%%2909%%083455%%20100718%%39000000644%%SPON000106%%20.00
D%%2430%%80000000001%%190%%2912%%143448%%20100718%%39000000636%%SPON000106%%20.00
D%%2210%%80000000001%%190%%341%%090658%%20100718%%39000000693%%SPON000101%%20.00
D%%2430%%80000000001%%190%%345%%151102%%20100718%%39000000842%%SPON000101%%20.00
D%%2430%%80000000001%%190%%2911%%143455%%20100718%%39000000644%%SPON000101%%20.00
D%%2210%%80000000001%%95%%327%%074551%%20100718%%39000000677%%SPON000111%%10.00
F%%95001%%20100718070925%%20100718221523%%10
T%%20100718070925%%20100718221523%%12

Header and trailer record templates

As mentioned above, the reconciliation files contain two (2) header records, two (2) trailer records, and zero (0) or more detailed records.

Header 1

H%%BeginExtractDate%%EndExtractDate

Header 2

S%%CardAcceptorId%%BeginExtractDate%%EndExtractDate

Trailer 1

F%%CardAcceptorId%%BeginExtractDate%%EndExtractDate%%NumOfDetailRowsInFile

Trailer 2

T%%BeginExtractDate%%EndExtractDate%%NumOfDetailRowsInFile+2

Reconciliation file fields

File transmission method

The accepted transmission method for receiving the Reconciliation file is via SFTP (Simple File-Transfer-Protocol).

Contact us for more details at partnersupport@loyalty.com.

6 - OpenAPI (Swagger-Spec)