Response & Decline Codes

Reference for the codes the Tonder API returns: HTTP codes, card decline codes, and withdrawal status codes.

HTTP codes

Success

Code	Status	Description
200	OK	The request was successful. Typical for `GET` requests.
201	Created	The resource was created successfully. Typical for `POST` requests.
202	Accepted	The request was accepted but isn't yet complete (e.g. a payment requiring 3DS).
204	No Content	The request was successful but there's no content to return (e.g. a `DELETE`).

Client errors

Code	Status	Description	Action
400	Bad Request	Malformed request or missing required parameters.	Check the body and parameters.
401	Unauthorized	Authentication failed: invalid or missing API key.	Check your key and that it carries the `Token` prefix (with a space).
402	Payment Required	The processor or issuing bank declined the payment.	Advise the user to try another method.
404	Not Found	The requested resource doesn't exist.	Check the transaction ID or URL.
422	Unprocessable Entity	Well-formed request with semantic errors (e.g. invalid email, amount out of range).	Fix the indicated fields.
429	Too Many Requests	You exceeded the rate limit.	Retry after a delay (exponential backoff).

Server errors

Code	Status	Description	Action
500	Internal Server Error	An unexpected error on Tonder's servers.	Retry after a short delay.
502	Bad Gateway	A dependent service is temporarily down.	Retry after a short delay.
503	Service Unavailable	The API is temporarily unavailable (e.g. maintenance).	Retry later. Check the status page.

Error format

{
  "error": {
    "code": "validation_error",
    "message": "Amount must be greater than 0",
    "type": "request_error",
    "details": { "field": "amount", "received_value": -10.00 }
  },
  "request_id": "req_abc123"
}

The error object contains code (machine-readable), message (human-readable), type (category), details (additional context). The request_id identifies the request — include it when contacting support.

Card decline codes

A standardized internal decline-code system to unify error handling across providers. Format: [Category][Type][Sequence] — category (letter A-Z), type H (hard decline, permanent) or S (soft decline, retry allowed), sequence (two digits).

The detailed catalog of the raw processor codes (numeric, alphanumeric, and K codes) is in Decline codes.

A — Authentication & Security

Code	Type	Description
AH01	Hard	Invalid card number
AH02	Hard	Invalid CVV/CVC
AH03	Hard	Invalid expiry date
AH04	Hard	3D Secure authentication failed
AH05	Hard	Fraudulent transaction detected
AH06	Hard	Card reported lost
AH07	Hard	Card reported stolen
AH08	Hard	Suspicious behavior detected
AS01	Soft	3D Secure authentication required
AS02	Soft	Strong customer authentication (SCA) required

B — Bank/Issuer

Code	Type	Description
BH01	Hard	Card declined by bank
BH02	Hard	Card expired
BH03	Hard	Card canceled/disabled
BH04	Hard	Card restricted
BH05	Hard	Bank authorization required
BH06	Hard	Card blacklisted
BH07	Hard	Invalid account
BH08	Hard	Bank requested card retention
BS01	Soft	Bank temporarily unavailable
BS02	Soft	Issuer system maintenance

C — Credit/Funds

Code	Type	Description
CH01	Hard	Insufficient funds
CH02	Hard	Credit limit exceeded
CH03	Hard	Over limit
CH04	Hard	Withdrawal limit exceeded
CH05	Hard	Transaction limit exceeded
CS01	Soft	Temporary credit hold

D — Data/Configuration

Code	Type	Description
DH01	Hard	Invalid merchant configuration
DH02	Hard	Currency not supported
DH03	Hard	Card type not supported
DH04	Hard	Invalid amount
DH05	Hard	Transaction type not permitted
DH06	Hard	Invalid transaction data
DS01	Soft	Validation error — retry allowed
DS02	Soft	Configuration temporarily unavailable

E — External/Network

Code	Type	Description
ES01	Soft	Network timeout
ES02	Soft	Communication error
ES03	Soft	Processor unavailable
ES04	Soft	Gateway timeout
ES05	Soft	External service error

F — Fraud Prevention

Code	Type	Description
FH01	Hard	High risk transaction blocked
FH02	Hard	Velocity rules violated
FH03	Hard	Geographic restrictions
FH04	Hard	Merchant blacklist match
FH05	Hard	Card blocked for fraud
FS01	Soft	Transaction under fraud review

G — General/System

Code	Type	Description
GS01	Soft	General system error
GS02	Soft	Processing error — retry allowed
GS03	Soft	Duplicate transaction
GS04	Soft	Transaction expired
GS05	Soft	Service temporarily unavailable

U — User/Customer

Code	Type	Description
UH01	Hard	Transaction canceled by customer
UH02	Hard	Customer authentication failed
UH03	Hard	Customer verification failed
US01	Soft	Customer action required
US02	Soft	Session timeout

The decline code arrives in the webhook in the decline_code and decline_reason fields:

{
  "status": "Declined",
  "decline_code": "BH01",
  "decline_reason": "Card declined by bank",
  "event_type": "payment_Declined"
}