To receive money, create virtual accounts for your customers. Customers pay into their assigned virtual account using local payment rails (bank transfer, PIX, SPEI, SEPA, etc.). You receive a webhook notification when funds arrive.
Customers must have KYC approved (is_va_approved: true) before you can issue them a virtual account.
Step 1: Get Supported Pay-in Countries Retrieve the list of countries where Yativo supports incoming payments:
GET /payment-methods/payin/countries
curl -X GET 'https://api.yativo.com/api/v1/payment-methods/payin/countries' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
{ "status" : "success" , "data" : [ { "country" : "Brazil" , "iso3" : "BRA" , "iso2" : "BR" }, { "country" : "Mexico" , "iso3" : "MEX" , "iso2" : "MX" }, { "country" : "Chile" , "iso3" : "CHL" , "iso2" : "CL" } ] }
Step 2: Get Supported Currencies for a Country Once you know the destination country, retrieve which currencies are available for deposits:
GET /payment-methods/payin/currency?country={countryCode}
ISO 3166-1 alpha-2 country code (e.g. BR, MX, CL).
curl -X GET 'https://api.yativo.com/api/v1/payment-methods/payin/currency?country=BR' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Step 3: Create a Virtual Account for a Customer Issue a local bank account number to your customer for a specific currency:
POST /business/virtual-account/create
The ID of the KYC-approved customer to issue the account to.
Currency for the virtual account. Supported values: USDBASE, EURBASE, EURDE, MXN, MXNBASE, MXNUSD, BRL.
Brazil (PIX / BRL)
Mexico (SPEI / MXN)
USD (ACH / Wire)
curl -X POST 'https://api.yativo.com/api/v1/business/virtual-account/create' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: unique-key-here' \ -d '{ "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2", "currency": "BRL" }'
curl -X POST 'https://api.yativo.com/api/v1/business/virtual-account/create' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: unique-key-here' \ -d '{ "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2", "currency": "MXNBASE" }'
curl -X POST 'https://api.yativo.com/api/v1/business/virtual-account/create' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: unique-key-here' \ -d '{ "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2", "currency": "USDBASE" }'
{ "status" : "success" , "status_code" : 201 , "message" : "Virtual account creation in progress" , "data" : { "account_id" : "va_xxxxxx" , "account_number" : "9900123456" , "account_type" : "savings" , "currency" : "BRL" , "customer_id" : "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2" , "created_at" : "2026-04-01T10:00:00Z" } }
Step 4: List Virtual Accounts Retrieve all virtual accounts, with optional filters:
GET /business/virtual-account
Filter by currency code (e.g. BRL, USD).
Filter by account status.
Search query (account number, customer name, etc.).
curl -X GET 'https://api.yativo.com/api/v1/business/virtual-account?currency=BRL&per_page=20' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Step 5: Get Virtual Account Transaction History Retrieve payment history for a specific virtual account:
POST /business/virtual-account/history/{account_number}
The account number (not the account ID).
Filter by payment status.
curl -X POST 'https://api.yativo.com/api/v1/business/virtual-account/history/9900123456?start_date=2026-04-01&end_date=2026-04-30' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
{ "status" : "success" , "data" : [ { "amount" : 1000 , "currency" : "BRL" , "status" : "completed" , "credited_amount" : 950 , "transaction_id" : "TXNMP2HK81BHJ" , "sender_name" : "John Smith" , "account_number" : "9900123456" , "transaction_fees" : 50 } ] }
Alternative: Gateway-Based Deposits (Quote Flow) For payment gateways that involve a hosted checkout (rather than a push to a standing account number), use the two-step quote flow.
Step 1: Quote the deposit Call POST /exchange-rate with method_type: "payin" and the gateway’s method_id to lock the exchange rate and get a quote_id:
curl -X POST 'https://api.yativo.com/api/v1/exchange-rate' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "from_currency": "BRL", "to_currency": "USD", "method_id": 15, "method_type": "payin", "amount": 1000 }'
Step 2: Initiate the deposit Pass the quote_id to lock the rate, plus a redirect_url for after the customer completes payment on the hosted page:
curl -X POST 'https://api.yativo.com/api/v1/wallet/deposits/new' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: deposit-001' \ -d '{ "gateway": 15, "quote_id": "QUOTE_ID_FROM_STEP_1", "currency": "USD", "redirect_url": "https://your-app.com/deposit/complete" }'
The response contains a checkout_url — redirect the customer there to complete the payment. Once done they return to your redirect_url and you receive a deposit.completed webhook.
Use virtual accounts (Step 3 above) for recurring or standing deposit addresses. Use the gateway quote flow when the customer initiates a one-time payment on a specific date and you want to lock the rate before they pay.
Alternative: Crypto Deposits To accept cryptocurrency deposits, retrieve your crypto wallet addresses:
curl -X GET 'https://api.yativo.com/api/v1/crypto/get-wallets' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Webhooks for Deposit Notifications Configure a webhook endpoint to be notified in real-time when a deposit arrives. See the Webhooks guide for setup.
Key events for deposits:
Event Triggered when virtual_account.depositPayment arrives at a customer’s virtual account deposit.createdA new deposit is initiated deposit.updatedA deposit status changes (e.g. pending → success)
Example virtual_account.deposit payload:
{ "event.type" : "virtual_account.deposit" , "payload" : { "amount" : 1000 , "currency" : "BRL" , "status" : "completed" , "credited_amount" : 950 , "transaction_id" : "TXNMP2HK81BHJ" , "customer" : { "customer_id" : "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2" , "customer_name" : "Jane Doe" } } }
Respond with a 2xx status within 10 seconds to acknowledge receipt. Failed deliveries are retried automatically.
