Issuer response codes

Issuer Response Codes (F39)

The ISO 8583 Field 39 (F39) response code is the authoritative indicator of why a card transaction was approved or declined. This code comes directly from the card issuer and provides the most accurate reason for transaction outcomes, without intermediary error mapping that might obscure the actual reason.

‍

Finding the Response Code

The issuer response code is located in the transaction_data.attempts[].extra.response_code field of the purchase response.

‍

Example Response

JSON

{
  "client": {
    "email": "sarah.johnson@example.com",
    "phone": "+27821234567",
    "full_name": "Sarah Johnson"
  },
  "purchase": {
    "currency": "ZAR",
    "products": [
      {
        "name": "Monthly Subscription",
        "price": 29900,
        "quantity": "1.0000"
      }
    ],
    "total": 29900
  },
  "transaction_data": {
    "payment_method": "",
    "flow": "server_to_server",
    "extra": {
      "card_type": "debit",
      "card_brand": "visa",
      "card_issuer": "first national bank",
      "card_issuer_country": "ZA"
    },
    "attempts": [
      {
        "type": "execute",
        "successful": false,
        "payment_method": "visa",
        "flow": "server_to_server",
        "extra": {
          "RRN": "502847291038",
          "card_type": "debit",
          "card_brand": "visa",
          "descriptor": "ACME Corp",
          "masked_pan": "411111******1111",
          "card_issuer": "first national bank",
          "expiry_year": 27,
          "expiry_month": 9,
          "card_category": "PERSONAL",
          "response_code": "51",
          "cardholder_name": "SARAH JOHNSON",
          "commerce_indicator": "internet",
          "card_issuer_country": "ZA",
          "network_transaction_id": "0115XYZABC123"
        },
        "country": "ZA",
        "client_ip": "192.168.1.100",
        "processing_time": 1768397734,
        "processing_status": "{\"class\":\"external\",\"code\":\"INSUFFICIENT_FUND\",\"message\":\"Decline - Insufficient funds in the account.\"}",
        "error": {
          "code": "insufficient_funds",
          "message": "Insufficient funds"
        }
      }
    ]
  },
  "status": "error",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

‍

Key Fields

Field Path	Description
`transaction_data.attempts[].extra.response_code`	The F39 issuer response code
`transaction_data.attempts[].extra.masked_pan`	Masked card number
`transaction_data.attempts[].extra.card_issuer`	Issuing bank name
`transaction_data.attempts[].processing_status`	Detailed processing status with mapped error
`transaction_data.attempts[].error`	Simplified error object

‍

Soft Decline Codes

Soft declines are temporary failures that may succeed if retried.

‍

Response Code	Definition
`01`	Invalid Card length
`01`	VSDC STIP Default Response Code
`01`	CVV2 STIP Default Response Code
`04`	CVV2 STIP Default Response Code
`05`	Missing Expiration Date
`05`	VSDC STIP Default Response Code
`05`	Decline Key Entered transactions in STIP
`05`	RTD Decline in STIP
`05`	Decline in STIP transactions acquired in a Risky Country
`05`	Issuer Default STIP Response Code (Transaction Type and/or MCG)
`05`	OCT Rules Engine Decline
`05`	CAM not performed due to missing data
`05`	CAM not eligible for CHIP txn
`05`	AA score greater than AA STIP
`05`	TTL expired, auth/fin txns only
`10`	Partial Approval
`14`	No Issuer for Account Number
`21`	PCAS Reversal cannot find Original Activity
`54`	Invalid PAN length
`54`	Expired Card
`54`	VSDC STIP Default Response Code
`55`	VSDC STIP Default Response Code
`55`	International transaction — PIN Not Present
`55`	Domestic PIN Not Present
`57`	Invalid Check Digit
`57`	International ATM transaction not permitted for this Service Code
`57`	Account Range Blocked
`61`	Activity Amount Limit Exceeded
`62`	Restricted Country
`65`	Activity Count Limit Exceeded
`75`	VSDC STIP Default Response Code
`82`	Incorrect CVV
`86`	PIN Present but Not Verified
`91`	STIP default response code from Country-to-Country Exclusion Table
`91`	Decline Generic EMV transactions in STIP
`91`	Decline in STIP Non-domestic Key Entered transactions
`91`	Decline in STIP Card Not Present transactions
`91`	Decline in STIP PIN-present transactions
`91`	Decline in STIP PIN-not-present transactions
`91`	Decline in STIP transactions above USD 100,000
`91`	Decline in International transactions
`N7`	CVV2 STIP Default Response Code
`R0`	Decline in STIP — Stop Payment Order
`R1`	Decline in STIP — Revocation Of One Authorization Order
`R3`	Decline in STIP — Revocation Of All Authorization Order

‍

Hard Decline Codes

Hard declines are permanent failures that will not succeed on retry. These require customer intervention.

‍

Response Code	Definition
`00`	Processed in STIP / Generic Send to STIP with no Error
`01`	CVV Default Response Code — Refer to Issuer
`02`	Refer to Issuer — Special Condition
`04`	CVV Default Response Code — Pick Up Card
`05`	CVV Default Response Code — Decline
`05`	CAVV validation failed
`05`	WLM Scoring Request Decline
`05`	Targeted Acceptance Decline
`05`	CAVCS transaction decline
`05`	CAM failed (CAM — All respond)
`05`	MIT Timeline failure
`12`	Invalid transaction
`12`	Bill Payment not supported for this country, MCC, or Network
`12`	Token auth/prov environ mismatch
`13`	Currency Conversion overflow / amount invalid
`14`	Invalid PAN length
`14`	Invalid Check Digit
`15`	No Issuer for Account Number
`19`	Merchant fraud risk assessment
`21`	Delayed Settlement
`51`	Insufficient Funds
`54`	Expired Card
`55`	Incorrect PIN
`55`	PIN Missing
`57`	Invalid Service Code
`57`	Transaction Type and/or MCG blocked for issuer
`57`	Issuer Blocked
`57`	Acquirer Blocked
`57`	Sanction Bin Blocking - decline
`58`	Transaction not allowed in acquirer terminal
`59`	RTD Decline
`61`	Money Transfer Amount Limit exceeded
`62`	Restricted Country for card usage
`62`	MIT Timeline failure
`64`	Transaction does not fulfill AML requirement
`65`	Money Transfer Amount Limit exceeded
`75`	"PIN Incorrect" activity threshold exceeded
`76`	Unsolicited Reversal
`81`	PIN decryption error
`82`	Incorrect CVV or iCVV
`83`	Unable to verify PIN
`85`	Account Verification — No Reason to Decline
`86`	Could not Verify PIN
`91`	Destination unavailable
`93`	Transaction could not be completed — Violation Of Law
`94`	Duplicate transmission
`96`	I/O Error retrieving CDB record
`N5`	Not eligible for resubmission
`N7`	CVV2 Failed
`N8`	Transaction amount in Completion exceeds that in Pre-Auth
`R0`	Stop Payment Order
`R1`	Revocation of Authorization Order
`R3`	Revocation of all Auth Order

‍

Common Response Codes Quick Reference

Code	Category	Meaning	Recommended Action
`00`	Approved	Transaction approved	None required
`01`	Soft	Refer to issuer	Retry or contact issuer
`05`	Hard	Do not honor	Use different card
`12`	Hard	Invalid transaction	Check transaction data
`14`	Hard	Invalid card number	Verify card details
`51`	Hard	Insufficient funds	Customer to add funds or use different card
`54`	Hard	Expired card	Use valid card
`55`	Hard	Incorrect PIN	Re-enter PIN
`57`	Hard	Transaction not permitted	Use different card/method
`61`	Soft	Exceeds withdrawal limit	Retry with lower amount or later
`65`	Soft	Activity limit exceeded	Retry later
`91`	Soft	Issuer unavailable	Retry later

‍

Retry Logic Recommendations

Soft Declines

Wait and retry: Allow 15-30 minutes before retrying
Maximum attempts: Limit to 3 retry attempts per 24-hour period
Exponential backoff: Increase wait time between retries

‍

Hard Declines

Do not retry automatically: These require customer action
Notify customer: Provide clear instructions on next steps
Request alternative payment: Prompt for a different payment method

‍

Special Cases

Code	Handling
`51` (Insufficient Funds)	Allow customer-initiated retry after they've added funds
`54` (Expired Card)	Request updated card details
`91` (Issuer Unavailable)	Implement automatic retry with exponential backoff
`65` (Activity Limit)	Wait until the next calendar day to retry

‍

Integration Notes

Always log the F39 code: Store the response_code for all transactions for debugging and analytics
Don't rely solely on mapped errors: The processing_status and error fields contain mapped values that may lose specificity
Build response code handling: Implement specific handling based on F39 codes rather than generic error categories
Monitor trends: Track response code frequency to identify issues with specific card types or issuers

Table of contents

Issuer response codes