{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["tabs","tab"]},"type":"markdown"},"seo":{"title":"Reefpay Docs","description":"Reefpay is the groundbreaking payment gateway that lets you integrate with the future of payments.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"tutorial-processor-specific-errors","__idx":0},"children":["Tutorial: Processor-specific errors"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-processor-errors-reach-you","__idx":1},"children":["How processor errors reach you"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When Paradise Gateway forwards a transaction to a processor, the processor may return its own error or decline code. The API normalizes these into a consistent response, but the raw processor details are available in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processor_response"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"https://files.modern-mermaid.live/images/1776277618995-mermaid-diagram-1776277619066.png","alt":"image"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"response-layers","__idx":2},"children":["Response layers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every transaction response contains two layers of information:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"Layer"},"children":["Layer"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"Fields"},"children":["Fields"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"Purpose"},"children":["Purpose"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Gateway"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_status"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_code"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_message"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Normalized result you should use for business logic"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Processor"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processor_response"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Raw response from TSYS or Vericheck — useful for debugging"]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC\",\n  \"response_status\": \"declined\",\n  \"response_code\": \"05\",\n  \"response_message\": \"Transaction declined by the issuer.\",\n  \"processor_response\": {\n    \"processor_code\": \"051\",\n    \"processor_message\": \"INSUFFICIENT FUNDS\",\n    \"auth_response_code\": \"51\"\n  },\n  \"correlation_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"tsys-error-codes-card-transactions","__idx":3},"children":["TSYS error codes (card transactions)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Common TSYS auth response codes and what to do:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"Action"},"children":["Action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["00"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Approved"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Success — fulfill the order"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["01"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Refer to issuer"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Do not retry — the cardholder should call their bank"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["02"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Refer to issuer (special)"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Do not retry — possible fraud alert"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["05"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Do not honor"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Do not retry — ask for a different card"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["12"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Invalid transaction"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Check your request — wrong transaction type?"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["13"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Invalid amount"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Verify the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," field"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["14"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Invalid card number"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Card number failed validation at the processor"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["41"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Lost card — pick up"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Do not retry — possible fraud"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["43"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Stolen card — pick up"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Do not retry — possible fraud"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["51"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Insufficient funds"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Ask the customer for a different card"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["54"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Expired card"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Ask for an updated card"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["61"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Exceeds withdrawal limit"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Ask for a different card or smaller amount"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["65"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Activity limit exceeded"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Retry later or ask for a different card"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["91"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Issuer unavailable"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Retry with exponential backoff"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"vericheck-error-codes-ach-transactions","__idx":4},"children":["Vericheck error codes (ACH transactions)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["ACH errors are typically ACH return codes from the receiving bank:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"Action"},"children":["Action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["R01"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Insufficient funds"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Wait and retry, or contact customer"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["R02"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Account closed"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Request new bank details; delete the token"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["R03"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["No account / unable to locate"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Request corrected account number"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["R04"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Invalid account number"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Validate and re-enter"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["R08"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Payment stopped"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Contact customer to resolve"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["R10"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Customer advises not authorized"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Do not retry — investigate"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["R29"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Corporate not authorized"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Do not retry — contact the business"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/tutorials/payment-cookbook/auth-returns"},"children":["ACH returns"]}," for the full return handling guide."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"mapping-processor-errors-to-actions","__idx":5},"children":["Mapping processor errors to actions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Build a mapping function to translate processor codes into your application's actions."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"PROCESSOR_ACTION_MAP = {\n    \"00\": \"success\",\n    \"01\": \"refer_to_issuer\",\n    \"05\": \"decline_no_retry\",\n    \"12\": \"invalid_request\",\n    \"14\": \"invalid_card\",\n    \"51\": \"insufficient_funds\",\n    \"54\": \"expired_card\",\n    \"91\": \"retry\",\n}\n\nNO_RETRY_ACTIONS = {\"decline_no_retry\", \"refer_to_issuer\", \"invalid_card\", \"expired_card\"}\nRETRY_ACTIONS = {\"retry\"}\n\ndef classify_processor_error(processor_response: dict) -> dict:\n    code = processor_response.get(\"auth_response_code\", \"\")\n    action = PROCESSOR_ACTION_MAP.get(code, \"unknown\")\n\n    return {\n        \"action\": action,\n        \"retryable\": action in RETRY_ACTIONS,\n        \"user_message\": get_user_message(action),\n        \"processor_code\": code,\n        \"processor_message\": processor_response.get(\"processor_message\", \"\"),\n    }\n\ndef get_user_message(action: str) -> str:\n    messages = {\n        \"success\": \"Payment successful.\",\n        \"decline_no_retry\": \"Your card was declined. Please try a different payment method.\",\n        \"refer_to_issuer\": \"Please contact your bank for assistance.\",\n        \"insufficient_funds\": \"Insufficient funds. Please try a different card.\",\n        \"expired_card\": \"Your card has expired. Please use a different card.\",\n        \"invalid_card\": \"Invalid card number. Please check and re-enter.\",\n        \"invalid_request\": \"There was an issue with the payment. Please try again.\",\n        \"retry\": \"Temporary issue. Please try again in a moment.\",\n    }\n    return messages.get(action, \"Payment could not be processed. Please try again.\")\n","lang":"python"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"JavaScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const PROCESSOR_ACTION_MAP = {\n  \"00\": \"success\",\n  \"01\": \"refer_to_issuer\",\n  \"05\": \"decline_no_retry\",\n  \"12\": \"invalid_request\",\n  \"14\": \"invalid_card\",\n  \"51\": \"insufficient_funds\",\n  \"54\": \"expired_card\",\n  \"91\": \"retry\",\n};\n\nconst USER_MESSAGES = {\n  success: \"Payment successful.\",\n  decline_no_retry: \"Your card was declined. Please try a different payment method.\",\n  refer_to_issuer: \"Please contact your bank for assistance.\",\n  insufficient_funds: \"Insufficient funds. Please try a different card.\",\n  expired_card: \"Your card has expired. Please use a different card.\",\n  invalid_card: \"Invalid card number. Please check and re-enter.\",\n  invalid_request: \"There was an issue with the payment. Please try again.\",\n  retry: \"Temporary issue. Please try again in a moment.\",\n};\n\nfunction classifyProcessorError(processorResponse) {\n  const code = processorResponse?.auth_response_code || \"\";\n  const action = PROCESSOR_ACTION_MAP[code] || \"unknown\";\n  return {\n    action,\n    retryable: action === \"retry\",\n    userMessage: USER_MESSAGES[action] || \"Payment could not be processed.\",\n    processorCode: code,\n    processorMessage: processorResponse?.processor_message || \"\",\n  };\n}\n","lang":"javascript"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":6},"children":["Best practices"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_status"]}," for flow control"]}," — base your approve/decline/retry logic on the normalized gateway fields, not raw processor codes."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processor_response"]}," for diagnostics"]}," — log it for debugging, but don't expose it to customers."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Keep your mapping table current"]}," — as you encounter new processor codes in production, add them to your map."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Alert on unknown codes"]}," — if ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["classify_processor_error"]}," returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unknown"]},", log an alert so you can investigate."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":7},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/tutorials/error-handling/log-monitor-api-errors"},"children":["Log and monitor API errors"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/tutorials/error-handling/retry-with-exponential-backoff"},"children":["Retry with exponential backoff"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/tutorials/payment-cookbook/handle-declined-transactions"},"children":["Handle declined transactions"]}]}]}]},"headings":[{"value":"Tutorial: Processor-specific errors","id":"tutorial-processor-specific-errors","depth":1},{"value":"How processor errors reach you","id":"how-processor-errors-reach-you","depth":2},{"value":"Response layers","id":"response-layers","depth":2},{"value":"TSYS error codes (card transactions)","id":"tsys-error-codes-card-transactions","depth":2},{"value":"Vericheck error codes (ACH transactions)","id":"vericheck-error-codes-ach-transactions","depth":2},{"value":"Mapping processor errors to actions","id":"mapping-processor-errors-to-actions","depth":2},{"value":"Best practices","id":"best-practices","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Tutorial: Processor-specific errors","shortTitle":"Processor errors","intro":"Learn how to interpret and handle errors that originate from the underlying processors (TSYS for cards, Vericheck for ACH) and map them to actionable outcomes.","type":"tutorial","seo":{"title":""}},"lastModified":"2026-06-05T02:46:44.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/tutorials/error-handling/processor-specific-errors","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}