> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yativo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Virtual Accounts

> Issue local virtual accounts to collect payments in multiple currencies

Virtual accounts give each customer a unique local bank account number. When a payment arrives at that number, it is automatically matched and credited to the right customer — no manual reconciliation needed.

> [!NOTE]
>
> Each customer can hold **one virtual account per currency**. The customer needs an approved endorsement for that currency before you can issue the account. See [KYC Requirement](#kyc-requirement).

## Supported Rails

| Currency | Rail | Countries | Extra required fields |
| - | - | - | - |
| `BRL` | PIX | Brazil | — |
| `MXNBASE` / `MXN` | SPEI | Mexico | — |
| `USDBASE` | ACH / Wire | United States | — |
| `EURBASE` / `EURDE` | SEPA | Europe / Germany | — |
| `MXNUSD` | SPEI (USD-settled) | Mexico | — |
| `ARS` | CVU/CBU | Argentina | `document_id`, `document_type` |

> [!NOTE]
>
> Argentina accounts require the customer's `document_id` and `document_type` (`"CUIT"`, `"CUIL"`, or `"CDI"`) in the create request. The customer must be an Argentine resident. See the [Regional Payouts guide](https://docs.yativo.com/guides/regional-payouts.md) for details.

> [accordion] Type Definitions
>
> ```typescript theme={null}
> interface VirtualAccount {
>   account_id: string;
>   account_number: string;
>   account_type: string;
>   currency: string;
>   customer_id: string;
>   created_at: string;
> }
>
> type SupportedCurrency =
>   | "USDBASE"   // USD (standard ACH/wire)
>   | "EURBASE"   // EUR (SEPA standard)
>   | "EURDE"     // EUR (Germany SEPA)
>   | "MXN"       // Mexican Peso via SPEI
>   | "MXNBASE"   // Mexican Peso via SPEI
>   | "MXNUSD"   // USD-settled via SPEI
>   | "BRL";      // Brazilian Real via PIX
> ```

***

## Create Virtual Account

```
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 (see supported values above).

```bash Brazil (PIX) theme={null}
curl -X POST 'https://api.yativo.com/api/v1/business/virtual-account/create' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unique-key-here' \
  -d '{
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "currency": "BRL"
  }'
```

```bash Mexico (SPEI) theme={null}
curl -X POST 'https://api.yativo.com/api/v1/business/virtual-account/create' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unique-key-here' \
  -d '{
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "currency": "MXNBASE"
  }'
```

```javascript Node.js theme={null}
const { data } = await client.post('/business/virtual-account/create', {
  customer_id: customerId,
  currency: 'BRL',
}, {
  headers: { 'Idempotency-Key': crypto.randomUUID() },
});
console.log('Account number:', data.data.account_number);
```

```json Success theme={null}
{
  "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"
  }
}
```

***

## List Virtual Accounts

```
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.

```bash cURL theme={null}
curl -X GET 'https://api.yativo.com/api/v1/business/virtual-account?currency=BRL&per_page=20' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'
```

***

## Get Virtual Account

```
GET /business/virtual-account/show/{id}
```

**id** `string` *required*

The virtual account ID.

```bash cURL theme={null}
curl -X GET 'https://api.yativo.com/api/v1/business/virtual-account/show/va_xxxxxx' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'
```

***

## Virtual Account Transaction History

Retrieve all payments received into 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 ID.

**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.

```bash cURL theme={null}
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 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'
```

```json Success theme={null}
{
  "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
    }
  ],
  "pagination": { "total": 12, "per_page": 20, "current_page": 1 }
}
```

***

## Delete Virtual Account

```
DELETE /business/virtual-account/delete-virtual-account/{id}
```

**id** `string` *required*

The virtual account ID to delete.

```bash cURL theme={null}
curl -X DELETE 'https://api.yativo.com/api/v1/business/virtual-account/delete-virtual-account/va_xxxxxx' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'
```

