Skip to main content
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}
​
country
string
required
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
​
customer_id
string
required
The ID of the KYC-approved customer to issue the account to.
​
currency
string
required
Currency for the virtual account. Supported values: USDBASE, EURBASE, EURDE, MXN, MXNBASE, MXNUSD, 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": "BRL"
  }'

{
  "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
​
currency
string
Filter by currency code (e.g. BRL, USD).
​
status
string
Filter by account status.
​
start_date
string
From date (ISO 8601).
​
q
string
Search query (account number, customer name, etc.).
​
per_page
number
Results per page.
​
page
number
Page number.
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}
​
account_number
string
required
The account number (not the account ID).
​
customer_id
string
Filter by customer.
​
status
string
Filter by payment status.
​
start_date
string
From date (ISO 8601).
​
end_date
string
To date (ISO 8601).
​
page
number
Page number.
​
per_page
number
Results per page.
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: Crypto Deposits

To accept cryptocurrency deposits, retrieve your crypto wallet addresses: 
GET /crypto/get-wallets

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:
EventTriggered 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.