{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/payments-odl/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Failure conversion","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com/products/custody","lang":"en-US","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":"failure-conversion","__idx":0},"children":["Failure conversion"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Occasionally, RippleNet payments fail, for example due to an exchange outage. When this happens, RippleNet Server marks the payment as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]}," and your funds may not reach the destination currency."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["RippleNet's failure conversion ensures that the funds from failed payments are made available in a fiat currency quickly. Depending on your ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#use-cases"},"children":["use case"]},", failure conversion identifies the fund's location on the liquidity path and continues a failed payment's process until it either arrives in the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/system-components/failure-conversion-and-ssa/sender-segregated-account"},"children":["Sender Segregated Account"]}," or until you manually recapture the funds from the failed payment. "]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note:"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The process for manually recapturing funds depends on the exchange you're using.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Contact your RippleNet liaison for more information."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Failure conversion ensures that during liquidation, your payment's value is converted to fiat currency and that any ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/glossary#slippage"},"children":["slippage"]}," is accounted for."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"use-cases","__idx":1},"children":["Use cases"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We recommend that you use the following combination of On-Demand Liquidity (ODL) features, depending on your use case:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two wallets and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["two exchanges"]}," - The wallet at the source exchange is used for the XRP withdrawal and the wallet at the destination exchange for the XRP deposit and subsequently the liquidation trade.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}]},{"$$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":""},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/glossary#wallet-send"},"children":["Wallet Send"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/glossary#wallet-receive"},"children":["Wallet Receive"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/system-components/liquidation/smart-liquidation"},"children":["SLS"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/system-components/failure-conversion-and-ssa/failure-conversion"},"children":["Failure conversion"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/system-components/failure-conversion-and-ssa/sender-segregated-account"},"children":["SSA"]}]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/introduction/use-cases#individual-payments"},"children":["Individual payments"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["yes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/introduction/use-cases#bulk-funding"},"children":["Bulk funding"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["no"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/introduction/use-cases#internal-treasury"},"children":["Internal treasury"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["no"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["no"]}]}]}]}]}]}]}]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two wallets and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["one exchange"]}," - One wallet at the destination exchange is used for the XRP withdrawal and the other wallet at the destination exchange for the XRP deposit and subsequently the liquidation trade.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}]},{"$$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":""},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/glossary#wallet-send"},"children":["Wallet Send"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/glossary#wallet-receive"},"children":["Wallet Receive"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/system-components/liquidation/smart-liquidation"},"children":["SLS"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/system-components/failure-conversion-and-ssa/failure-conversion"},"children":["Failure conversion"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/system-components/failure-conversion-and-ssa/sender-segregated-account"},"children":["SSA"]}]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/introduction/use-cases#individual-payments"},"children":["Individual payments"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["yes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/introduction/use-cases#bulk-funding"},"children":["Bulk funding"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["no"]}]}]}]}]}]}]}]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["One wallet and one exchange - The wallet at the destination exchange is used for the liquidation trade.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}]},{"$$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":""},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/glossary#wallet-send"},"children":["Wallet Send"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/glossary#wallet-receive"},"children":["Wallet Receive"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/system-components/liquidation/smart-liquidation"},"children":["SLS"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/system-components/failure-conversion-and-ssa/failure-conversion"},"children":["Failure conversion"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/system-components/failure-conversion-and-ssa/sender-segregated-account"},"children":["SSA"]}]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/introduction/use-cases#internal-treasury"},"children":["Internal treasury"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["no"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["no"]}]}]}]}]}]}]}]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information about your failure conversion use case, contact your RippleNet liaison."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":2},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you want to use failure conversion with the Sender Segregated Account, consider the following:"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note:"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By default, failure conversion is disabled (set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},") in ODL-RippleNet."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"check-failure-conversion-status","__idx":3},"children":["Check failure conversion status"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When your payment's status is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]}," with a sub-state of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUSH_FORWARD"]},", it indicates that the failure conversion process has started."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n   \"json\": { },\n   \"created_at\": \"2022-12-13T18:37:11.138Z\",\n   \"subState\": \"PUSH_FORWARD\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Failure conversion behaves differently depending on where in the payment process the failure occurs."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If the failure occurs after XRP withdrawal and before deposit confirmation at the receiving exchange, failure conversion will retry the payment once per 30 minutes for up to 12 hours."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If the failure occurs during the destination liquidation at the receiving exchange, failure conversion will retry the payment once per hour for up to 24 hours."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note:"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Original payments that are subject to failure conversion continue to be marked as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]}," even after failure conversion is successful."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To check a payment's failure conversion status:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To retrieve your payment, use the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-odl/api-docs/ripplenet/reference/openapi/non-orchestration-payments/getpayments"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Get payments"]}]}," operation with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"status\": \"FAILED\""]}," and with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"with_labels\" = \"PUSH_FORWARD,SSA_FUNDING_COMPLETED\""]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the response, check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content.push_forward_execution_result"]}," array of objects.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," You should see values like in this example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"\"push_forward_execution_results\": [\n    {\n    \"execution_result_id\": \"cc004b30-2e4e-4ede-9ef2-8f6c9dddcd17\",\n    \"execution_timestamp\": \"2022-12-13T18:36:05.363Z\",\n    \"execution_result_type\": \"CRYPTO_TRANSFER\",\n    \"execution_result_order\": \"3\",\n    \"sender_address\": \"sender_address@example\",\n    \"receiver_address\": \"receiver_address@example\",\n    \"sending_amount\": \"77.045351000\",\n    \"receiving_amount\": \"77.045351000\",\n    \"sending_fee\": \"0.000000000\",\n    \"receiving_fee\": \"0.000000000\",\n    \"sending_currency_code\": null,\n    \"receiving_currency_code\": null,\n    \"fx_rate\": null,\n    \"transfer_currency_code\": \"XRP\",\n    \"intermediary_delta\": null,\n    \"incentive_type\": null,\n    \"incentive_value\": null,\n    \"transaction_hash\": null,\n    \"venue_id\": \"0f397fd5-825c-40c6-b4f1-2595c8e7521f\",\n    \"fiat_adjusted_value\": null,\n    \"odl_payment_id\": \"726970706C6578766961-01670956230-489-001-244E41524B968BB8C9A0534175A87163A30EEB95CC91B752B4582801E61F1499\"\n    }\n]\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note:"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content.execution_results"]}," array of objects doesn't get populated for failed payments, only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["push_forward_execution_results"]},"."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content.user_info.settlement_declined"]}," array of objects. ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subState"]}," field should show ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUSH_FORWARD"]}," and there should be an object with fields pertaining to the SSA transfer, like in this example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"\"settlement_declined\": [\n  . . .\n  {\n    \"json\": { },\n    \"created_at\": \"2022-12-13T18:37:11.138Z\",\n    \"subState\": \"PUSH_FORWARD\"\n  },\n  {\n    \"json\": {\n        \"ssa_remote_transfer_id\": \"2558c823-6737-4955-9ad9-aeec4f94c2f4\",\n        \"transfer_amount\": \"1669.50\",\n        \"transfer_currency\": \"PHP\",\n        \"funding_account\": \"funding_account@example\",\n        \"ssa_account\": \"ssa_account@example\",\n        \"transfer_state\": \"EXECUTED\"\n    },\n    \"created_at\": \"2022-12-13T18:41:14.599Z\",\n    \"subState\": \"SSA_FUNDING_COMPLETED\"\n  },\n  . . .\n]\n","lang":"json"},"children":[]}]}]}]},"headings":[{"value":"Failure conversion","id":"failure-conversion","depth":1},{"value":"Use cases","id":"use-cases","depth":2},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Check failure conversion status","id":"check-failure-conversion-status","depth":2}],"frontmatter":{"seo":{"title":"Failure conversion"}},"lastModified":"2025-10-03T17:57:05.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/payments-odl/api-docs/ripplenet/system-components/failure-conversion-and-ssa/failure-conversion","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}