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"
}'{
"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_code | HTTP | Cause |
|---|---|---|
2100 | 403 | IP address not allowed for this key. |
2101 | 400 | The number is not 16 digits. |
2102 | 400 | The number does not start with 57. |
2103 | 400 | The PIN is not 4 or 5 digits. |
2104 | 400 | Invalid date format. |
2110 | 200 | Incorrect card details. |
2111 | 429 | Card blocked after too many attempts (retry_after in seconds). |
2112 | 429 | Too many requests or failures from your key. |
2120 | 200 | Card suspended. |
2121 | 200 | Card not activated yet. |
2122 | 200 | Card expired. |
2123 | 200 | Customer account not validated, suspended or closed. |
2150 | 503 | Service temporarily unavailable. |