ECHO

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

POST /checkout/amcash/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.

Note

It is highly recommended that all Partners use the ECHO test upon starting their integration, to ensure both systems can communicate properly. Also at the partner’s discretion, we recommend performing periodic ECHO tests at regular intervals to be notified immediately in the case of any unforeseen outages.

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

Parameter	Description
Authorization	Token from authentication. Example: `Bearer eyJhbGciOiJSUzI1NiIsI…`
Content-Type	Default value: `application/json`
cache-control	Default value: `no-cache`

Query parameters

Parameter	Description
none	none

Body parameters

* Required field

Parameter	Description
`deviceId`*	ID number used to identify the POS terminal currently in use. Example: `"001"`
`sponsorCode`*	Alpha-numeric value used to identify the Partner. Example: `"LOY1"` To be provided by AIR MILES
`storeId`*	Alpha-numeric value used to identify the Partner’s location. Example: `"0001"` To be provided by Partner
`traceId`*	Partner’s unique transaction tracking number. Example: `"000012345678"` This value can be recycled after a year To be provided by Partner
`vendorId`*	Number used to identify the Partner and for downstream financial payments. Example: `"555555"` 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
{
  "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.

Parameter	Description
`message`	Text description of the response code. Example: `"Approved"`
`responseCode`	Number indicating the result of the transaction. Example: `"0000"` `0000`: Request processed successfully `0001`: Approved (balance suppressed). `0002`: Collector profile inactive. `0005`: Unable to redeem (balance suppressed). `0006`: Unable to redeem. `0008`: Transaction timed-out, request needs to be retried. `0009`: Card not swiped or scanned. `0025`: Invalid collector number. `0035`: Invalid request parameter. `0051`: Insufficient AIR MILES Cash Miles. `0057`: Invalid redemption confirmation number. `0065`: Exceeded daily redemption limit. `0066`: Insufficient basket size. `0067`: Offer is temporarily unavailable. `0080`: Reversal window expired. `0092`: Scheduled outage. `0096`: System error.
`transDateTime`	Date and time when the response was sent. (see ISO-8601) Example: `"1972-07-16T13:32:00+0400"`

Note

Responses will always include the responseCode and message fields. If the original request was successful, the response will include the same parameters sent in the request body.

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.
`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”.
`400`	`0035`	Invalid request parameter	A mistake was made when submitting the request. Please correct the error and try again.
`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."