---
title: "Customercheckgiftcardbalance"
method: POST
path: "/v2/giftcards/customer/balance-check"
tags: ["Gift Cards"]
---

# Customercheckgiftcardbalance

`POST /v2/giftcards/customer/balance-check`

### 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

## Query parameters

- `programId` string
- `cardId` string

## Headers

- `X-Eposn-Customer-Token` string, nullable
- `X-Eposn-Merchant-Token` string, nullable

## Request body

- BalanceCheckRequest
  - `cardNumber` string, required
  - `securityCode` string, required
  - `captchaToken` string, nullable

## Response `200`

Successful Response

- BalanceCheckResponse
  - `id` string, required
  - `programId` string, required
  - `cardNumber` string, required
  - `lastFourDigits` string, required
  - `balance` string, required
  - `status` 'pending' | 'active' | 'suspended' | 'expired' | 'voided' | 'depleted', required — Gift card status enumeration.
  - `expiresAt` string, date-time, required
  - `isActive` boolean, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/loyalty/apis/loyaltydog.md) · [All operations](https://skmtc.net/loyalty/apis/loyaltydog/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/loyalty/loyaltydog/versions/42b7b22af2b6/schema)