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

# Overview

> Create unique virtual account numbers for customers or transactions — each payment recorded as an independent VA Transaction.

Virtual Account (VA) is a bank transfer payment method where each customer or transaction gets a unique account number to pay into. One Virtual Account can receive multiple payments over time, with each payment recorded as a separate **VA Transaction**.

<CardGroup cols={3}>
  <Card title="Unique per transaction" icon="hashtag">
    Each VA has its own number — no payment collisions between customers or orders.
  </Card>

  <Card title="Temporary or permanent" icon="calendar">
    Create one-time VAs that expire, or permanent VAs for recurring customers.
  </Card>

  <Card title="Multi-bank support" icon="building-columns">
    BRI, BNI, BCA, Maybank, Danamon, and more — customers pay via ATM or mobile banking.
  </Card>
</CardGroup>

***

## Payment flow

```mermaid theme={null}
sequenceDiagram
  autonumber
  participant M as Merchant System
  participant S as SingaPay API
  participant C as Customer
  participant B as Bank Network

  M->>S: POST /virtual-accounts/{account_id}
  Note over M,S: Create VA with amount & expiry
  S-->>M: VA Number & details (e.g. 8890-1234-5678)

  M->>C: Share VA number
  Note over M,C: Invoice, email, or app notification

  C->>B: Transfer to VA number
  Note over C,B: ATM, mobile banking, internet banking

  B->>S: Payment notification
  S->>S: Create VA Transaction (pending → paid)
  S-->>M: Webhook notification (optional)

  M->>S: GET /va-transactions/{account_id}
  Note over M,S: Verify and track payment status
```

***

## Virtual Account vs VA Transaction

<CardGroup cols={2}>
  <Card title="Virtual Account (Parent)" icon="vault">
    **The payment instrument.** Defines how and where to pay.

    * Unique VA number per account/transaction
    * Configured with fixed or open amount
    * Can be temporary (with expiry) or permanent
    * Controls max usage and validity period
  </Card>

  <Card title="VA Transaction (Child)" icon="clock-rotate-left">
    **The payment record.** Created every time a customer pays.

    * Individual payment records per transfer
    * Linked to one Virtual Account
    * Tracks status and settlement
    * One VA → multiple transactions
  </Card>
</CardGroup>

<Info>
  **Example:** VA `8890-1234-5678` receives 3 bank transfers on different days → 3 separate VA Transaction records are created, each with its own status, amount, and settlement data.
</Info>

***

## VA types

| Type          | Expiry                      | Use case                                           |
| ------------- | --------------------------- | -------------------------------------------------- |
| **Temporary** | Yes — based on `expired_at` | One-time invoices, orders with deadlines           |
| **Permanent** | No                          | Recurring customers, standing payment instructions |

<Tip>
  Use **temporary VAs** for order-based payments where you want the VA to stop accepting payment after a deadline. Use **permanent VAs** for customers who pay regularly on the same account number.
</Tip>

***

## Amount types

| Type     | Description                                             |
| -------- | ------------------------------------------------------- |
| `closed` | Fixed amount — only accepts the exact configured amount |
| `open`   | Any amount — customer can transfer any value            |

***

## Supported banks — comparison

| Bank Code    | Min (IDR) | Max (IDR)     | Settlement | Sharia    |
| ------------ | --------- | ------------- | ---------- | --------- |
| **BCA**      | 10,000    | 20,000,000\*  | T+1        | —         |
| **BNI**      | 10,000    | 250,000,000\* | T+1        | —         |
| **BRI**      | 10,000    | 250,000,000\* | T+1        | —         |
| **MANDIRI**  | 10,000    | 100,000,000\* | T+1        | —         |
| **PERMATA**  | 10,000    | 50,000,000\*  | T+1        | —         |
| **MAYBANK**  | 10,000    | 250,000,000\* | T+1        | —         |
| **CIMB**     | 10,000    | 50,000,000\*  | T+1        | —         |
| **BSI**      | 10,000    | 50,000,000\*  | T+1        | ✓ Islamic |
| **MUAMALAT** | 10,000    | 50,000,000\*  | T+1        | ✓ Islamic |
| **BNC**      | 10,000    | 50,000,000\*  | T+1        | —         |
| **OCBC**     | 10,000    | 50,000,000\*  | T+1        | —         |
| **DANAMON**  | 10,000    | 50,000,000\*  | T+1        | —         |

\* Maximum limits are configurable per merchant tier. Contact your account manager or customer service to discuss higher limits.

## Important notes

<AccordionGroup>
  <Accordion title="One VA, multiple transactions" icon="arrows-rotate">
    A single Virtual Account can receive multiple payments over its lifetime. Each transfer is independently recorded as a VA Transaction — with its own timestamp, amount, and settlement status.
  </Accordion>

  <Accordion title="Temporary VA expiry and usage limit" icon="hourglass">
    Temporary VAs expire based on your `expired_at` setting. You can also set `max_usage` to limit how many times a VA can be paid — useful for one-time invoices or limited-slot registrations.
  </Accordion>

  <Accordion title="Permanent VA for recurring payments" icon="calendar-check">
    Permanent VAs never expire and are ideal for recurring payments from the same customer — subscriptions, monthly invoices, or standing transfer instructions.
  </Accordion>

  <Accordion title="Amount validation" icon="scale-balanced">
    For `closed` VAs, Singapay validates that the transfer amount exactly matches the configured amount. Mismatched amounts are rejected by the bank network before reaching Singapay.
  </Accordion>

  <Accordion title="Cannot delete a VA with transactions" icon="lock">
    Once a VA has received at least one payment, it cannot be deleted. This preserves the integrity of all linked VA Transaction records.
  </Accordion>

  <Accordion title="Tracking payments" icon="magnifying-glass">
    Use the VA Transaction API to list all payments received by a VA, filter by status or date range, and retrieve settlement details per transaction.
  </Accordion>
</AccordionGroup>

***

## Available endpoints

<CardGroup cols={2}>
  <Card title="List Virtual Accounts" icon="list" href="./list">
    Paginated list of VAs for an account.
  </Card>

  <Card title="Show Virtual Account" icon="eye" href="./show">
    Retrieve a single VA by ULID.
  </Card>

  <Card title="Create Virtual Account" icon="plus" href="./create">
    Generate a new VA with bank, amount type, and expiry configuration.
  </Card>

  <Card title="Update Virtual Account" icon="pen" href="./update">
    Update mutable fields on an existing VA.
  </Card>

  <Card title="Delete Virtual Account" icon="trash" href="./delete">
    Delete a VA that has no transactions.
  </Card>
</CardGroup>

<Note>
  All endpoints require authentication. See [Authentication](/api-reference/authentication).
</Note>