ECRS Logo
API docs by Redocly

Third-Party Loyalty Redemption API (1.0)

Download OpenAPI specification:Download

This RESTful API provides third parties with the capability to check and decrement the loyalty balances for customers within the CATAPULT® database. Error codes utilized by the bad-request responses include:

  1. Not Authorized.
  2. Invalid customer.
  3. Invalid loyalty program.
  4. Data Access Error.
  5. Insufficient Balance.
  6. Pre-Authorization Already Complete.
  7. Pre-Authorization Identifier Duplicated with Differing Values.
  8. Completion Identifier Duplicated with Differing Values.
  9. Cannot authorize 0-points.
  10. No Corresponding Pre-Authorization.

Balance-Check

Get's a customer's current point balance which can be used for providing discounts.

Authorizations:
Pre-Shared Key
query Parameters
customer
required
string [ 1 .. 16 ] characters
Example: customer=40100637000240

The customers account / card number.

requestor
required
string [ 1 .. 62 ] characters
Example: requestor=Third-Party

An identifier for the entity making the request.

time
required
string <date-time>
Example: time=2018-03-20T09:12:28Z

The date/time of the requestor in RFC-3339 date-time format.

programId
string [ 1 .. 32 ] characters
Example: programId=1-0

The id of the loyalty program to check the balance on. If omitted then the default loyalty program will be used.

Responses

Response Schema: application/json
customer
required
string [ 1 .. 16 ] characters

The customers account / card number. Echoed from the request.

requestor
required
string [ 1 .. 62 ] characters

The identifier for the entity requesting the balance. Echoed from the request.

time
required
string <date-time>

The time of the requestor in RFC-3339 date-time format. Echoed from the request.

programId
string

The id of the loyalty program for which this balance check applies. Echoed from the request.

balance
required
integer

The current available balance of the loyalty program.

Response Schema: application/json
code
required
integer

A numeric code indicating the type of error.

description
required
string

A description of the error.

Response samples

Content type
application/json
{
  • "customer": "40100637000240",
  • "requestor": "Third-Party",
  • "time": "2018-03-20T09:12:28Z",
  • "programId": "1-0",
  • "balance": 163
}

Pre-Authorization

Initiates a temporary hold on a specified number of loyalty points for a customer. Pre-authorizing the loyalty points ensures the customer has enough to redeem for the discount. These points are reserved exclusively for a pending transaction and cannot be used elsewhere until the transaction is either completed or the hold expires. The hold duration is fixed at one hour and cannot be customized.

Authorizations:
Pre-Shared Key
Request Body schema: application/json
customer
required
string [ 1 .. 16 ] characters

The customers account / card number.

requestor
required
string [ 1 .. 62 ] characters

An identifier for the entity making the request.

time
required
string <date-time>

The date/time of the requestor in RFC-3339 date-time format.

programId
string [ 1 .. 32 ] characters

The id of the loyalty program to pre-authorize against If ommitted then the default loyalty program will be used.

discount
string <= 128 characters

An optional description of the discount for which the pre-authorized points are being used.

amount
integer >= 1

The number of points to pre-authorize. If omitted then all points will be pre-authorized, at least 1-point is always required even if omitted. An error will be returned if not enough points are available or if the pre-auth amount is 0.

identifier
required
string <uuid>

A UUID used for tracking the request and preventing duplicates when retrying a failed request.

If the same uuid is repeated in multiple identical requests then the repeated requests will return as successful without changing the customers available point balance. This allows requests to be retried following a timout without the risk of duplicating a point reduction. When a successful response is duplicated for this reason the dupe flag will be set to true.

If the request has already been completed then an error will be returned.

Responses

Response Schema: application/json
customer
required
string [ 1 .. 16 ] characters

The customers account / card number. Echoed from the request.

requestor
required
string [ 1 .. 62 ] characters

An identifier for the entity making the request. Echoed from the request.

time
required
string <date-time>

The date/time of the requestor in RFC-3339 date-time format. Echoed from the request.

progamId
required
string [ 1 .. 32 ] characters

The id of the loyalty program to pre-authorize against.

discount
string <= 128 characters

An optional description of the discount for which the pre-authorized points are being used.

amount
required
integer

The number of points pre-authorized from the customers account.

identifier
required
string <uuid>

