Sign in

v2

latestOpenAPI 3.1.02026-08-01244220427.0 KB
Gift Cards

Reloadgiftcardbynumber

Reload Gift Card by Card Number

Allows topping up a gift card using the card number instead of the card ID. This is useful for POS/cashier scenarios where the cashier types or scans a card number rather than looking up the internal ID.

Business Rules:

  • Same rules as the standard reload endpoint
  • Only ACTIVE cards can be reloaded
  • Card must not be expired
  • Reload amount: $0.01 - $5,000 per transaction
  • Maximum card balance: $10,000

Request Body:

  • cardNumber: The full card number (up to 20 chars)
  • amount: Amount to add ($0.01 - $5,000)
  • referenceId: External reference ID for tracking (optional)
  • description: Transaction description (optional, defaults to "Gift card reload")

Status Codes:

  • 200: Gift card reloaded successfully
  • 400: Cannot reload (inactive, expired, or would exceed max balance)
  • 404: Gift card not found
post/v2/giftcards/programs/{programId}/cards/reload-by-number

Path parameters

programIdstring required
Example:5eb7cf5a86d9755df3a6c593

Query parameters

cardIdstring
Example:5eb7cf5a86d9755df3a6c593

Headers

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

Request body

cardNumberstring required
referenceIdstring nullable
descriptionstring nullable

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"
}