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

‍

Soft Decline Codes

Soft declines are temporary failures that may succeed if retried.

‍

‍

Hard Decline Codes

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

‍

‍

Common Response Codes Quick Reference

‍

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

‍

Integration Notes

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