An optional description of the discount for which the pre-authorized points are being used.

balance
required
integer

The available/remaining balance of the customers account for the current program.

dupe:
boolean
Default: false

True if this response is a dupe of a prior response with the same identifier.

Response Schema: application/json
code
required
integer
description
required
string
identifier
string <uuid>

The identifier for the request, if available.

balance
integer

If the authentication, customer, balance, and loyalty program were valid. The the balance of the customer will be returned.

Request samples

Content type
application/json
Example
{
  • "customer": "40100637000240",
  • "requestor": "Third-Party",
  • "time": "2019-08-24T14:15:22Z",
  • "discount": "15c",
  • "identifier": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Response samples

Content type
application/json
{
  • "customer": "40100637000240",
  • "requestor": "Third-Party",
  • "time": "2019-08-24T14:15:22Z",
  • "progamId": "1-0",
  • "discount": "15c",
  • "amount": 100,
  • "identifier": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "balance": 63,
  • "dupe:": false
}

Completion

Called when a transaction is complete, this can either complete a pre-authorization, or be used to apply a complete transaction.

Authorizations:
Pre-Shared Key
Request Body schema: application/json
customer
string [ 1 .. 16 ] characters

The customers account / card number.

requestor
required
string [ 1 .. 64 ] characters

An identifier for the entity making the request.

time
required
string <date-time>

The date/time of the requestor in RFC-3339 date-time format.

programId
string [ 1 .. 32 ] characters

The id of the loyalty program to pre-authorize against. If ommitted then the loyalty program from the pre-auth will be used if available. Otherwise, the default loyalty program will be used.

discount
string <= 128 characters

An optional description of the discount for which the pre-authorized points are being used.

amount
integer >= 0

The number of points to deduct.

If omitted and there is not corresponding pre-auth then all points will be deducted from the customers account.

If omitted and there is a corresponding pre-auth then the amount from the pre-auth will be used.

An error will be returned if not enough points are available on the customers account.

identifier
required
string <uuid>

A UUID used for tracking the request and preventing duplicates when retrying a failed request.

If the same uuid is repeated in multiple identical requests then the repeated requests will return as successful without changing the customers available point balance. This allows requests to be retried following a timout without the risk of duplicating a point reduction. When a successful response is duplicated for this reason the dupe flag is set to true.

If the identifier matches the identifier for a preceding pre-auth request then that pre-auth will be updated with the completed amount and made permanent.

If the amount on a completion request is 0 then any matching pre-auth will be cancelled. Otherwise a zero amount will result in an error.

Responses

Response Schema: application/json
customer
required
string [ 1 .. 16 ] characters

The customers account / card number. Echoed from the request.

requestor
required
string [ 1 .. 62 ] characters

An identifier for the entity making the request. Echoed from the request.

time
required
string <date-time>

The date/time of the requestor in RFC-3339 date-time format. Echoed from the request.

programId
required
string [ 1 .. 32 ] characters

The id of the loyalty program to complete a transaction against.

discount
string <= 128 characters

An optional description of the discount for which the pre-authorized points are being used.

amount
required
integer

The number of points deducted from the customers account.

identifier
required
string <uuid>

The UUID identifier for this request. Echoed from the request.

balance
required
integer

The available/remaining balance of the customers account.

dupe
boolean
Default: false

True if this response is a dupe of a prior response with the same identifier.

Response Schema: application/json
code
required
integer
description
required
string
identifier
string <uuid>

The identifier of the request if avaiable.

balance
integer

If the authentication, customer, balance, and loyalty program were valid. The the balance of the customer will be returned.

Request samples

Content type
application/json
Example
{
  • "customer": "40100637000240",
  • "requestor": "Third-Party",
  • "time": "2019-08-24T14:15:22Z",
  • "discount": "15c",
  • "amount": 100,
  • "identifier": "14d3030c-3b61-4070-b902-342f80e99364"
}

Response samples

Content type
application/json
{
  • "customer": "40100637000240",
  • "requestor": "Third-Party",
  • "time": "2019-08-24T14:15:22Z",
  • "programId": "1-0",
  • "discount": "15c",
  • "amount": 100,
  • "identifier": "14d3030c-3b61-4070-b902-342f80e99364",
  • "balance": 63,
  • "dupe": false
}