Failure conversion

Occasionally, RippleNet payments fail, for example due to an exchange outage. When this happens, RippleNet Server marks the payment as FAILED and your funds may not reach the destination currency.

RippleNet's failure conversion ensures that the funds from failed payments are made available in a fiat currency quickly. Depending on your 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 Sender Segregated Account or until you manually recapture the funds from the failed payment.

Note:

The process for manually recapturing funds depends on the exchange you're using.
Contact your RippleNet liaison for more information.

Failure conversion ensures that during liquidation, your payment's value is converted to fiat currency and that any slippage is accounted for.

Use cases

We recommend that you use the following combination of On-Demand Liquidity (ODL) features, depending on your use case:




For more information about your failure conversion use case, contact your RippleNet liaison.

Prerequisites

If you want to use failure conversion with the Sender Segregated Account, consider the following:

Note:

By default, failure conversion is disabled (set to false) in ODL-RippleNet.

Check failure conversion status

When your payment's status is FAILED with a sub-state of PUSH_FORWARD, it indicates that the failure conversion process has started.

Copy
Copied!
{
   "json": { },
   "created_at": "2022-12-13T18:37:11.138Z",
   "subState": "PUSH_FORWARD"
}

Failure conversion behaves differently depending on where in the payment process the failure occurs.

  • 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.
  • 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.
Note:

Original payments that are subject to failure conversion continue to be marked as FAILED even after failure conversion is successful.

To check a payment's failure conversion status:

  1. To retrieve your payment, use the Get payments operation with "status": "FAILED" and with "with_labels" = "PUSH_FORWARD,SSA_FUNDING_COMPLETED" .
  2. In the response, check the content.push_forward_execution_result array of objects.
    You should see values like in this example:
    Copy
    Copied!
    "push_forward_execution_results": [
    {
    "execution_result_id": "cc004b30-2e4e-4ede-9ef2-8f6c9dddcd17",
    "execution_timestamp": "2022-12-13T18:36:05.363Z",
    "execution_result_type": "CRYPTO_TRANSFER",
    "execution_result_order": "3",
    "sender_address": "sender_address@example",
    "receiver_address": "receiver_address@example",
    "sending_amount": "77.045351000",
    "receiving_amount": "77.045351000",
    "sending_fee": "0.000000000",
    "receiving_fee": "0.000000000",
    "sending_currency_code": null,
    "receiving_currency_code": null,
    "fx_rate": null,
    "transfer_currency_code": "XRP",
    "intermediary_delta": null,
    "incentive_type": null,
    "incentive_value": null,
    "transaction_hash": null,
    "venue_id": "0f397fd5-825c-40c6-b4f1-2595c8e7521f",
    "fiat_adjusted_value": null,
    "odl_payment_id": "726970706C6578766961-01670956230-489-001-244E41524B968BB8C9A0534175A87163A30EEB95CC91B752B4582801E61F1499"
    }
]
    Note:

    The content.execution_results array of objects doesn't get populated for failed payments, only push_forward_execution_results.

  3. Check the content.user_info.settlement_declined array of objects.

    The subState field should show PUSH_FORWARD and there should be an object with fields pertaining to the SSA transfer, like in this example:
    Copy
    Copied!
    "settlement_declined": [
  . . .
  {
    "json": { },
    "created_at": "2022-12-13T18:37:11.138Z",
    "subState": "PUSH_FORWARD"
  },
  {
    "json": {
        "ssa_remote_transfer_id": "2558c823-6737-4955-9ad9-aeec4f94c2f4",
        "transfer_amount": "1669.50",
        "transfer_currency": "PHP",
        "funding_account": "funding_account@example",
        "ssa_account": "ssa_account@example",
        "transfer_state": "EXECUTED"
    },
    "created_at": "2022-12-13T18:41:14.599Z",
    "subState": "SSA_FUNDING_COMPLETED"
  },
  . . .
]