{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["tabs","tab","admonition"]},"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":"recipe-handle-declined-transactions","__idx":0},"children":["Recipe: Handle declined transactions"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"why-transactions-are-declined","__idx":1},"children":["Why transactions are declined"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A decline means the card issuer or processor refused the transaction. Common reasons:"]},{"$$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":"left","data-label":"Reason"},"children":["Reason"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"What happened"},"children":["What happened"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"What to do"},"children":["What to do"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Insufficient funds"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Customer's balance is too low"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Ask the customer to use a different card"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Invalid card number"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["PAN failed Luhn check or is not recognized"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Prompt the customer to re-enter card details"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Expired card"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The card's expiry date has passed"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Ask for an updated card"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["CVV mismatch"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["CVV does not match the issuer's records"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Ask the customer to re-enter CVV"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["AVS mismatch"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Billing address does not match"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Ask the customer to verify their billing address"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Fraud suspect"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Issuer flagged the transaction"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Do not retry — contact the customer"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Processor error"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Temporary issue at the processor"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Retry after a delay"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"recognizing-a-decline","__idx":2},"children":["Recognizing a decline"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_status"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_code"]}," on every transaction response."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"TRANSACTION-02LGEHRR1BZSPA6WRY1T3H4CD\",\n  \"type\": \"sale\",\n  \"amount\": 5000,\n  \"transaction_state\": \"failed\",\n  \"response_status\": \"declined\",\n  \"response_code\": \"05\",\n  \"response_message\": \"Transaction declined by the issuer.\",\n  \"avs_result_code\": \"n\",\n  \"cvv_result\": \"N\",\n  \"correlation_id\": \"c3d4e5f6-a7b8-9012-cdef-123456789abc\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"decision-flowchart","__idx":3},"children":["Decision flowchart"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"https://files.modern-mermaid.live/images/1776277281111-mermaid-diagram-1776277281047.png","alt":"image"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"code-example-decline-handling","__idx":4},"children":["Code example: Decline handling"]},{"$$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":"import time, requests, os\n\nAPI_KEY = os.environ[\"PARADISE_API_KEY\"]\nBASE = \"https://api.dev.paradisegateway.net\"\n\ndef process_with_retry(payload, max_retries=3):\n    for attempt in range(max_retries):\n        resp = requests.post(\n            f\"{BASE}/v1/transactions\",\n            headers={\"Content-Type\": \"application/json\", \"APIKEY\": API_KEY},\n            json=payload,\n        )\n        result = resp.json()\n\n        if result[\"response_status\"] == \"approved\":\n            return {\"success\": True, \"transaction\": result}\n\n        if result[\"response_status\"] == \"declined\":\n            return {\n                \"success\": False,\n                \"reason\": \"declined\",\n                \"message\": result.get(\"response_message\", \"Transaction declined\"),\n                \"avs\": result.get(\"avs_result_code\"),\n                \"cvv\": result.get(\"cvv_result\"),\n            }\n\n        # error — retry with backoff\n        wait = 2 ** attempt\n        print(f\"Error on attempt {attempt + 1}, retrying in {wait}s...\")\n        time.sleep(wait)\n\n    return {\"success\": False, \"reason\": \"error\", \"message\": \"Max retries exceeded\"}\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 API_KEY = process.env.PARADISE_API_KEY;\nconst BASE = \"https://api.dev.paradisegateway.net\";\n\nasync function processWithRetry(payload, maxRetries = 3) {\n  for (let attempt = 0; attempt < maxRetries; attempt++) {\n    const resp = await fetch(`${BASE}/v1/transactions`, {\n      method: \"POST\",\n      headers: { \"Content-Type\": \"application/json\", \"APIKEY\": API_KEY },\n      body: JSON.stringify(payload),\n    });\n    const result = await resp.json();\n\n    if (result.response_status === \"approved\") {\n      return { success: true, transaction: result };\n    }\n\n    if (result.response_status === \"declined\") {\n      return {\n        success: false,\n        reason: \"declined\",\n        message: result.response_message || \"Transaction declined\",\n        avs: result.avs_result_code,\n        cvv: result.cvv_result,\n      };\n    }\n\n    // error — retry with backoff\n    const wait = 2 ** attempt * 1000;\n    console.log(`Error on attempt ${attempt + 1}, retrying in ${wait}ms...`);\n    await new Promise((r) => setTimeout(r, wait));\n  }\n  return { success: false, reason: \"error\", message: \"Max retries exceeded\" };\n}\n","lang":"javascript"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-to-show-the-customer","__idx":5},"children":["What to show the customer"]},{"$$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":"left","data-label":"Scenario"},"children":["Scenario"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"User-facing message"},"children":["User-facing message"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Declined — insufficient funds"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["\"Your card was declined. Please try a different payment method.\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Declined — invalid card"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["\"We couldn't process your card. Please check the number and try again.\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Declined — AVS mismatch"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["\"Your billing address doesn't match. Please verify and retry.\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Error — temporary"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["\"Something went wrong. Please try again in a moment.\""]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Never expose raw error details"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not show ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_code"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_message"]},", or processor details to the customer. Use friendly messages and log the details server-side."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"testing-declines-in-sandbox","__idx":6},"children":["Testing declines in sandbox"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use these test card numbers to simulate specific scenarios:"]},{"$$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":"left","data-label":"Card number"},"children":["Card number"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Expected result"},"children":["Expected result"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["4000000000000002"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Declined"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5200000000000007"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Declined"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["4111111111111111"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Approved"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/reference/quick-reference#test-card-numbers"},"children":["Quick reference — test cards"]}," for the full list."]},{"$$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/payment-cookbook/handle-payment-failures"},"children":["Handle payment failures"]}," — broader error handling patterns"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/api-fundamentals/error-handling"},"children":["Error handling concepts"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/security-compliance/fraud-protection"},"children":["Fraud prevention"]}]}]}]},"headings":[{"value":"Recipe: Handle declined transactions","id":"recipe-handle-declined-transactions","depth":1},{"value":"Why transactions are declined","id":"why-transactions-are-declined","depth":2},{"value":"Recognizing a decline","id":"recognizing-a-decline","depth":2},{"value":"Decision flowchart","id":"decision-flowchart","depth":2},{"value":"Code example: Decline handling","id":"code-example-decline-handling","depth":2},{"value":"What to show the customer","id":"what-to-show-the-customer","depth":2},{"value":"Testing declines in sandbox","id":"testing-declines-in-sandbox","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Recipe: Handle declined transactions","shortTitle":"Handle declines","intro":"Learn why transactions get declined, how to interpret decline responses, and what to do next — retry, ask for a different card, or escalate.","type":"tutorial","seo":{"title":""}},"lastModified":"2026-06-05T02:46:44.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/tutorials/payment-cookbook/handle-declined-transactions","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}