Declines and Retries
When a charge you initiate is declined, your system decides whether it may try again. Card schemes monitor retry behaviour, so route on the category of the response code first and the individual code second.
Decline categories
| Category | Retry | Meaning | Action |
|---|---|---|---|
| Soft decline | Yes, with increasing intervals | A temporary failure — insufficient funds, a processing timeout, or the issuer briefly unavailable | Schedule reattempts with increasing gaps, within scheme limits |
| Step-up | No | The issuer requires your customer to authenticate | Do not retry without your customer. Send a payment link so they can authorise the payment |
| Hard decline | Never | A permanent failure — lost or stolen card, closed account, expired card, or recurring charges blocked | Delete the stored token and ask your customer for a new payment method |
Ask your account manager which response codes count as soft declines and step-ups, how long to wait between attempts, and how many attempts the card schemes allow.
Scheme retry limitsCard schemes monitor retry patterns. Retrying a hard decline, or retrying too often, can lead to scheme non-compliance fines and lower approval rates.
Response codes
This table lists approval and the codes you must never retry. The Message column shows the scheme response description. For every code across N-Genius Online, see Error Codes — Details & Description.
| Code | Message | Cause | Category | Action |
|---|---|---|---|---|
00 | Successful approval/completion | The charge was approved | Success | Fulfil the order and send your customer an itemised receipt |
14 | Invalid card number / Account Not Found | The card number or account does not exist | Hard decline | Delete the token and ask your customer to update their payment method |
54 | Expired card | The card has expired | Hard decline | Stop charging and ask your customer for their renewed card details |
41 / 43 | Lost / Stolen card (Pick up) | The card has been reported lost or stolen | Hard decline | Delete the token immediately and flag the account in your risk monitoring |
57 | Transaction not permitted to issuer | Your customer or the issuer has blocked recurring charges on this card | Hard decline | Ask your customer for a different card |
Example response
Hard decline — lost card (41)
{
"_id": "urn:payment:d1234567-89ab-cdef-0123-456789abcdef",
"reference": "d1234567-89ab-cdef-0123-456789abcdef",
"state": "FAILED",
"authResponse": {
"success": false,
"resultCode": "41",
"resultMessage": "Lost card - Pick up",
"recommendation": "DO_NOT_RETRY_CARD_REVOKED"
},
"errors": [
{
"code": "CARD_REVOKED",
"message": "Card has been reported lost/stolen. Do not initiate further retries on this token."
}
]
}Handling a response
Route on the category, not on individual codes scattered through your logic. The helper functions are yours to implement, including load_retry_rules(), which returns the soft-decline and step-up codes and the retry limits your account manager confirms.
# Hard declines follow the response code table on this page. Never retry them.
HARD_DECLINE = {"14", "41", "43", "54", "57"}
# Soft-decline and step-up codes, and the retry limits, come from your account manager.
RULES = load_retry_rules()
SOFT_DECLINE = RULES["soft_decline_codes"]
STEP_UP = RULES["step_up_codes"]
MAX_ATTEMPTS = RULES["max_attempts"]
RETRY_WINDOW_DAYS = RULES["retry_window_days"]
def handle_mit_response(payment, attempt_count, days_since_first_attempt):
auth = payment.get("authResponse", {})
code = auth.get("resultCode")
if code == "00":
mark_order_as_paid(payment["reference"])
send_receipt(payment)
return "PAID"
if code in HARD_DECLINE:
# Hard-decline responses may not include savedCard,
# so revoke the token you stored against this customer.
revoke_stored_token(payment["reference"])
request_new_payment_method(payment["reference"])
return "CARD_REVOKED"
if code in SOFT_DECLINE:
if attempt_count < MAX_ATTEMPTS and days_since_first_attempt <= RETRY_WINDOW_DAYS:
schedule_retry(payment["reference"], backoff_hours(attempt_count))
return "RETRY_SCHEDULED"
request_new_payment_method(payment["reference"])
return "RETRIES_EXHAUSTED"
if code in STEP_UP:
link = payment.get("_links", {}).get("customerCheckout", {}).get("href")
send_payment_link(link)
return "CUSTOMER_ACTION_REQUIRED"
log_unhandled_code(code, auth)
return "UNHANDLED"
