Bank transfer

Bank transfer collections work by generating a temporary account for a specific amount. The customer sends the exact amount to it before it expires, and the payment is reconciled to your Zerocash account automatically.

This collection method is available for Kenya (KES) and Nigeria (NGN) only.

Use it for larger payments, invoice-style collections, and customers who prefer bank transfer over mobile money or card.

Happy path

Create the account

Generate a temporary account for the expected amount and currency.

Show the details

Display the account number, bank name, amount, and expiry to the customer.

Customer transfers

They send the exact amount before the account expires.

Confirm

Listen for the webhook or query the transaction status.

Fulfil

Only once the transfer is successful.

1. Create the account

Send a request to Bank Transfer.

Field	Type	Required	Description
`amount`	Number	Yes	Amount to be charged, e.g. `1000`
`currency`	String	Yes	`KES` or `NGN`
`externalReference`	String	Yes	Your own unique ID for reconciliation
`email`	String	Yes	Email address of the customer being charged

Request

{
  "amount": 1000,
  "currency": "NGN",
  "externalReference": "invoice_5678",
  "email": "customer@example.com"
}

Response

{
  "success": true,
  "message": "Account created successfully.",
  "data": {
    "transactionId": "BFiR6ISntYyii9h1GUe6",
    "virtualAccount": {
      "permanent": false,
      "accountNumber": "1250837235",
      "bankName": "78 Finance Company limited (Bank78)",
      "createdAt": "2025-09-05T20:35:21+00:00",
      "expiresAt": "2025-09-05T22:35:21.205979Z",
      "note": "Please make a bank transfer to 78 Finance Company limited (Bank78)",
      "amount": "1000",
      "bankLogo": "https://test.com"
    }
  }
}

2. Show the details to your customer

Render these fields from the response so the customer can complete the transfer:

Field	Show it as
`accountNumber`	The account to transfer to
`bankName`	The receiving bank
`amount`	The exact amount to send
`note`	Instructions for the customer
`expiresAt`	A countdown or deadline
`bankLogo`	Visual identifier for the bank

The customer must transfer the exact amount to the account before expiresAt. A partial or late transfer will not reconcile cleanly.

3. Check the transaction status

Call Get Transaction with the transactionId or your externalReference.

{
  "success": true,
  "data": {
    "transactionId": "BFiR6ISntYyii9h1GUe6",
    "amount": 1000,
    "type": "deposit",
    "currency": "NGN",
    "senderCurrency": "NGN",
    "senderAmount": 1000,
    "receiverCurrency": "NGN",
    "receiverAmount": 1000,
    "chargeStatus": "successful",
    "status": "SUCCESSFUL",
    "method": "bank",
    "note": "Bank transfer received from account 1234567890",
    "fullTimestamp": "2025-09-05T20:40:44+03:00",
    "externalReference": "invoice_5678",
    "thirdPartyReference": "BANK_REF_12345",
    "accountNumber": "1250837235"
  }
}

{
  "success": true,
  "data": {
    "transactionId": "BFiR6ISntYyii9h1GUe6",
    "amount": 1000,
    "type": "deposit",
    "currency": "NGN",
    "chargeStatus": "failed",
    "status": "FAILED",
    "method": "bank",
    "fullTimestamp": "2025-09-05T22:40:44+03:00",
    "externalReference": "invoice_5678",
    "accountNumber": "1250837235"
  }
}

4. Handle webhooks

{
  "event": "transaction_created",
  "data": {
    "transactionId": "BFiR6ISntYyii9h1GUe6",
    "status": "pending",
    "type": "deposit",
    "externalReference": "invoice_5678",
    "method": "bank"
  },
  "timestamp": "2025-09-05T20:35:21.600Z"
}

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "BFiR6ISntYyii9h1GUe6",
    "status": "successful",
    "type": "deposit",
    "externalReference": "invoice_5678",
    "method": "bank",
    "amount": 1000,
    "currency": "NGN"
  },
  "timestamp": "2025-09-05T20:40:44.600Z"
}

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "BFiR6ISntYyii9h1GUe6",
    "status": "failed",
    "type": "deposit",
    "externalReference": "invoice_5678",
    "method": "bank",
    "amount": 1000,
    "currency": "NGN"
  },
  "timestamp": "2025-09-05T22:40:44.600Z"
}

5. Handle expiry

Accounts created this way are temporary and expire at expiresAt. After that:

The account can no longer receive new transfers.
Transfers received after expiry may not reconcile automatically.
Create a new account if the customer needs more time.

If a transfer lands after expiry, you may need to reconcile manually. Contact support@zerocash.tech for help.

Best practices

Verify before fulfilling

Confirm the status even after receiving a webhook. Never release goods on account creation alone.

Store both references

Keep transactionId and externalReference for reconciliation and support tickets.

Surface the deadline

Show the customer a live countdown to expiresAt, and re-issue an account when it lapses.

Prefer webhooks

Use webhooks for real-time updates rather than polling the status endpoint in a loop.

Get Started

Before You Build

Charges

Payouts

Webhooks

Testing

Errors

Happy path

1. Create the account

2. Show the details to your customer

3. Check the transaction status

4. Handle webhooks

5. Handle expiry

Best practices

Verify before fulfilling

Store both references

Surface the deadline

Prefer webhooks

​Happy path

​1. Create the account

​2. Show the details to your customer

​3. Check the transaction status

​4. Handle webhooks

​5. Handle expiry

​Best practices

Verify before fulfilling

Store both references

Surface the deadline

Prefer webhooks

Happy path

1. Create the account

2. Show the details to your customer

3. Check the transaction status

4. Handle webhooks

5. Handle expiry

Best practices