The account stops accepting funds and you receive a [`virtual_account.deleted`](https://docs.yativo.com/yativo-fiat/webhooks#virtual_accountdeleted) webhook. An ID that doesn't exist or isn't yours returns `404`.

***

## Bulk Account Creation

Create virtual accounts for multiple customers in a single request. Useful when onboarding a batch of pre-verified customers.

```
POST https://api.yativo.com/api/v1/business/virtual-account/bulk-account-creation
```

> [!NOTE]
>
> Requires `Idempotency-Key` header. Every customer needs an approved endorsement for the currency before bulk creation.

**accounts** `array` *required*

Array of account creation objects.

**accounts item fields**

**customer\_id** `string` *required*

The KYC-approved customer UUID.

**currency** `string` *required*

Currency for the virtual account (e.g. `"BRL"`, `"MXNBASE"`, `"USDBASE"`).

```bash cURL theme={null}
curl -X POST 'https://api.yativo.com/api/v1/business/virtual-account/bulk-account-creation' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: bulk-va-june-001' \
  -d '{
    "accounts": [
      { "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2", "currency": "BRL" },
      { "customer_id": "c586066b-0f29-468f-b775-15483871a202", "currency": "BRL" },
      { "customer_id": "f7e8d9c0-1a2b-3c4d-5e6f-7a8b9c0d1e2f", "currency": "MXNBASE" }
    ]
  }'
```

***

## Enable / Disable Virtual Account

Suspend or reactivate a virtual account without deleting it. Suspended accounts stop receiving deposits.

```
PUT https://api.yativo.com/api/v1/business/virtual-account/enable_disable_virtual_account
```

**account\_id** `string` *required*

The virtual account ID.

**action** `string` *required*

`"enable"` or `"disable"`.

```bash Disable theme={null}
curl -X PUT 'https://api.yativo.com/api/v1/business/virtual-account/enable_disable_virtual_account' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: disable-va-001' \
  -d '{
    "account_id": "va_xxxxxx",
    "action": "disable"
  }'
```

```bash Re-enable theme={null}
curl -X PUT 'https://api.yativo.com/api/v1/business/virtual-account/enable_disable_virtual_account' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: enable-va-001' \
  -d '{
    "account_id": "va_xxxxxx",
    "action": "enable"
  }'
```

***

## Refund a Payin

Reverse a specific incoming deposit back to the sender. Use this when a customer payment needs to be returned.

```
POST https://api.yativo.com/api/v1/business/virtual-account/refundPayin/{externalId}
```

**externalId** `string` *required*

The external transaction ID of the deposit to refund. This is returned in the `virtual_account.deposit` webhook payload.

> [!NOTE]
>
> Requires `Idempotency-Key` header. Refunds are subject to the availability of the underlying payment rail — not all currencies support reversals.

```bash cURL theme={null}
curl -X POST 'https://api.yativo.com/api/v1/business/virtual-account/refundPayin/TXNMP2HK81BHJ' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: refund-TXNMP2HK81BHJ-001'
```

***

## List All Virtual Account History

Retrieve transaction history across all virtual accounts (not scoped to a specific account number):

```
GET https://api.yativo.com/api/v1/business/virtual-account/histories
```

***

## Get Customer Virtual Accounts

List all virtual accounts belonging to a specific customer:

```
GET https://api.yativo.com/api/v1/business/virtual-account/customer/accounts/{customerId}
```

**customerId** `string` *required*

The customer UUID.

```bash cURL theme={null}
curl -X GET 'https://api.yativo.com/api/v1/business/virtual-account/customer/accounts/da44a3e6-eb5d-429f-8d17-357aa5a6cdf2' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'
```

***

## KYC Requirement

Each currency needs a specific endorsement. Find it with:

```bash theme={null}
curl -X GET 'https://api.yativo.com/api/v1/business/virtual-account/currencies-and-endorsements' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'
```

Then check that the customer's endorsement for it is `approved`, either from the `endorsement.updated` webhook or from the `endorsement` list on `GET /customer/{customer_id}`. If it isn't, submit or fix KYC first. See [Track verification with endorsements](https://docs.yativo.com/yativo-fiat/kyc.md#track-verification-with-endorsements).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.