Quickstart: Receive a Payment

Type	Best for	Amount	Expiry
Static	Recurring payments from a known customer	Any	Never
Dynamic	One-time invoice or order payments	Fixed	24 hours

Both types receive payments the same way — the payer does a regular bank transfer to the virtual account number. You get a webhook when the money arrives.

Path A — Static Virtual Account

Use this when you want to give a customer a dedicated account number they can reuse.

Step 1: Create the customer

A static virtual account must be linked to a customer. Create one first.

curl -X POST https://api.withcapera.com/b2b/v1/customers \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "CUST-001",
    "firstName": "Amara",
    "lastName": "Okafor",
    "email": "[email protected]",
    "phoneNumber": "+2348012345678"
  }'

Request fields

Field	Type	Required	Description
`reference`	string	Yes	Your unique identifier for this customer — must be unique per business
`firstName`	string	Yes	Customer's first name
`lastName`	string	Yes	Customer's last name
`email`	string	No	Customer's email address
`phoneNumber`	string	No	Customer's phone number
`bvn`	string	No	Bank Verification Number
`nin`	string	No	National Identification Number

Response

{
  "success": true,
  "data": {
    "id": "cust_abc123",
    "reference": "CUST-001",
    "firstName": "Amara",
    "lastName": "Okafor",
    "email": "[email protected]",
    "phoneNumber": "+2348012345678",
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-01-15T10:00:00Z"
  }
}

Save the reference — you'll use it to generate and look up virtual accounts.

Step 2: Generate the virtual account

curl -X POST https://api.withcapera.com/b2b/v1/virtual-accounts/ngn \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customerReference": "CUST-001"
  }'

Request fields

Field	Type	Required	Description
`customerReference`	string	Yes	The `reference` you set when creating the customer
`preferredBank`	string	No	Request a specific bank provider. Omit to use the default.

Response

{
  "success": true,
  "data": {
    "id": "va_xyz789",
    "accountNumber": "1234567890",
    "accountName": "Amara Okafor - Your Business",
    "bankName": "Providus Bank",
    "createdAt": "2024-01-15T10:05:00Z",
    "updatedAt": "2024-01-15T10:05:00Z"
  }
}

Share the accountNumber and bankName with your customer. When they transfer any amount to that account, you will receive a customer.deposit.success webhook.

Path B — Dynamic Virtual Account

Use this when you need the payer to send an exact amount, for example to settle a specific invoice.

Generate a dynamic account

curl -X POST https://api.withcapera.com/b2b/v1/virtual-accounts/dynamic/ngn \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1500000
  }'

Request fields

Field	Type	Required	Description
`amount`	integer	Yes	Expected payment amount in kobo. Minimum 100 (₦1).
`preferredBank`	string	No	Request a specific bank provider. Omit to use the default.

Amounts are in kobo. ₦1 = 100 kobo, ₦15,000 = 1,500,000 kobo.

Response

{
  "success": true,
  "data": {
    "accountNumber": "9900123456",
    "accountName": "Your Business Name",
    "bankName": "Providus Bank",
    "expiresIn": "24h0m0s",
    "fee": 50
  }
}

Field	Description
`accountNumber`	The account number to share with the payer
`accountName`	Your business name as it appears on the account
`bankName`	The bank providing the virtual account
`expiresIn`	How long the account remains active
`fee`	Collection fee in kobo deducted from the incoming deposit

The account accepts only the exact amount specified and expires after 24 hours. When payment arrives you will receive a deposit.success webhook.

Step 3: Handle the webhook

When a payment is received Capera sends a POST to your registered webhook URL.

Customer account deposit (customer.deposit.success)

{
  "id": "evt_ghi789",
  "event": "customer.deposit.success",
  "timestamp": "2024-01-15T12:00:00Z",
  "data": {
    "id": "dep_xyz456",
    "customerReference": "CUST-001",
    "amount": 1500000,
    "fee": 25,
    "currency": "NGN",
    "reference": "CAPERA-CUSTDEP-456",
    "senderAccountName": "John Smith",
    "senderAccountNumber": "1122334455",
    "senderBankName": "First Bank",
    "recipientAccountNumber": "1234567890",
    "recipientBankName": "Providus Bank",
    "sessionId": "000001240115...",
    "transactionId": "txn_abc789",
    "createdAt": "2024-01-15T12:00:00Z"
  }
}

Business account deposit (deposit.success) — received for dynamic accounts

{
  "id": "evt_def456",
  "event": "deposit.success",
  "timestamp": "2024-01-15T12:00:00Z",
  "data": {
    "id": "dep_xyz789",
    "amount": 1500000,
    "fee": 50,
    "currency": "NGN",
    "reference": "CAPERA-DEP-123",
    "senderAccountName": "Jane Doe",
    "senderAccountNumber": "9876543210",
    "senderBankName": "GTBank",
    "recipientAccountNumber": "9900123456",
    "recipientBankName": "Providus Bank",
    "sessionId": "000001240115...",
    "transactionId": "txn_xyz789",
    "createdAt": "2024-01-15T12:00:00Z"
  }
}

Always verify the webhook signature before processing. See Webhooks for signature verification details.

What's next

Quickstart: Make a Transfer — send NGN to a bank account
Virtual Accounts API Reference — full endpoint documentation
Webhooks — set up and verify webhooks