Declines and Retries

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

CategoryRetryMeaningAction
Soft declineYes, with increasing intervalsA temporary failure — insufficient funds, a processing timeout, or the issuer briefly unavailableSchedule reattempts with increasing gaps, within scheme limits
Step-upNoThe issuer requires your customer to authenticateDo not retry without your customer. Send a payment link so they can authorise the payment
Hard declineNeverA permanent failure — lost or stolen card, closed account, expired card, or recurring charges blockedDelete 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 limits

Card 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.

CodeMessageCauseCategoryAction
00Successful approval/completionThe charge was approvedSuccessFulfil the order and send your customer an itemised receipt
14Invalid card number / Account Not FoundThe card number or account does not existHard declineDelete the token and ask your customer to update their payment method
54Expired cardThe card has expiredHard declineStop charging and ask your customer for their renewed card details
41 / 43Lost / Stolen card (Pick up)The card has been reported lost or stolenHard declineDelete the token immediately and flag the account in your risk monitoring
57Transaction not permitted to issuerYour customer or the issuer has blocked recurring charges on this cardHard declineAsk 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"
© Network International LLC. All Rights Reserved.