{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Reefpay Docs","description":"Reefpay is the groundbreaking payment gateway that lets you integrate with the future of payments."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"handle-declines","__idx":0},"children":["Handle declines"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A declined payment returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]},". The request was well formed, it reached the"," ","issuer, and the issuer said no. Nothing is wrong with your integration."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["That is the distinction your code has to make:"]},{"$$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":{"data-label":""},"children":[]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"HTTP status"},"children":["HTTP status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What it means"},"children":["What it means"]},{"$$mdtype":"Tag","name":"th","attributes":{"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":{},"children":["Approved"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["APPROVED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The issuer approved it"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fulfill"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Declined"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The issuer refused it"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ask for another payment method"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The transaction could not be attempted"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Investigate; do not retry blindly"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Failed request"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["4xx"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5xx"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The request never became a transaction"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/get-started/errors"},"children":["Errors and retries"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Branch on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]},", not on the status code."]}," Treating any ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," as success is"," ","the most common defect in a first integration, and it ships goods for payments"," ","that never happened."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-a-decline-looks-like","__idx":1},"children":["What a decline looks like"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"TRANSACTION-01KEW36C9TQ5N1P7YRFGZ0BVW4\",\n  \"type\": \"SALE\",\n  \"result\": \"DECLINED\",\n  \"response_code\": \"51\",\n  \"response_description\": \"Insufficient funds\",\n  \"batch_id\": null,\n  \"amount\": 10000\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_code"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_description"]}," come from the processor. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["batch_id"]}," is"," ","null, because a declined transaction never joins a batch."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The transaction still exists and still has an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},". A decline is recorded, not"," ","discarded, so you can read it back later from"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/after-the-payment/find-and-report-on-transactions"},"children":["the reporting endpoints"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"retry-or-do-not","__idx":2},"children":["Retry, or do not"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The useful split is between declines that might succeed later and declines that"," ","never will."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Do not retry the same card immediately."]}," Card networks penalize repeated"," ","attempts on a refused card, and issuers may treat a burst as suspicious."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["A soft decline"]}," — insufficient funds, a velocity limit — may succeed on a"," ","different day. For a recurring charge, retry on a schedule measured in days,"," ","not seconds."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["A hard decline"]}," — closed account, stolen card, invalid number — will not"," ","succeed. Ask for a different payment method."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Never retry with a slightly different amount"]}," to get around a decline. It"," ","looks like probing, and it is."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The gateway does not classify a decline as soft or hard for you. The processor's"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_code"]}," carries that meaning, and the mapping is processor-specific."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-to-tell-the-customer","__idx":3},"children":["What to tell the customer"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not show ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_code"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_description"]},", or anything under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source"]},"."," ","\"Do not honor\" and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["51"]}," mean nothing to a cardholder, and some of them imply"," ","things about their account that you should not be relaying on the issuer's"," ","behalf."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Say what they can do instead:"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["That card was declined. Try another card, or contact your bank."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep the codes in your logs, where they are worth having. Log the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-request-id"]}," ","header with them — it is what support needs to trace one specific attempt."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"ach-is-different","__idx":4},"children":["ACH is different"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An ACH debit can be approved and then ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["returned days later"]},". There is no"," ","decline at the moment of payment to catch."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Watch ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_returned"]}," on the transaction rather than waiting for a decline that"," ","will not come. ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/payments/accept-an-ach-payment"},"children":["Accept an ACH payment"]}," covers the"," ","return fields and the trap that ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["return_code"]}," is omitted rather than null."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"testing-a-decline","__idx":5},"children":["Testing a decline"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No card number triggers a decline against the real gateway. To exercise this path"," ","in the API reference, send the header ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-redocly-response-body-example: saleDeclined"]}," ","and the mock returns a declined body. See"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/get-started/environments"},"children":["Environments and test data"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":6},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/get-started/errors"},"children":["Errors and retries"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/payments/recurring-payments"},"children":["Recurring payments"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/avs-and-cvv"},"children":["AVS and CVV"]}]}]}]},"headings":[{"value":"Handle declines","id":"handle-declines","depth":1},{"value":"What a decline looks like","id":"what-a-decline-looks-like","depth":2},{"value":"Retry, or do not","id":"retry-or-do-not","depth":2},{"value":"What to tell the customer","id":"what-to-tell-the-customer","depth":2},{"value":"ACH is different","id":"ach-is-different","depth":2},{"value":"Testing a decline","id":"testing-a-decline","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Handle declines","shortTitle":"Handle declines","intro":"A decline is a successful request with an unwelcome answer. Telling it apart from a failure decides whether you retry, ask for another card, or stop.","type":"how-to","seo":{"title":""}},"lastModified":"2026-09-17T08:54:39.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/payments/handle-declines","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}