v2

latestOpenAPI 3.1.02026-08-01244220427.0 KB

Gift Cards

Redeemgiftcard

Redeem a specified amount from an active, non-expired gift card and record a REDEMPTION transaction.

Performs an atomic balance deduction (prevents double-spend and race conditions), updates the card status to DEPLETED when balance reaches zero, and inserts a GiftCardTransaction recording the redemption.

Returns: RedeemResponse: Contains transactionId, giftCardId, amountRedeemed, remainingBalance, success, and message.

Idempotency Scope: Keys are scoped to programId + redeem + cardId. The same key may be reused for different cards or different gift card actions.

post/v2/giftcards/programs/{programId}/cards/{cardId}/redeem

Path parameters

programIdstring required

Example:5eb7cf5a86d9755df3a6c593

cardIdstring required

Example:5eb7cf5a86d9755df3a6c593

Headers

idempotency-keystring nullable

X-Eposn-Customer-Tokenstring nullable

X-Eposn-Merchant-Tokenstring nullable

Request body

posTransactionIdstring nullable

cashierIdstring nullable

terminalIdstring nullable

descriptionstring nullable

Response

Successful Response

transactionIdstring required

giftCardIdstring required

amountRedeemedstring required

remainingBalancestring required

successboolean required

messagestring required

Example response

{
  "transactionId": "5eb7cf5a86d9755df3a6c593",
  "giftCardId": "5eb7cf5a86d9755df3a6c593"
}