Sign in

v2

latestOpenAPI 3.1.02026-08-01244220427.0 KB
Gift Cards

Transfergiftcardbalance

Transfer Balance Between Gift Cards

Moves a specified amount from a source gift card to a destination gift card within the same program. The source card's security code is required to authorise the transfer.

Both cards must be active and belong to the same program. A TRANSFER_OUT transaction is recorded on the source card and a TRANSFER_IN transaction on the destination card.

Business Rules:

  • Source and destination cards must be different
  • Both cards must have status active
  • Source card balance must be >= transfer amount
  • Destination card balance after transfer must not exceed £10,000.00
  • Source card security code must match (constant-time comparison)
  • Transfer depletes source card if resulting balance reaches zero

Status Codes:

  • 200: Transfer completed successfully
  • 400: Invalid amount, insufficient balance, or cards not eligible
  • 401: Incorrect security code
  • 404: Source or destination card not found
  • 409: Card currently locked by another operation

Idempotency Scope:

  • Idempotency keys are scoped to programId + transfer + sourceCardId + destinationCardId
  • The same key may be reused for different source/destination pairs or other gift card actions
post/v2/giftcards/programs/{programId}/cards/{cardId}/transfer

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

securityCodestring required
destinationCardNumberstring required
descriptionstring nullable
referenceIdstring nullable

Response

Successful Response

successboolean required
messagestring required
transferIdstring required
amountTransferredstring required

Example response

{
  "sourceCard": {
    "id": "5eb7cf5a86d9755df3a6c593"
  },
  "destinationCard": {
    "id": "5eb7cf5a86d9755df3a6c593"
  }
}