---
title: "Checkgiftcardbalance"
method: POST
path: "/v2/giftcards/programs/{programId}/balance-check"
tags: ["Gift Cards"]
---

# Checkgiftcardbalance

`POST /v2/giftcards/programs/{programId}/balance-check`

Authenticate the provided card number and security code, and return the card's balance and usability information.

Performs a constant-time security-code comparison and abuse/lockout checks before returning card details.

Returns:
    BalanceCheckResponse: Contains `cardNumber`, `lastFourDigits`, `balance`, `status`, `expiresAt`, and `isActive`.
    On authentication failure or lockout the endpoint responds with an HTTP error (e.g., 404 for not found/invalid code, 429 for rate limiting or card lockout).

## Path parameters

- `programId` string, required

## Query parameters

- `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)