Fiat Collection(BRL PIX for example)

This guide shows how to accept PIX payments, buy/sell USDC using Virtual Account (VA) balances, and query bills/transactions. All examples are minimal and easy to copy.

1. PIX Collection Service

1.1 Create a Static PIX QR (Create Virtual Account)

Before accepting PIX, create a seller-specific static QR via the create virtual account API. The response contains the static QR and VA details.

Create Virtual Account API link: create virtaul account

Receive Open Virtual Account Status: Open Virtual Account Status

1.2 Receive Funds via Webhook (Real-time Notifications)

After buyers pay the PIX QR, subscribe to our webhook to get instant updates. Use the virtual account payment status payload.

Useful Link： virtual account payment status

1.3 Refund to Original Route (Refund Virtual Account Order)

If a received payment needs to be returned via the same route, call: refund virtual account order

⸻

1.4 List All PIX Transactions (List Virtual Account Orders)

Batch query all PIX VA orders: list virtual account orders

1.5 Master VA Balance Inquiry

Check the total balance across the master VA: Master VA balance inquiry

2. Buy Crypto Using VA Funds (USDC)

You can use VA balances to buy USDC. The flow is:

Get quote (price + fees) → returns a quote_id

Create order (confirm buy/sell/transfer) with that quote_id

Note
• The quote & order APIs are shared across transfer, buy, and sell.
• Distinguish by type when placing the order.
• For sell orders, you must first add a bank account (or list an existing one).

⸻

2.1 Get Stablecoin Quote

POST /quotes/stablecoin

Body (example)

{
"type": "buy", // buy | sell | transfer
"from_currency": "BRL",
"to_currency": "USDC",
"amount": "1500.00", // amount in from_currency
"source": "VA", // using Virtual Account funds
"seller_id": "seller_123"
}

Response (example)

{
"quote_id": "q_9f3d2a",
"price": "1 USDC = 5.51 BRL",
"fee": "5.00",
"fee_currency": "BRL",
"expires_at": "2025-09-15T07:35:00Z",
"net_usdc": "271.33"
}

⸻

2.2 Create Stable Order (Confirm)

POST /orders/stable

Body (example)

{
"type": "buy", // buy | sell | transfer
"quote_id": "q_9f3d2a",
"source": "VA",
"seller_id": "seller_123",
"confirm": true
}

Response (example)

{
"order_id": "ord_71k2h",
"type": "buy",
"status": "PENDING", // PENDING | EXECUTED | FAILED
"filled_usdc": "271.33",
"tx_hash": null
}

⸻

2.3 Bank Accounts (for Sell)

Before sell, add a payout bank account or select an existing one.

Add bank account

POST /bank-accounts

List bank accounts

GET /bank-accounts?seller_id=seller_123

Pass the chosen bank_account_id when you create a sell order.

⸻

Billing & Reports

3.1 PIX Inbound List

Use List Virtual Account Orders to batch query PIX incoming payments:

GET /virtual-accounts/orders?type=pix&...

3.2 Buy/Sell/Transfer Orders (Batch)

Use List Orders (batch) to query trading & transfer history:

GET /orders?types=buy,sell,transfer&from=2025-09-01&to=2025-09-15&page=1&page_size=100

Response (example)

{
"items": [
{
"order_id": "ord_71k2h",
"type": "buy",
"status": "EXECUTED",
"from_currency": "BRL",
"to_currency": "USDC",
"gross_amount": "1500.00",
"fee": "5.00",
"executed_at": "2025-09-15T07:33:12Z"
}
],
"page": 1,
"page_size": 100,
"total": 27
}

⸻

Best Practices
• Idempotency: include Idempotency-Key for POST requests to avoid duplicate orders.
• Timestamps: all times are UTC ISO-8601.
• Webhook security: verify signatures and retry on non-200 responses.
• Quote expiry: always check expires_at before confirming an order.
• Reconciliation: store order_id, quote_id, and your internal reference.

⸻

Error Model (example)

{
"error": {
"code": "invalid_request",
"message": "quote has expired",
"details": { "expired_at": "2025-09-15T07:35:00Z" }
}
}

⸻

If you’d like, I can tailor this guide to your exact endpoint paths and required fields (schemas), and add Postman collection/curl snippets for your sandbox and production environments.

Fiat Collection(BRL PIX for example)

1. PIX Collection Service#

1.1 Create a Static PIX QR (Create Virtual Account)#

1.2 Receive Funds via Webhook (Real-time Notifications)#

1.3 Refund to Original Route (Refund Virtual Account Order)#

1.4 List All PIX Transactions (List Virtual Account Orders)#

1.5 Master VA Balance Inquiry#

2. Buy Crypto Using VA Funds (USDC)#

1. PIX Collection Service

1.1 Create a Static PIX QR (Create Virtual Account)

1.2 Receive Funds via Webhook (Real-time Notifications)

1.3 Refund to Original Route (Refund Virtual Account Order)

1.4 List All PIX Transactions (List Virtual Account Orders)

1.5 Master VA Balance Inquiry

2. Buy Crypto Using VA Funds (USDC)