What does this endpoint do?

The purpose of this endpoint is to unlock a Swap Order in the Ramp flow when it becomes stuck due to an error or exception scenario. It provides operational flexibility by allowing you to either refund the operation or force its completion, supporting both on-ramp and off-ramp flows. This unlock is always executed on an existing Swap Order and does not create a new ramp process.

Fields

swapOrderId string (required)
Identifier of the Swap Order that should be unlocked.
unlockAction string (required)
Action to be executed on the Swap Order. Possible values:
- Refund: unlocks the flow by refunding the deposit. Note: This action is supported only for equivalent currency pairs (e.g., USDC-USD, BRL-BRZ).
- Complete: unlocks the flow by forcing the completion of the operation.
cryptoAddress string (optional)
Used in:
- On-ramp flows when you want to complete the withdrawal to a different crypto wallet than the original one.
- Off-ramp flows when you want to refund the deposit in crypto to a specific wallet.
fiatWithdrawalKey string (optional)
Used to specify a destination PIX key in the following scenarios:
- Off-ramp flows when the withdrawal should be made to a different PIX key.
- On-ramp flows to direct a refund to a specific PIX key.
This field becomes required when the original error is related to an invalid PIX key, since a valid replacement key must be provided.

Supported flows and behaviors

The unlock behavior depends on the original Swap Order flow (on-ramp or off-ramp) and the selected unlockAction.

On-ramp flows

Unlock with `Refund`

Possible scenarios:

There was a withdrawal error and you want to return fiat via PIX to the customer.
There was a refund error and you want to complete that refund, you simply need to retry the unlock operation by calling the endpoint one more time.

Constraints:

When the trade has already been executed, this option is available only for equivalent currencies (e.g., BRL–BRZ).
If the error occurs before the trade is executed, the refund can be processed in any currency, and the currencies do not need to be equivalent.

Unlock with `Complete`

Possible scenarios:

Withdrawal error and want to complete
- The flow will retry the payout. You may optionally send a cryptoAddress to complete the withdrawal to a different wallet on the same blockchain configured for the Swap Order.
- If no cryptoAddress is provided, the withdrawal is retried using the original configuration.
Trade error and want to complete
- This scenario is common when the quote has expired and the bypass flow cannot be executed. The unlock will execute a new quote and a new trade before performing the crypto payout. As in other scenarios, this may generate additional costs.

Off-ramp flows

Unlock with `Refund`

Use this option when there was a withdrawal error and you want to return crypto to the customer.

Constraints:

When the trade has already been executed, this option is available only for equivalent currencies (e.g., BRL–BRZ).
If the error occurs before the trade is executed, the refund can be processed in any currency, and the currencies do not need to be equivalent.

Unlock with `Complete`

Use this option when you want to complete the off-ramp, even after an error.

Possible scenarios:

Withdrawal error and want to complete
- The flow will retry the payout. You can optionally send a fiatWithdrawalKey to direct the withdrawal to a different PIX key.
- Note: If the original error was Invalid Pix Key, a valid fiatWithdrawalKey becomes mandatory.
Trade error and want to complete
- This scenario is common when the quote has expired and the bypass flow cannot be executed. The unlock will execute a new quote and a new trade before performing the PIX payout. As in other scenarios, this may generate additional costs.