Sign in

v2

latestOpenAPI 3.1.02026-08-01244220427.0 KB
Gift Cards

Creategiftcard

Create a new gift card in pending status with a generated card number and security code.

Validates and sets the expiration (defaults to 1 year, must not exceed 5 years), sanitizes the provided custom message to prevent XSS, generates a unique 16-digit card number and a 6-digit security code, persists the card with a zero balance and the requested initialValue, and returns the persisted card representation.

Parameters: data (CreateGiftCardRequest): Request payload containing initialValue, merchantId, optional customer fields, expiration, isPhysical, designTemplate, and customMessage.

Returns: GiftCardResponse: The newly created gift card data (status will be "pending"); the security code is stored but not returned.

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

Path parameters

programIdstring required
Example:5eb7cf5a86d9755df3a6c593

Query parameters

cardIdstring
Example:5eb7cf5a86d9755df3a6c593

Headers

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

Request body

customerEmailstring email nullable
customerPhonestring phone nullable
customerNamestring nullable
senderNamestring nullable
merchantIdstring required
expiresAtstring date-time nullable
isPhysicalboolean
designTemplatestring nullable
customMessagestring nullable
deliverAtstring date-time nullable

Example request

{
  "merchantId": "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"
}