Understanding a Fiat to Fiat transaction

UnblockPay's API enables you to send fiat money from one country and have it arrive as a different fiat currency in another — in a single, unified flow.

Under the hood, the flow uses a stablecoin as an intermediary: the sender's fiat is first converted to a stablecoin (on-ramp), held momentarily in an UnblockPay-managed wallet, then immediately converted and sent to the receiver's bank account in the destination currency (off-ramp). This two-leg process is fully abstracted — your integration only handles the fiat on both ends.

To create a fiat to fiat transaction, first you need to create a Customer, a Wallet, and an External Account.

---

How to create a Fiat to Fiat transaction

Example: A customer sends BRL via Pix in Brazil. UnblockPay converts it to USDC, then immediately converts the USDC to MXN and delivers it to a Mexican bank account via SPEI — all in one transaction.

Step 1: Create a fiat to fiat quote - POST /v1/quote/fiat-to-fiat

This endpoint returns exchange rates for both legs of the conversion: sender fiat → stablecoin and stablecoin → receiver fiat. Both rates are locked for 5 minutes.

In the request body, specify:

• sender — the fiat currency and local payment_rail (e.g. BRL via pix)

• stablecoin — the intermediary currency and blockchain payment_rail (e.g. USDC on solana)

• receiver — the destination fiat currency and local payment_rail (e.g. MXN via spei)

You can optionally include an amount on either the sender or receiver side, and a partner_fee to apply a markup.

The response includes:

• id — unique quote identifier to reference in the next step

• sender_quotation — the fiat A → stablecoin exchange rate

• receiver_quotation — the stablecoin → fiat B exchange rate

• expires_at — timestamp when the rates expire

Step 2: Initiate a fiat to fiat transaction - POST /v1/fiat-to-fiat

This endpoint initiates the transaction. You'll need to provide:

• quote_id — the ID from the previous step

• customer_id — the customer initiating the transaction

• wallet_id — the UnblockPay-managed wallet used as the stablecoin intermediary between the two legs

• sender — the sender's name and document (tax ID or government-issued number)

• receiver — the external_account_id of the registered bank account where fiat B will be delivered

After initiating, you'll receive sender_deposit_instructions with the bank account information where the sender should send fiat A. Once the deposit is detected, UnblockPay handles the full two-leg conversion and settlement automatically — no additional API calls needed.

After initiating a fiat to fiat transaction, we will send a webhook with the event type payin.created.

---

Fiat to Fiat API endpoints

Here are the endpoints you'll need to create or list a fiat to fiat transfer:

• POST /v1/quote/fiat-to-fiat — Create a fiat to fiat quote

• POST /v1/fiat-to-fiat — Initiate a fiat to fiat transaction

• GET v1/transactions/{id} — View details of a specific transaction

• PUT v1/transactions/{id} — Cancel a transaction (only available for awaiting_deposit status)