Accept bank transfers with a virtual account

A virtual account is a permanent NGN bank account number that belongs to your account, or to a connected account you manage. Anyone can send money to it from any Nigerian bank, at any time, and each deposit becomes a payment in your Bachs balance. In this guide you’ll get your number, share it, test your integration, and match each deposit to the customer who sent it. By the end you’ll have a working way to take repeat bank transfers without a checkout.

Is a virtual account right for you?

A virtual account is one number for your whole business. It is the right tool when the same people pay you again and again. It is the wrong tool when you need each payment tied to one order.

	Virtual account	Bank-transfer checkout
Account number	One permanent number per account	A new number for each payment, valid for 30 minutes
Amount	Any amount	Fixed to the order
Knows which order it pays for	No. You match it yourself	Yes. It carries your `checkout_id` and `reference`
Best for	Retainers, rent, school fees, wallet top-ups, regular clients	One-off orders and invoices
Fee	1%, capped at NGN 300	1.5%, capped at NGN 2,000

You get one virtual account per account, per currency. There is no number per customer. If you need a separate number for each seller or client, give each one a connected account and issue the number there. NGN is the only currency available today.

Get your account number

Before you start

To turn on the virtual_accounts capability, the account needs a representative with a first name, a last name and a BVN. In live mode, Bachs requests the capability for every Nigerian business automatically. Once the BVN is in, Bachs checks it and the representative’s name against the national BVN register. This usually takes a few minutes. If the name does not match, or the BVN is not found, the field comes back as due with a reason you can show. When the capability turns on, Bachs emails the account’s contact email. If the account asked for virtual accounts itself, Bachs also creates the number then and the email includes it. Either way, you can create or read it yourself, as shown below.

Dashboard
API
Connected account

Open your NGN balance

Go to Balance and click Get virtual account on your NGN balance card.

Create the number

Click Request virtual account. If the panel asks for details instead, your account isn’t ready yet. It tells you what it needs.You need to be an owner, or have permission to manage payins.

Copy the details

Click Account details on the card to see the Account number, Bank name and Account name.

Your API key needs virtual_accounts:write to create the number and virtual_accounts:read to read it. Existing keys do not get these scopes automatically. Add them through Edit scopes.

Wait for the capability

Listen for capability.updated with data.capability: "virtual_accounts" and data.status: "active". Before that, POST returns 403 FORBIDDEN.

Create the number

Calling it again returns the same number, so it is safe to retry.

curl -X POST https://sandbox-api.bachs.io/v1/virtual-accounts \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{ "currency": "NGN" }'

{
  "id": "va_8Hs2kQ4mZpXv",
  "currency": "NGN",
  "account_number": "9902847361",
  "account_name": "Ada Stores",
  "bank_name": "Globus Bank",
  "bank_code": "103",
  "status": "active",
  "created_at": "2026-09-22T09:14:02.000Z"
}

Read it back when you need it

GET /v1/virtual-accounts?currency=NGN returns the same object, or 404 NOT_FOUND if there is no number yet.

Each connected account gets its own number, and it belongs to one end user: the person who owns that account. That person has to be verified like any other account holder.Submit the end user’s own first name, last name and BVN. Do not reuse your own details, or another user’s, across connected accounts. Bachs checks the name against the BVN register, and the number is not issued until it matches.

Create the account with the capability

Name virtual_accounts under the merchant configuration. An account with no merchant configuration cannot hold it.

curl -X POST https://sandbox-api.bachs.io/v1/accounts \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{
    "contact_email": "ada@example.com",
    "display_name": "Ada Stores",
    "country": "NG",
    "configuration": {
      "merchant": { "capabilities": { "virtual_accounts": { "requested": true } } }
    }
  }'

The display_name becomes the account name senders see.

Submit the representative

Send the end user’s own name and BVN, and mark the person as the representative. Without representative: true, the name and BVN do not count.

curl -X POST https://sandbox-api.bachs.io/v1/accounts/acct_3Wq8ZfT1yHnJ5sVe \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "persons": [{
        "first_name": "Ada",
        "last_name": "Obi",
        "id_numbers": [{ "type": "bvn", "value": "22345678901", "issuing_country": "NG" }],
        "relationship": { "representative": true }
      }]
    }
  }'

Get the number

When capability.updated reports virtual_accounts as active, call POST /v1/virtual-accounts with your platform’s key and X-Account-Id: acct_3Wq8ZfT1yHnJ5sVe. It returns the number Bachs created, or creates it if it is not there yet.To choose the bank, send bank_code in the same call (see Choose the bank). If Bachs already created the number when the capability turned on, it keeps the bank it has.

In sandbox, the capability is active as soon as you create the account.

Choose the bank

You can choose which bank holds the number. Send bank_code with the currency when you create it:

