API docs by Redocly

CardAPI (v1)

License: Copyright

CardsAPI provides endpoints for card management, including retrieving card details and processing debit/credit transactions. It ensures secure processing of card data and provides a unified interface for applications that interact with card-based systems.

List of errors

Here is the list of internal error codes. These errors only appear in the context of an HTTP 500 status.

Code HTTP status
CARD-1 500
CARD-4 500
CARD-10 500
CARD-11 500

Here is the list of error codes

Code Description HTTP status
CARD-2 Invalid path 404
CARD-3 A parameter is missing or invalid in the body of the request (e.g., parameter sent as a string instead of an integer) 422
CARD-5 Missing token 401
CARD-6 Invalid token signature 400
CARD-7 Token expired 400
CARD-8 Invalid token 400
CARD-9 Unauthorized access to the service 403
CARD-14 Pass not found 404
CARD-15 Rate limit exceeded 429

Localization

The API supports response localization based on the Accept-Language HTTP header.
Supported locales: en, fr. Defaults to en if the header is absent or contains an unsupported locale.

Rate limiting

All routes are subject to a rate limit (requests per minute). When the limit is exceeded, the API returns an HTTP 429 with error code CARD-15.
The response includes the following headers:

  • X-RateLimit-Limit: maximum number of requests allowed per minute
  • X-RateLimit-Remaining: number of requests remaining in the current window
  • Retry-After: seconds to wait before retrying

Usages

Get API usages

Get API usages for a given period

Authorizations:
BearerToken
query Parameters
start_date
required
string <date>
Example: start_date=2024-01-01
end_date
required
string <date>
Example: end_date=2024-01-31
header Parameters
Accept-Language
string
Example: fr

Locale for response messages. Supported: en, fr. Defaults to en.

Responses

Response samples

Content type
application/json
{
  • "message": "The bearer token is missing",
  • "code": "CARD-5"
}

Status

Check that the API is available

Responses

Response samples

Content type
application/json
{
  • "OK": true
}

Search card by mode

Search for card by NFC number, barcode, or manual input (search_mode + q + store_id + point_of_sale_id).

Authorizations:
BearerToken
query Parameters
object (SearchByStorePos)
Example: search_mode=NFC&q=0438F2C2941190&store_id=62&point_of_sale_id=33

The different research methodologies

Responses

Response samples

Content type
application/json
Example
{
  • "type": "CASHBACK",
  • "pass": {
    }
}

Debit a cashback card

Debiting a cashback card on the ‘pass’ with ‘type‘=‘CASHBACK‘ obtained via the GET ‘/cards’ route.

Authorizations:
BearerToken
Request Body schema: application/json
required

The ticket id, the cashback pass and necessary debit data.

ticket_id
required
string <uuid>

The ticket’s lifetime unique ID in YOUR information system

ticket_number
string

Your ticket number

point_of_sale_id
required
integer

Point of Sale ID

device_id
required
string

Device ID

required
object

Payment movement

Responses

Request samples

Content type
application/json
{
  • "ticket_id": "9ffa8d1d-0765-11f1-88b3-0cc47a065898",
  • "ticket_number": "string",
  • "point_of_sale_id": 65,
  • "device_id": "string",
  • "payment_row": {
    }
}

Response samples

Content type
application/json
{
  • "ticket_id": "9ffa8d1d-0765-11f1-88b3-0cc47a065898",
  • "payment_row": {
    },
  • "receipt_row": {
    }
}