Sign in

v2

latestOpenAPI 3.1.02026-08-01244220427.0 KB
Gift Cards

Transfergiftcardownership

Transfer Gift Card Ownership

Updates the cardholder details (name, email, optional customer ID) on an active gift card. Intended for merchant use when a card is gifted or resold to a new owner.

An OWNERSHIP_TRANSFER transaction is recorded for audit trail purposes.

Business Rules:

  • Card must be active
  • New owner email must be a valid email address (validated by Pydantic EmailStr)
  • Name is sanitized to remove HTML/script content

Status Codes:

  • 200: Ownership transferred successfully
  • 400: Card is not active
  • 404: Card not found
  • 401: Unauthorized
post/v2/giftcards/programs/{programId}/cards/{cardId}/transfer-ownership

Path parameters

programIdstring required
Example:5eb7cf5a86d9755df3a6c593
cardIdstring required
Example:5eb7cf5a86d9755df3a6c593

Headers

X-Eposn-Customer-Tokenstring nullable
X-Eposn-Merchant-Tokenstring nullable

Request body

newOwnerNamestring required
newOwnerEmailstring email required
newCustomerIdstring
referenceIdstring nullable

Example request

{
  "newCustomerId": "5eb7cf5a86d9755df3a6c593"
}

Response

Successful Response

idstring required
cardNumberstring required
balancestring required
initialValuestring required
status'pending' | 'active' | 'suspended' | 'expired' | 'voided' | 'depleted' required

Gift card status enumeration.

createdAtstring date-time required
updatedAtstring date-time nullable required
activatedAtstring date-time nullable required
expiresAtstring date-time required
suspendedReasonstring nullable required
suspendedUntilstring date-time nullable required
suspendedAtstring date-time nullable required
customerIdstring required
customerEmailstring nullable required
customerPhonestring nullable required
customerNamestring nullable required
senderNamestring nullable
merchantIdstring required
merchantNamestring nullable
isPhysicalboolean required
designTemplatestring nullable required
customMessagestring nullable required
lastFourDigitsstring required
programIdstring required
deliverAtstring date-time nullable
deliveredboolean

Example response

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