> ## 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**. KYC approval (`is_va_approved: true`) is required before a virtual account can be issued.
</Note>

## 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](/guides/regional-payouts) for details.
</Note>

<Accordion title="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
  ```
</Accordion>

***

## Create Virtual Account

```
POST /business/virtual-account/create
```

<ParamField body="customer_id" type="string" required>
  The ID of the KYC-approved customer to issue the account to.
</ParamField>

<ParamField body="currency" type="string" required>
  Currency for the virtual account (see supported values above).
</ParamField>

<RequestExample>
  ```bash Brazil (PIX) theme={null}
  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"
    }'
  ```

  ```bash Mexico (SPEI) theme={null}
  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"
    }'
  ```

  ```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);
  ```
</RequestExample>

<ResponseExample>
  ```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"
    }
  }
  ```
</ResponseExample>

***

## List Virtual Accounts

```
GET /business/virtual-account
```

<ParamField query="currency" type="string">
  Filter by currency code (e.g. `BRL`, `USD`).
</ParamField>

<ParamField query="status" type="string">
  Filter by account status.
</ParamField>

<ParamField query="start_date" type="string">
  From date (ISO 8601).
</ParamField>

<ParamField query="q" type="string">
  Search query — account number, customer name, etc.
</ParamField>

<ParamField query="per_page" type="number">
  Results per page.
</ParamField>

<ParamField query="page" type="number">
  Page number.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET 'https://api.yativo.com/api/v1/business/virtual-account?currency=BRL&per_page=20' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```
</RequestExample>

***

## Get Virtual Account

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

<ParamField path="id" type="string" required>
  The virtual account ID.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET 'https://api.yativo.com/api/v1/business/virtual-account/show/va_xxxxxx' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```
</RequestExample>

***

## Virtual Account Transaction History

Retrieve all payments received into a specific virtual account:

```
POST /business/virtual-account/history/{account_number}
```

<ParamField path="account_number" type="string" required>
  The account number (not the account ID).
</ParamField>

<ParamField query="customer_id" type="string">
  Filter by customer ID.
</ParamField>

<ParamField query="status" type="string">
  Filter by payment status.
</ParamField>

<ParamField query="start_date" type="string">
  From date (ISO 8601).
</ParamField>

<ParamField query="end_date" type="string">
  To date (ISO 8601).
</ParamField>

<ParamField query="page" type="number">
  Page number.
</ParamField>

<ParamField query="per_page" type="number">
  Results per page.
</ParamField>

<RequestExample>
  ```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 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```
</RequestExample>

<ResponseExample>
  ```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 }
  }
  ```
</ResponseExample>

***

## Delete Virtual Account

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

<ParamField path="id" type="string" required>
  The virtual account ID to delete.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE 'https://api.yativo.com/api/v1/business/virtual-account/delete-virtual-account/va_xxxxxx' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```
</RequestExample>

***

## 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. All customers must have `is_va_approved: true` before bulk creation.
</Note>

<ParamField body="accounts" type="array" required>
  Array of account creation objects.

  <Expandable title="accounts item fields">
    <ParamField body="customer_id" type="string" required>
      The KYC-approved customer UUID.
    </ParamField>

    <ParamField body="currency" type="string" required>
      Currency for the virtual account (e.g. `"BRL"`, `"MXNBASE"`, `"USDBASE"`).
    </ParamField>
  </Expandable>
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://api.yativo.com/api/v1/business/virtual-account/bulk-account-creation' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -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" }
      ]
    }'
  ```
</RequestExample>

***

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

<ParamField body="account_id" type="string" required>
  The virtual account ID.
</ParamField>

<ParamField body="action" type="string" required>
  `"enable"` or `"disable"`.
</ParamField>

<RequestExample>
  ```bash Disable theme={null}
  curl -X PUT 'https://api.yativo.com/api/v1/business/virtual-account/enable_disable_virtual_account' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -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 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -H 'Content-Type: application/json' \
    -H 'Idempotency-Key: enable-va-001' \
    -d '{
      "account_id": "va_xxxxxx",
      "action": "enable"
    }'
  ```
</RequestExample>

***

## 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}
```

<ParamField path="externalId" type="string" required>
  The external transaction ID of the deposit to refund. This is returned in the `virtual_account.deposit` webhook payload.
</ParamField>

<Note>
  Requires `Idempotency-Key` header. Refunds are subject to the availability of the underlying payment rail — not all currencies support reversals.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://api.yativo.com/api/v1/business/virtual-account/refundPayin/TXNMP2HK81BHJ' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -H 'Content-Type: application/json' \
    -H 'Idempotency-Key: refund-TXNMP2HK81BHJ-001'
  ```
</RequestExample>

***

## 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}
```

<ParamField path="customerId" type="string" required>
  The customer UUID.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET 'https://api.yativo.com/api/v1/business/virtual-account/customer/accounts/da44a3e6-eb5d-429f-8d17-357aa5a6cdf2' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```
</RequestExample>

***

## KYC Requirement

Before issuing a virtual account, the customer's KYC must be approved. Check the `is_va_approved` flag on the customer object:

```bash theme={null}
curl -X GET 'https://api.yativo.com/api/v1/customer/da44a3e6-eb5d-429f-8d17-357aa5a6cdf2' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

If `is_va_approved` is `false`, submit KYC first. See the [Customers & KYC](/yativo-fiat/kyc) guide.