Bank	`bank_code`
Globus Bank	`103`
Nombank MFB	`090645`
Bank78 MFB	`110072`

Create the number at Nombank MFB

curl -X POST https://sandbox-api.bachs.io/v1/virtual-accounts \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{ "currency": "NGN", "bank_code": "090645" }'

You get the bank you asked for, or an error. If that bank is down, POST returns 400 with VIRTUAL_ACCOUNT_REFUSED and creates nothing. If we have switched it off for now, you get VIRTUAL_ACCOUNT_BANK_UNAVAILABLE. We never give you a number at a different bank. Try again later, pick another bank, or leave bank_code out.
Leave it out and we pick. Leave bank_code out, or send an empty string, and Bachs picks the bank. If that bank is down, we try the next one.
It only counts the first time. Once you have a number, it keeps its bank. Calling POST again returns the same number, whatever bank_code you send. You can’t move a number to another bank.
The response tells you the bank. bank_code on the response is the code from the table above, and bank_name is the name senders see.

Give your customers the account number, bank name and account name together.

Account name: read it from account_name. It is your business name.
Connected accounts: the sender sees the connected account’s name, not your platform’s.
No reference needed: customers don’t need a reference to pay. If they add your invoice number in their bank’s narration or description field, matching is much easier (see Match deposits to customers).

Test your integration in sandbox

A sandbox number looks real but can never receive money. It starts with 90 and its bank_name is always Sandbox Test Bank. Its bank_code is still a real code: the one you sent, or the bank we picked. There is no way to simulate a deposit into it today. In sandbox you can test:

Creating and reading the number, including the idempotent retry
Your handler’s signature check, by sending a sample event:
bachs trigger collection.succeeded

The sample event is shaped like a checkout payment, not a deposit. It has a checkout_id, no payment_method_details, and a lowercase status. Test your deposit-parsing code against the deposit example below instead.

Refunds are not blocked in sandbox, but a live deposit cannot be refunded. Don’t build a refund path for deposits on the strength of a sandbox test.

Receive a deposit

When a deposit arrives, you get collection.succeeded. A deposit is easy to tell apart from a checkout payment because checkout_id is null and virtual_account.type is permanent.

collection.succeeded for a deposit

{
  "id": "evt_3ab4e0d5d27445cf8a52ab3d8cb8f0b1",
  "type": "collection.succeeded",
  "created_at": "2026-09-22T10:41:18.402Z",
  "organization_id": "acct_7KpQ2mNv4XbR9dLc",
  "data": {
    "charge_id": "ch_1a2b3c4d5e6f",
    "checkout_id": null,
    "reference": null,
    "status": "SUCCEEDED",
    "amount": "250000.00",
    "currency": "NGN",
    "settlement_amount": "249700.00",
    "settlement_currency": "NGN",
    "processing_fee": "300.00",
    "processing_fee_currency": "NGN",
    "fee_bearer": "merchant",
    "product_cart": null,
    "customer": { "id": null },
    "payment_method_details": {
      "type": "bank_transfer",
      "bank_transfer": {
        "sender_name": "JANE ADEYEMI",
        "sender_bank": "Guaranty Trust Bank",
        "sender_bank_code": "058",
        "sender_account_number": "2294879124",
        "session_id": "000013260922104115000821734502",
        "narration": "INV-1042",
        "virtual_account": {
          "id": "va_8Hs2kQ4mZpXv",
          "account_number": "9902847361",
          "bank_name": "Globus Bank",
          "type": "permanent",
          "expires_at": null
        }
      }
    },
    "metadata": {}
  }
}

Fields can be null. Every sender field is always present, but the sending bank can leave any of them out. narration in particular is often blank. Code for null on each one.
Deduplicate on the event id. A redelivered event has the same id.
The money is available immediately. NGN deposits move to your available balance as soon as they are confirmed, unless the deposit is over your limit (see Large deposits are held for review).
The fee comes off first. Each deposit costs 1% of the amount, capped at NGN 300, so a NGN 250,000 deposit settles NGN 249,700. See Fees.

Match deposits to customers

A deposit tells you who sent money and how much. It does not tell you what the money is for. Matching is your job, so decide your rules before you go live. A reliable order to try:

A known payer. Save each customer’s sender_account_number the first time you confirm one of their payments. Later deposits from that account are almost certainly theirs.
An invoice number in the narration. Ask customers to put your invoice number in their transfer description. Look for it in narration.
Amount and timing. An exact amount from a customer with one open invoice is a strong hint, but treat it as a suggestion.
Everything else goes to a review queue. Don’t guess. Show unmatched deposits to someone who can check them.

Match a deposit in your collection.succeeded handler

