Accept Payments

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}

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

string

required

The ID of the KYC-approved customer to issue the account to.

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"
  }'

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

string

Filter by currency code (e.g. BRL, USD).

string

Filter by account status.

string

From date (ISO 8601).

string

Search query (account number, customer name, etc.).

number

Results per 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}

string

required

The account number (not the account ID).

string

Filter by customer.

string

Filter by payment status.

string

From date (ISO 8601).

string

To date (ISO 8601).

number

Page number.

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

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:

Event	Triggered when
`virtual_account.deposit`	Payment arrives at a customer’s virtual account
`deposit.created`	A new deposit is initiated
`deposit.updated`	A 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.

Get Started

Payments

Wallets

Customers & Compliance

Transactions

Products

Developer Tools

Regional Guides

Accept Payments

Step 1: Get Supported Pay-in Countries

Step 2: Get Supported Currencies for a Country

Step 3: Create a Virtual Account for a Customer

Step 4: List Virtual Accounts

Step 5: Get Virtual Account Transaction History

Alternative: Gateway-Based Deposits (Quote Flow)

Step 1: Quote the deposit

Step 2: Initiate the deposit

Alternative: Crypto Deposits

Webhooks for Deposit Notifications

​Step 1: Get Supported Pay-in Countries

​Step 2: Get Supported Currencies for a Country

​Step 3: Create a Virtual Account for a Customer

​Step 4: List Virtual Accounts

​Step 5: Get Virtual Account Transaction History

​Alternative: Gateway-Based Deposits (Quote Flow)

​Step 1: Quote the deposit

​Step 2: Initiate the deposit

​Alternative: Crypto Deposits

​Webhooks for Deposit Notifications

Step 1: Get Supported Pay-in Countries

Step 2: Get Supported Currencies for a Country

Step 3: Create a Virtual Account for a Customer

Step 4: List Virtual Accounts

Step 5: Get Virtual Account Transaction History

Alternative: Gateway-Based Deposits (Quote Flow)

Step 1: Quote the deposit

Step 2: Initiate the deposit

Alternative: Crypto Deposits

Webhooks for Deposit Notifications