# Virtual Bank Accounts

## Request a Virtual USD Bank Account

```graphql
mutation {
  requestVirtualBankAccount(customerId: "customer_id") {
    id
    status
  }
}
```

<table><thead><tr><th width="114.77777099609375">Argument</th><th width="104.33331298828125">Type</th><th width="94">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>customer</code></td><td><code>ID!</code></td><td><strong>Yes</strong></td><td>The ID of the customer to request the virtual bank account for. <a href="customers">(Create a customer)</a>.</td></tr></tbody></table>

The mutation returns the new virtual bank account’s global `id`, which you’ll reference in future calls (e.g., fetching the full account details).

## Important Notes

* The virtual bank account is only available for **USD ACH payments**.
* The issuance fee is **free**, but the KYC fee is a **non-refundable $3 fee**. Ensure your balance is sufficient to cover the fee.
* We'll email your customer the KYC form & ToS to complete.
* We recommend that your customer submit their **International Passport** for KYC to increase the chances of approval and account issuance.

***

## Fetch a Virtual Bank Account

```graphql
query {
  virtualBankAccount(id: "virtual_bank_account_id") {
    id
    accountName
    accountNumber
    bankName
    city
    country
    line1
    postalCode
    state
    routingNumber
    status
    createdAt
  }
}
```

<table><thead><tr><th width="114.77777099609375">Argument</th><th width="104.33331298828125">Type</th><th width="94">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td><code>ID!</code></td><td><strong>Yes</strong></td><td>The ID of the virtual bank account to fetch.</td></tr></tbody></table>

The query returns the full details of the virtual bank account.

## Virtual Bank Account Statuses

| Status      | Description                                                                             |
| ----------- | --------------------------------------------------------------------------------------- |
| `requested` | Account has been requested, waiting for KYC verification and ToS acceptance to complete |
| `pending`   | KYC verified and ToS accepted, account creation is in progress                          |
| `active`    | Account successfully created and ready to use                                           |
| `freezing`  | Account is frozen or suspended                                                          |

***

## Fetch Virtual Bank Account KYC Info

```graphql
query {
  virtualBankAccountKycInfo(merchantCustomer: "merchant_customer_id") {
    kycLink
    tosLink
    kycStatus
    tosStatus
    kycRejectionReason
    kycRejectionReasons {
      reason
      developerReason
    }
    pendingIssues
  }
}
```

<table><thead><tr><th width="114.77777099609375">Argument</th><th width="104.33331298828125">Type</th><th width="94">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>merchantCustomer</code></td><td><code>ID!</code></td><td><strong>Yes</strong></td><td>The ID of the merchant customer to fetch KYC info for.</td></tr></tbody></table>

The query returns:

* `kycLink` - URL to the KYC verification form
* `tosLink` - URL to the Terms of Service agreement
* `kycStatus` - Completion status of the KYC verification
* `tosStatus` - Completion status of the ToS agreement
* `kycRejectionReason` - Flat string summary of rejection reasons (only present when `kycStatus` is `rejected` or `incomplete`)
* `kycRejectionReasons` - Structured list of rejection reasons (only present when `kycStatus` is `rejected` or `incomplete`), each containing:
  * `reason` - Human-readable rejection reason
  * `developerReason` - Technical reason intended for debugging
* `pendingIssues` - List of outstanding issues that need to be resolved for KYC approval

### KYC Status Values

| Status       | Description                                                                                       |
| ------------ | ------------------------------------------------------------------------------------------------- |
| `pending`    | KYC verification is in progress                                                                   |
| `verified`   | KYC has been approved and verified                                                                |
| `incomplete` | KYC requires additional information — check `kycRejectionReasons` and `pendingIssues` for details |
| `rejected`   | KYC has been rejected — check `kycRejectionReasons` for details                                   |

### TOS Status Values

| Status     | Description                                |
| ---------- | ------------------------------------------ |
| `pending`  | Terms of Service has not been accepted yet |
| `verified` | Terms of Service has been accepted         |