// Run after you have verified the signature and checked the event id is new.
async function matchDeposit(event) {
  const payment = event.data;
  if (payment.checkout_id !== null) return; // a checkout payment, handled elsewhere

  const transfer = payment.payment_method_details?.bank_transfer ?? {};

  const payer = transfer.sender_account_number
    ? await db.payers.findByAccountNumber(transfer.sender_account_number)
    : null;

  const invoice =
    (await db.invoices.findByNumberIn(transfer.narration)) ??
    (payer ? await db.invoices.onlyOpenInvoice(payer.id, payment.amount) : null);

  if (invoice) {
    await db.invoices.markPaid(invoice.id, { chargeId: payment.charge_id });
  } else {
    await db.unmatchedDeposits.add({
      chargeId: payment.charge_id,
      amount: payment.amount,
      senderName: transfer.sender_name ?? null,
      narration: transfer.narration ?? null,
    });
  }
}

Amounts are decimal strings. Compare them as strings, or with a decimal library, never as floats.

Catch up on missed deposits

If your endpoint was down, you can find the deposits you missed in two ways. Replay the events. Redeliver a deposit’s collection.succeeded with POST /v1/webhooks/replay and its charge_id, or by event ID with bachs events replay. See Replay webhook events. List your payments. GET /v1/payments has no filter for deposits, so filter the results yourself. A deposit has:

payment_method.type: "ngn_bank_transfer"
no source.checkout_id

The list does not include sender details. Call GET /v1/payments/{payment_id} for each deposit to get payment_method_details.

List recent payments

curl "https://sandbox-api.bachs.io/v1/payments?limit=100" \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..."

What can go wrong

Large deposits are held for review

Each account has a limit on a single deposit and on a day’s deposits added together. By default both are NGN 5,000,000, with the day counted in UTC. Your account may have its own limits.A deposit over either limit is not refused, because a bank transfer cannot be stopped. It is held for a manual review before it reaches your balance:

You still receive collection.succeeded straight away, with nothing in it to say the deposit is held.
The amount appears in neither your pending nor your available balance until we release it.
No event is sent on release.

If a large deposit has not reached your balance, contact support with the charge_id. To raise your limits ahead of time, see Deposit limits.

The sender details are missing

The sending bank decides what it passes on. Any of sender_name, sender_bank, sender_bank_code, sender_account_number and narration can be null. When they are, the deposit goes to your review queue (see Match deposits to customers). The session_id is the interbank reference your customer’s bank can use to trace the transfer.

A customer sent money by mistake

A deposit cannot be refunded through the API. The payment has is_refundable: false, and a refund request returns 400. Contact support with the charge_id to return it.

Creating the number fails

If the issuing bank refuses to create the number, POST returns 400 with VIRTUAL_ACCOUNT_REFUSED and the bank’s reason. Fix what the reason names, then try again. If the reason isn’t clear, contact support.If the reason is “The bank could not make an account number right now. Please try again in a minute.”, nothing is wrong with the account. The bank is down or slow. Wait a minute and call POST again, or send a different bank_code. It never creates a second number.If you chose a bank we have switched off for now, POST returns 400 with VIRTUAL_ACCOUNT_BANK_UNAVAILABLE. Pick another bank, or leave bank_code out and we pick one.See Virtual account errors for every code.

A number shows as inactive

A number can be marked inactive. It then no longer appears when you read it, but money sent to it is still received and credited. If you see this, contact support before you give out a different number.

Go-live checklist

Your live API key has virtual_accounts:read and virtual_accounts:write.
Your webhook endpoint verifies signatures and deduplicates on the event id.
Your handler copes with null in every sender field.
You have matching rules and a review queue for deposits you can’t match.
You know your deposit limits, and who to contact when a large deposit is held.
You’ve told regular customers the account name they’ll see in their bank app.

The virtual account object
collection.succeeded
The payment object
Deposit limits
Bank-transfer checkout
Capabilities and Requirements
Introducing virtual accounts: an account number your customers can keep on the Bachs blog: when a permanent account number beats a checkout

Overview

Checkout

Payment methods

Customers

After a payment

Dashboard

Fees, currencies and limits

Accept bank transfers with a virtual account

Is a virtual account right for you?

Get your account number

Before you start

Choose the bank

Test your integration in sandbox

Receive a deposit

Match deposits to customers

Catch up on missed deposits

What can go wrong

Go-live checklist

​Is a virtual account right for you?

​Get your account number

​Before you start

​Choose the bank

​Share the number

​Test your integration in sandbox

​Receive a deposit

​Match deposits to customers

​Catch up on missed deposits

​What can go wrong

​Go-live checklist

​Related

Is a virtual account right for you?

Get your account number

Before you start

Choose the bank

Share the number

Test your integration in sandbox

Receive a deposit

Match deposits to customers

Catch up on missed deposits

What can go wrong

Go-live checklist

Related