Gift Card API

Purpose

The Gift Card API enables external systems (such as POS terminals, e‑commerce sites or mobile apps) to interact with Resico’s gift card module. It exposes endpoints for retrieving card information, selling (activating) new cards, using cards for payment, reserving a card during checkout and cancelling reservations. Access to the API is controlled via bearer tokens and all requests use JSON【877301654772412†screenshot】.

Roles involved

• Developers/integrators – implement calls to the API from external applications and handle responses.
• System administrators – manage API keys, configure endpoints and monitor usage.
• Business analysts – ensure that the data returned by the API meets business requirements and adjust workflows accordingly.

Preconditions

• API credentials – obtain a bearer token and consumer key from Resico support. Without valid credentials requests will be rejected.
• HTTPS connection – all API calls must be made over HTTPS.
• Gift cards must exist in the system for GET, use or reservation operations. To sell new cards via the API, ensure the necessary card type and location codes are configured.

Navigation path

The API documentation can be viewed within the application by navigating to:

Gift Cards → API

This page details the endpoints, parameters and examples for each operation【877301654772412†screenshot】. Below is a summary.

Step‑by‑step procedure

The API uses RESTful endpoints. Each request must include the Authorization header with a bearer token and Content‑Type: application/json【877301654772412†screenshot】.

1. Get card info – Retrieve details of an existing card.
   • Endpoint: GET /api/giftcards/v1/cards/{card_id}
   • URL parameters: card_id – the unique card number.
   • Returns: JSON containing card attributes such as id, giftCardNo, original balance, current balance, fixed amount flag, redeem allowed flag, location code, status and expiry date【589796654157184†screenshot】.
2. Sell (create) a new card – Issue a new gift card via the API.
   • Endpoint: POST /api/giftcards/v1/cards/{card_id}
   • URL parameters: card_id – the desired card number.
   • Request body (JSON):
     • amount (decimal) – card amount with two decimal places.
     • transactionNo (string, max 8 characters) – transaction identifier.
     • locationCode (string) – unique location identifier (must exist in the system).
   • Returns: gift card data including the newly created card number and status【589796654157184†screenshot】.
   • Example body: {"amount": 57.23, "transactionNo": "00000045", "locationCode": "SHOP1"}【589796654157184†screenshot】.
3. Use a card for payment – Deduct value from a card when paying for goods.
   • Endpoint: POST /api/giftcards/v1/transactions/{consumer_key}/cards/{card_id}
   • URL parameters:
     • consumer_key – your unique consumer key (provided by Resico).
     • card_id – the gift card number.
   • Request body (JSON):
     • amount (decimal) – amount to draw from the card, two digits after the separator【499153476404150†screenshot】.
   • Returns: updated card data with new balance.
4. Reserve a card – Temporarily hold funds on a card prior to finalising a transaction.
   • Endpoint: POST /api/giftcards/v1/reserve/{card_id}
   • URL parameters: card_id – card number.
   • Request body (JSON): {"locationCode": "SHOP1"} – identifies the location where the reservation is made【653107097416600†screenshot】.
   • Returns: updated card data showing reserved balance.
5. Cancel card reservation – Release a held reservation without deducting funds.
   • Endpoint: GET /api/giftcards/v1/cancelreserve/{card_id}
   • URL parameters: card_id – card number【473768911778245†screenshot】.
   • Returns: gift card data.

Required fields

• Authorization header – every request must include Authorization: Bearer <token>【877301654772412†screenshot】.
• Content‑Type – set to application/json for all POST requests【877301654772412†screenshot】.
• Card ID – required on all endpoints to identify the card.
• Consumer key – required when using a card for payment.
• Request body parameters – as specified above (e.g., amount, transactionNo, locationCode).

Validation rules

• Bearer token validity – expired or invalid tokens will result in 401 Unauthorized.
• Card ID format – must match the gift card number length; non‑existing cards return 404 Not Found.
• Amount fields must be positive decimals with two digits after the separator.
• Location codes must exist in the system, otherwise an error is returned.
• TransactionNo length is limited to 8 characters【589796654157184†screenshot】.

Exceptions

• Attempting to sell a card that already exists will return a conflict error.
• Using or reserving a card that has insufficient balance returns an error response.
• Calling reserve or cancel reservation on a card that does not support reservations (e.g., dynamic cards) may return an unsupported operation error.

Common errors

• 401 Unauthorized – missing or invalid authorization header.
• 404 Not Found – card ID does not exist.
• 422 Unprocessable Entity – validation errors in the request body, such as invalid amount or unknown location code.
• 409 Conflict – attempting to create a card that already exists.

Troubleshooting

• Check that the bearer token is active and has not expired. Tokens must be refreshed periodically.
• Use the Get card info endpoint to verify the card’s status before performing other actions.
• If you receive validation errors, compare your request payload with the examples provided above and ensure all required fields are present.
• Enable request logging in your integration to capture the full request and response for debugging purposes.