v2

latestOpenAPI 3.1.02026-08-01244220427.0 KB

Gift Cards

Consolidategiftcards

Consolidates multiple ACTIVE gift cards from the same program and customer into a single new active card with the combined balance.

Performs validation (2–10 unique cards, all ACTIVE, positive balances, same customer, total ≤ $10,000), acquires per-card locks to prevent concurrent modifications, creates a new card with a cryptographically generated number and security code, voids source cards (setting their balances to zero), and records consolidation transactions inside an atomic database transaction.

Returns: ConsolidateResponse: Details of the consolidation including newCard (the created gift card), voidedCards (IDs of source cards), totalConsolidatedAmount, consolidationTransactions (transaction IDs), and an informational message.

Idempotency Scope: Keys are scoped to programId + consolidate + sorted source card ids. Reusing the same key for a different source-card set is treated as a fresh operation.

post/v2/giftcards/programs/{programId}/consolidate

Path parameters

programIdstring required

Example:5eb7cf5a86d9755df3a6c593

Query parameters

cardIdstring

Example:5eb7cf5a86d9755df3a6c593

Headers

idempotency-keystring nullable

X-Eposn-Customer-Tokenstring nullable

X-Eposn-Merchant-Tokenstring nullable

Request body

cardNumbersstring[] required

customerEmailstring email nullable

customerNamestring nullable

senderNamestring nullable

merchantIdstring required

referenceIdstring nullable

descriptionstring nullable

isPhysicalboolean

designTemplatestring nullable

customMessagestring nullable

Example request

{
  "merchantId": "5eb7cf5a86d9755df3a6c593"
}

Response

Successful Response

successboolean required

messagestring required

voidedCardsstring[] required

totalConsolidatedAmountstring required

consolidationTransactionsstring[] required

referenceIdstring nullable required

Example response

{
  "newCard": {
    "id": "5eb7cf5a86d9755df3a6c593",
    "customerId": "5eb7cf5a86d9755df3a6c593",
    "merchantId": "5eb7cf5a86d9755df3a6c593",
    "programId": "5eb7cf5a86d9755df3a6c593"
  }
}