What does this endpoint do?

The purpose of this endpoint is to initiate a ramp process. The flow it follows is determined by the properties you include in the request:

• On-ramp: Include cryptoWithdrawalInformation to ensure the cryptocurrency is sent to the correct wallet.
• Off-ramp: Include fiatWithdrawalInformation. You must provide either a Key (PIX Key) or a QrCode to ensure the funds are sent to the correct destination.
• Checkout: Do not include either of the above properties.

Refund Configuration & Auto-Refunds

To enable automatic refunds in case of an error during the flow, you must provide the refundCryptoAddress property.

Constraints

The eligibility for an automatic refund depends on when the error occurs:

• Before Trade: If the error happens before the exchange takes place, the refund can be processed for any currency pair.
• After Trade: If the error happens after the exchange, the automatic refund is supported only for equivalent currency pairs (e.g., BRL-BRZ).

Fees

Please note that the blockchainFee field (in the response) specifically refers to the fee charged by the blockchain network to process the transaction, unrelated to the service fees.

Quote Information

For all processes, note that only one type of quote information should be included. In other words, if quoteId is provided, you must not include quoteRequest.

To correctly provide the quoteId, you must use the Request a Quote endpoint.

QR Code Payout Flows (Off-ramp)

When providing a QrCode within fiatWithdrawalInformation for off-ramp transactions, the behavior of the quoteRequest depends on whether the QR Code contains a pre-defined value.

Scenario 1: QR Code without value

If the QR Code does not have an embedded value, you must specify the amount you wish to pay in the quoteRequest.

{
  "taxId": "33821597035",
  "name": "José",
  "email": "[email protected]",
  "externalId": "123",
  "taxIdCountry": "BRA",
  "DepositBlockchain": "Polygon",
  "fiatWithdrawalInformation": {
    "QrCode": "000201..." // Generic QR Code
  },
  "quoteRequest": {
    "Side": "Sell",
    "BaseAmount": 10, // Amount is REQUIRED
    "QuoteAmount": 0,
    "BaseCurrency": "USDC",
    "QuoteCurrency": "BRL"
  }
}

Scenario 2: QR Code with value

If the QR Code already includes a specific value/amount, you must NOT specify values in the quoteRequest. Set both amounts to 0. The system will automatically extract the amount from the QR Code string.

{
  "taxId": "33821597035",
  "name": "José",
  "email": "[email protected]",
  "externalId": "123",
  "taxIdCountry": "BRA",
  "DepositBlockchain": "Polygon",
  "fiatWithdrawalInformation": {
    "QrCode": "000201..." // QR Code with embedded value (e.g., R$ 50.00)
  },
  "quoteRequest": {
    "Side": "Sell",
    "BaseAmount": 0,      // Must be 0
    "QuoteAmount": 0,     // Must be 0
    "BaseCurrency": "USDC",
    "QuoteCurrency": "BRL"
  }
}

Ramp Status

The ramp process can have the following statuses:

• SwapOrderCreated: When the process is initiated, and a ramp is created.
• DepositReceived: Funds received from user (crypto or fiat).
• TradeCompleted: Exchange executed at agreed rate.
• WithdrawalCreated: Withdrawal request initiated.
• WithdrawalProcessing: The ongoing withdrawal process.
• WithdrawalCompleted: Funds sent to destination.
• SwapOrderCompleted: The final status of the ramp, signifying successful completion
• SwapOrderError: The final status of the ramp when it concludes with an error.
• RefundProcessing: Indicates that the refund process has started.
• SwapOrderRefunded: Indicates that the refund has been successfully completed.
• SwapOrderReverted: When trade is reverted.