Understanding a Pay-in

UnblockPay's API enables you to convert fiat currencies into stablecoins and transfer them to blockchain wallets — either wallets managed by UnblockPay or external wallets. This process is called a Pay-in (also known as an on-ramp).

To create a pay-in, first you need to create a Customer and a Wallet.

---

How to create or manage a Pay-in

Step 1: Create a quote - POST v1/quote

This endpoint returns a fresh exchange rate for converting fiat money into stablecoins. The quote is valid for 5 minutes and returns a unique id you'll reference when initiating the pay-in.

In the request body, set "type": "on_ramp", specify the sender with the fiat currency and local payment_rail, and the receiver with the stablecoin currency and blockchain payment_rail. You can optionally include an amount on either side and a partner_fee to apply a markup on top of UnblockPay's rate.

Currently supported fiat currencies (pay-in / on-ramp):

Fiat currency	payment_rail
BRL	pix
USD	wire
MXN	spei

Currently supported stablecoins and blockchains (pay-in / on-ramp):

	USDC	USDT
Solana	✅	✅
Ethereum	✅	✅
Polygon	✅	✅
Tron	coming soon	✅
Base	✅	coming soon
Arbitrum	coming soon	coming soon

Step 2: Initiate a fiat to stablecoin pay-in - POST /payin

This endpoint initiates the pay-in process by creating a transaction that converts fiat money into stablecoins and sends the tokens to a blockchain wallet. You'll need to provide the quote_id from the previous step, along with customer_id, sender, and receiver information.

The pay-in amount is not passed here, it's already fixed by the quote (quote_id).

The sender object will include:

Parameter	Definition	Required when	Example
payment_rail	The local payment network for initiating the pay-in. Must match the quote's sender.payment_rail.	Always	pix wire spei
name	The full name of the sender.	payment_rail = pix (BRL)	Satoshi Nakamoto
document	The tax ID or government-issued number from the sender.	payment_rail = pix (BRL)	14965065700 58444469000108
clabe	The sender's 18-digit CLABE.	payment_rail = spei (MXN)	032180000118359719

For wire (USD) pay-ins, sender can be omitted entirely, no extra fields are required.

The receiver request object accepts:

Parameter	Definition	Example
wallet_id	If sending tokens to an UnblockPay-managed wallet, this is our wallet's unique identifier where you want to send the tokens.	0196c1ab-a142-77a9-aa5f-38b3489393fa
address	If sending tokens to an external wallet (not managed by UnblockPay), this is the blockchain wallet address where you want to send the tokens.	HbXsDU6CByKZSi77cj5jTM7NXjBLExYDQ4hFWUJhjA3P

Since UnblockPay cannot pull funds directly from sender bank accounts, the response includes sender_deposit_instructions with the information the customer needs to send the fiat.

• pix (BRL): deposit_address is a Pix Copy & Paste code — display it as-is or generate a QR code from it in your frontend.

• spei (MXN): deposit_address is the CLABE to deposit into.

• wire (USD): there is no deposit_address — instead you get deposit_message (the wire reference to include) plus a bank_account object with bank_name, bank_account_number, routing_number, address, and beneficiary.name.

The sender_deposit_instructions object will include:

Parameter	Definition	Example
amount	The exact amount of fiat money you need to send.	5 10000
currency	The fiat currency you want to convert into stablecoins.	BRL USD MXN
payment_rail	The local payment network for initiating the pay-in.	pix wire spei sepa cvu
deposit_address	UnblockPay's bank account information where you should send fiat money. null for USD wire (use deposit_message/bank_account instead).	00020126580014BR.GOV.BCB.PIX0136da5d58a1-b857-4991-9a72-000efa46ca69520400005303986540550.005802BR5925 UNBLOCK622605221lWUPYIMvTraA7aFwKg63563049ABF
deposit_message	Transfer reference message. Present only for USD (wire, ACH or SWIFT) pay-ins.	BRGMGUPD6TK438PJBYTT
bank_account	Bank account details for the deposit. Present for BRL, MXN, and USD.	-

Once we detect the fiat deposit, the status will be updated to processing and we'll automatically process the conversion and initiate the stablecoin transfer to the receiver.

The finished_at field is only populated when the pay-in reaches a final status.

If you want to understand our fee structure, please check the Fee section.

Transactional Fees

---

View transaction details - GET v1/transactions/{id}

This endpoint allows you to check the status and details of a transaction at any time. You'll need the transaction ID that was returned when you initiated the pay-in.

Cancel a transaction - PUT v1/transactions/{id}

This endpoint allows you to cancel a transaction that is still in the awaiting_deposit status. You cannot cancel pay-ins that are in other statuses. Once cancelled, the transaction cannot be resumed and you'll need to create a new one if needed.

---

Pay-in API endpoints

Here are the endpoints you'll need to create, list or cancel a pay-in transaction:

• POST v1/quote: Create a stablecoin/fiat quote

• POST v1/payin: Initiate fiat to stablecoin pay-in transaction

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

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