Skip to content
HPay Developers
Français
Merchant API reference

Cards

Verify a card

POSThttps://api.hpay.cash/checkCard/

Token: action check-card, valid for 5 min

Approved payment terminals only

This endpoint receives the customer's card and PIN. It is reserved for physical payment terminals approved by HPay, where customers type their own PIN. For a website or app, use the payment gateway: you never handle the PIN.

Checks that a card is usable (number, PIN, optional expiry date), without debiting or storing anything. Never returns the balance, full number or customer contact details. It is not a payment authorisation.

Parameters (JSON)

api_keyrequiredstring Your API key.
api_public_keyrequiredstring Your public key.
tokenrequiredstring Token from /token/ with the stated action.
moderequiredstring test or live, matching your keys.
actionrequiredstring check-card
hpay_cardrequiredstring HPay card number (16 digits, starts with 57).
hpay_card_pinrequiredstring PIN entered by the customer on the terminal. Never store it.
expiry_datemay be emptystring Optional: MM/YYYY, MM/YY, YYYY-MM, YYYY-MM-DD or DD/MM/YYYY. Only month and year are compared.

Keep fingerprint to recognise the same card later without storing its number, and check_id for support. On error 2110, HPay never says whether the number, PIN or date is wrong; attempts_left gives the remaining tries.

curl -X POST https://api.hpay.cash/checkCard/ \
  -H "Content-Type: application/json" \
  -d '{
  "api_key": "YOUR_API_KEY",
  "api_public_key": "YOUR_PUBLIC_KEY",
  "token": "FRESH_TOKEN",
  "mode": "live",
  "action": "check-card",
  "hpay_card": "5700 1234 5678 3456",
  "hpay_card_pin": "••••",
  "expiry_date": "10/2027"
}'
Response
{
  "success": true,
  "message": "Card verified",
  "error_code": 0,
  "check_id": "CHK-00001234",
  "transaction_mode": "live",
  "card": {
    "status": "active",
    "masked_number": "5700 **** **** 3456",
    "holder": "Camille D.",
    "expires_at": "2027-10-05",
    "currency": "HTG",
    "fingerprint": "fp_9c1e4a7b2d0f83a6c5e1b904"
  }
}

Errors specific to this endpoint

error_codeHTTPCause
2100403IP address not allowed for this key.
2101400The number is not 16 digits.
2102400The number does not start with 57.
2103400The PIN is not 4 or 5 digits.
2104400Invalid date format.
2110200Incorrect card details.
2111429Card blocked after too many attempts (retry_after in seconds).
2112429Too many requests or failures from your key.
2120200Card suspended.
2121200Card not activated yet.
2122200Card expired.
2123200Customer account not validated, suspended or closed.
2150503Service temporarily unavailable.

Next : Transfers →