Sign in

v2

latestOpenAPI 3.1.02026-08-01244220427.0 KB
Gift Cards

Customercheckgiftcardbalance

Customer Balance Check (Cross-Program)

Allows customers to check the balance of any gift card without needing to know the programId. Searches across all programs by card number and security code.

This endpoint is designed for customer-facing applications where the customer may have cards from multiple merchants/programs.

Security:

  • Rate limited: 5 requests per minute per IP
  • Pattern detection for enumeration attacks
  • Card lockout after multiple failed attempts
  • Constant-time security code comparison

Request Body:

  • cardNumber: The full 16-digit card number
  • securityCode: The 6-digit security code

Returns:

  • Card balance, status, expiration, and activity status

Status Codes:

  • 200: Balance retrieved successfully
  • 404: Card not found or invalid security code
  • 429: Rate limited or card locked
post/v2/giftcards/customer/balance-check

Query parameters

programIdstring
Example:5eb7cf5a86d9755df3a6c593
cardIdstring
Example:5eb7cf5a86d9755df3a6c593

Headers

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

Request body

cardNumberstring required
securityCodestring required
captchaTokenstring nullable

Response

Successful Response

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

Gift card status enumeration.

expiresAtstring date-time required
isActiveboolean required

Example response

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