{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Card Declines"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"card-declines","__idx":0},"children":["Card Declines"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Beta"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Card Declines API is in Beta. Additive changes are normal, and breaking changes"," ","may be made with notice while the resource incorporates customer feedback. See"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/v1/versioning"},"children":["Versioning and compatibility"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/v1/transactions"},"children":["Transactions API"]}," tells you a card payment failed. This resource tells you why, in words you can hand to whoever is asking."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /api/v1/transactions/{transaction_id}/declined-authorizations\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every declined attempt on a card transaction comes back with the reasons it was declined, a plain-language ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["explanation"]},", and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recommended_actions"]}," a person can take. The wording matches what the card decline email tells the cardholder, so the API and the email give the same answer."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"when-a-transaction-has-declines","__idx":1},"children":["When a transaction has declines"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Card transactions can carry a declined attempt and still be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["settled"]},". A merchant that raises an authorization mid-stay - a hotel, a car rental, a fuel pump - sends an incremental authorization, and that increment can be declined after the first one succeeded. So the resource gates on transaction type, not on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]},", and you should not assume ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status: failed"]}," is the only place declines live."]},{"$$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":"Situation"},"children":["Situation"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Response"},"children":["Response"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A card transaction with declined attempts"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," with one entry per attempt, oldest first"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A card transaction where nothing was declined"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["declined_authorizations: []"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A transaction that is not a card transaction"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," - wires, ACH, and checks cannot carry card declines"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No transaction with that id in your business"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cards data could not be read"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["503"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction_id"]}," is the same identifier ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v1/transactions"]}," returns, and this sub-resource lives on the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v1"]}," surface as its parent transaction."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-an-attempt-carries","__idx":2},"children":["What an attempt carries"]},{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What it tells you"},"children":["What it tells you"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The amount of this authorization attempt, in minor units. This is the attempt's own amount, not the transaction's net amount - an incremental authorization is worth less than the transaction it belongs to."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reasons"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Why the attempt was declined. Never empty. More than one reason can apply to a single attempt: a card can hit its own limit and a blocked merchant category in the same authorization."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each reason carries three things:"]},{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What it tells you"},"children":["What it tells you"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A stable identifier such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["card_locked"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["card_limit_reached"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["explanation"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One or two sentences a person can read, matching what the decline email tells the cardholder. Constant per ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]},", and carries no transaction data."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recommended_actions"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["What to do next, in the order to try it. Empty when there is no customer-side remedy - a cash withdrawal is declined because no Rho card supports one, and there is nothing to change."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-workflows","__idx":3},"children":["Common workflows"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"answering-why-did-this-decline","__idx":4},"children":["Answering \"why did this decline\""]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl \"https://rhoapi.rho.co/api/v1/transactions/{transaction_id}/declined-authorizations\" \\\n  -H \"Authorization: Bearer $RHO_API_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"declined_authorizations\": [\n    {\n      \"amount\": { \"amount\": 10000, \"currency\": \"USD\" },\n      \"reasons\": [\n        {\n          \"code\": \"card_locked\",\n          \"explanation\": \"Your card was declined because it's locked.\",\n          \"recommended_actions\": [\n            {\n              \"code\": \"unlock_card\",\n              \"description\": \"Unlock your card to continue using it. You can do it on the card's detail page in your Rho dashboard or mobile app.\"\n            }\n          ]\n        }\n      ]\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"showing-declines-alongside-a-transaction-list","__idx":5},"children":["Showing declines alongside a transaction list"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There is no batch path. List transactions, keep the card ones you care about, and call this resource per transaction. That is one extra call each, which is fine for a support lookup on a handful of transactions and worth telling us about if you are doing it across a whole page."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"scopes","__idx":6},"children":["Scopes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactions:read"]},". This is a sub-resource of a transaction the token can already read, so it needs no second grant."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"reference","__idx":7},"children":["Reference"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Full endpoint catalogue - paths, parameters, response shapes, and the complete code lists - lives in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api/v1/openapi/transactions"},"children":["API Reference"]},"."]}]},"headings":[{"value":"Card Declines","id":"card-declines","depth":1},{"value":"When a transaction has declines","id":"when-a-transaction-has-declines","depth":2},{"value":"What an attempt carries","id":"what-an-attempt-carries","depth":2},{"value":"Common workflows","id":"common-workflows","depth":2},{"value":"Answering \"why did this decline\"","id":"answering-why-did-this-decline","depth":3},{"value":"Showing declines alongside a transaction list","id":"showing-declines-alongside-a-transaction-list","depth":3},{"value":"Scopes","id":"scopes","depth":2},{"value":"Reference","id":"reference","depth":2}],"frontmatter":{"seo":{"title":"Card Declines"}},"lastModified":"2026-10-23T10:00:23.881Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/v1/card-declines","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}