{"templateId":"markdown","sharedDataIds":{},"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":"recipe-ach-returns","__idx":0},"children":["Recipe: ACH returns"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-is-an-ach-return","__idx":1},"children":["What is an ACH return?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An ACH return occurs when the receiving bank rejects or reverses an ACH transaction. Unlike card chargebacks, ACH returns follow NACHA rules and have specific return reason codes."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-return-codes","__idx":2},"children":["Common return codes"]},{"$$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":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Name"},"children":["Name"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Timing"},"children":["Timing"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["R01"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Insufficient funds"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Not enough money in the account"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["2 business days"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["R02"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Account closed"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The account has been closed"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["2 business days"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["R03"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["No account / unable to locate"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Account number is invalid"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["2 business days"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["R04"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Invalid account number"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Account number structure is wrong"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["2 business days"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["R08"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Payment stopped"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Customer requested a stop payment"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["2 business days"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["R10"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Customer advises not authorized"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Customer claims they did not authorize the debit"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["60 calendar days"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["R29"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Corporate customer advises not authorized"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Corporate account disputes authorization"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["2 business days"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"return-timeline","__idx":3},"children":["Return timeline"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"---\nconfig:\n theme: 'neutral'\n---\ngantt\n title ACH return windows\n dateFormat YYYY-MM-DD\n axisFormat %a\n\n section Debit (payment)\n Transaction submitted :a1, 2026-03-25, 1d\n Standard return window :a2, after a1, 2d\n Unauthorized return (R10) :a3, 2026-03-25, 60d\n\n section Credit (payout)\n Transaction submitted :b1, 2026-03-25, 1d\n Standard return window :b2, after b1, 2d\n","diagramHtml":" Sun Sun Sun Sun Sun Sun Sun Sun SunTransaction submitted Unauthorized return (R10) Transaction submitted Standard return window Standard return window Debit (payment)Credit (payout)ACH return windows","diagramHtmlDark":" Sun Sun Sun Sun Sun Sun Sun Sun SunTransaction submitted Unauthorized return (R10) Transaction submitted Standard return window Standard return window Debit (payment)Credit (payout)ACH return windows"},"children":["---\nconfig:\n theme: 'neutral'\n---\ngantt\n title ACH return windows\n dateFormat YYYY-MM-DD\n axisFormat %a\n\n section Debit (payment)\n Transaction submitted :a1, 2026-03-25, 1d\n Standard return window :a2, after a1, 2d\n Unauthorized return (R10) :a3, 2026-03-25, 60d\n\n section Credit (payout)\n Transaction submitted :b1, 2026-03-25, 1d\n Standard return window :b2, after b1, 2d\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"detecting-returns","__idx":4},"children":["Detecting returns"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When an ACH transaction is returned, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction_state"]}," changes to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]},". Check the transaction periodically or use batch status polling."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"poll-the-transaction","__idx":5},"children":["Poll the transaction"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl https://api.dev.paradisegateway.net/v1/transactions/TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC \\\n -H \"APIKEY: YOUR-API-KEY\"\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A returned transaction looks like:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"id\": \"TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC\",\n \"type\": \"sale\",\n \"amount\": 250000,\n \"transaction_state\": \"failed\",\n \"response_status\": \"declined\",\n \"response_message\": \"ACH return: R01 - Insufficient funds\",\n \"correlation_id\": \"e5f6a7b8-c9d0-1234-ef01-23456789abcd\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handling-returns-in-your-application","__idx":6},"children":["Handling returns in your application"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"---\nconfig:\n theme: 'neutral'\n---\nflowchart TD\n A[ACH transaction submitted] --> B[Poll transaction state]\n B --> C{transaction_state?}\n C -->|completed / settled| D[Payment successful]\n C -->|failed| E{Return code?}\n E -->|R01 Insufficient funds| F[Retry in a few days or contact customer]\n E -->|R02/R03/R04 Bad account| G[Request updated bank details]\n E -->|R08 Stop payment| H[Contact customer]\n E -->|R10 Unauthorized| I[Do not retry — investigate]\n","diagramHtml":"

completed / settled

failed

R01 Insufficient funds

R02/R03/R04 Bad account

R08 Stop payment

R10 Unauthorized

ACH transaction submitted

Poll transaction state

transaction_state?

Payment successful

Return code?

Retry in a few days or contact customer

Request updated bank details

Contact customer

Do not retry — investigate

","diagramHtmlDark":"

completed / settled

failed

R01 Insufficient funds

R02/R03/R04 Bad account

R08 Stop payment

R10 Unauthorized

ACH transaction submitted

Poll transaction state

transaction_state?

Payment successful

Return code?

Retry in a few days or contact customer

Request updated bank details

Contact customer

Do not retry — investigate

"},"children":["---\nconfig:\n theme: 'neutral'\n---\nflowchart TD\n A[ACH transaction submitted] --> B[Poll transaction state]\n B --> C{transaction_state?}\n C -->|completed / settled| D[Payment successful]\n C -->|failed| E{Return code?}\n E -->|R01 Insufficient funds| F[Retry in a few days or contact customer]\n E -->|R02/R03/R04 Bad account| G[Request updated bank details]\n E -->|R08 Stop payment| H[Contact customer]\n E -->|R10 Unauthorized| I[Do not retry — investigate]\n"]},{"$$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 monitor_ach_transaction(txn_id, max_checks=10, interval=3600):\n \"\"\"Poll an ACH transaction until it settles or fails.\"\"\"\n for _ in range(max_checks):\n resp = requests.get(\n f\"{BASE}/v1/transactions/{txn_id}\",\n headers={\"APIKEY\": API_KEY},\n )\n txn = resp.json()\n state = txn[\"transaction_state\"]\n\n if state in (\"completed\", \"settled\"):\n return {\"status\": \"success\", \"transaction\": txn}\n\n if state == \"failed\":\n return {\n \"status\": \"returned\",\n \"message\": txn.get(\"response_message\", \"ACH return\"),\n \"transaction\": txn,\n }\n\n time.sleep(interval)\n\n return {\"status\": \"timeout\", \"message\": \"Transaction still pending\"}\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 monitorAchTransaction(txnId, maxChecks = 10, intervalMs = 3600000) {\n for (let i = 0; i < maxChecks; i++) {\n const resp = await fetch(`${BASE}/v1/transactions/${txnId}`, {\n headers: { \"APIKEY\": API_KEY },\n });\n const txn = await resp.json();\n\n if ([\"completed\", \"settled\"].includes(txn.transaction_state)) {\n return { status: \"success\", transaction: txn };\n }\n if (txn.transaction_state === \"failed\") {\n return {\n status: \"returned\",\n message: txn.response_message || \"ACH return\",\n transaction: txn,\n };\n }\n await new Promise((r) => setTimeout(r, intervalMs));\n }\n return { status: \"timeout\", message: \"Transaction still pending\" };\n}\n","lang":"javascript"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-to-do-after-a-return","__idx":7},"children":["What to do after a return"]},{"$$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":"Return code"},"children":["Return code"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Action"},"children":["Action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["R01 (Insufficient funds)"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Wait a few days and retry, or contact the customer for an alternative payment method"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["R02/R03/R04 (Bad account)"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Request updated bank details; delete the invalid token"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["R08 (Stop payment)"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Contact the customer to resolve the dispute"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["R10 (Unauthorized)"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Do not retry — investigate the authorization. This may indicate fraud"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"preventing-returns","__idx":8},"children":["Preventing returns"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verify bank accounts"]}," — use micro-deposit verification before processing large debits"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Get authorization"]}," — for WEB entries, ensure you have the customer's online consent"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Validate routing numbers"]}," — check the routing number format before tokenizing"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Communicate clearly"]}," — tell customers when debits will occur and for how much"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":9},"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/ach-for-invoices"},"children":["ACH for invoices"]}," — collect payments via ACH"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/tutorials/payment-cookbook/ach-payouts"},"children":["ACH payouts"]}," — send funds to vendors"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/tutorials/payment-cookbook/handle-payment-failures"},"children":["Handle payment failures"]}," — broader failure patterns"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/transactions/ach-accounts"},"children":["About ACH payments"]}]}]}]},"headings":[{"value":"Recipe: ACH returns","id":"recipe-ach-returns","depth":1},{"value":"What is an ACH return?","id":"what-is-an-ach-return","depth":2},{"value":"Common return codes","id":"common-return-codes","depth":2},{"value":"Return timeline","id":"return-timeline","depth":2},{"value":"Detecting returns","id":"detecting-returns","depth":2},{"value":"Poll the transaction","id":"poll-the-transaction","depth":3},{"value":"Handling returns in your application","id":"handling-returns-in-your-application","depth":2},{"value":"What to do after a return","id":"what-to-do-after-a-return","depth":2},{"value":"Preventing returns","id":"preventing-returns","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Recipe: ACH returns","shortTitle":"ACH returns","intro":"Understand why ACH transactions get returned, how to detect returns, and what to do when a debit or credit is sent back by the receiving bank.","type":"tutorial","seo":{"title":""}},"lastModified":"2026-06-05T02:46:44.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/tutorials/payment-cookbook/auth-returns","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}