Collect via bank transfer

A bank-transfer payment is the most Nigerian thing Acute does: you ask for money, we mint a dedicated virtual account (a dynamic NUBAN), your customer transfers into it over NIP, and the moment the funds land we settle the payment and credit a wallet: double-entry, to the kobo. No card, no redirect, no "please don't refresh." Just an account number and a webhook.

Here's the whole thing in one call.

# create a bank-transfer payment
curl -X POST https://sandbox.api.acute.network/v1/payments \
  -H "Authorization: Bearer acuinf_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "bank_transfer",
    "baseAmount": 500000,
    "targetWalletId": "acuinf830192847561wlt",
    "description": "Order #4821",
    "expiresIn": 1800
  }'

baseAmount is what you want to land in the wallet, in kobo. The payer pays a little more (the fee rides on top), so the response hands you the total fee and the account to pay into:

{
  "success": true,
  "statusCode": 201,
  "data": {
    "id": "acuinf471028395610pay",
    "method": "bank_transfer",
    "status": "pending",
    "baseAmount": 500000,
    "fee": 7500,
    "payableAmount": 507500,
    "amountReceived": 0,
    "currency": "NGN",
    "targetWalletId": "acuinf830192847561wlt",
    "description": "Order #4821",
    "expiresAt": "2026-06-26T12:30:00.000Z",
    "settledAt": null,
    "createdAt": "2026-06-26T12:00:00.000Z",
    "virtualAccount": {
      "accountNumber": "9914022731",
      "bankName": "Providus Bank",
      "accountName": "ACUTE / Order #4821",
      "expiresAt": "2026-06-26T12:30:00.000Z"
    }
  }
}

The lifecycle

A bank-transfer payment is a small state machine. It is born pending the instant the NUBAN exists, and it ends one of three ways: fully settled, stuck partial (the payer underpaid), or expired (nobody paid in time). Click through it:

1. Create → pending

POST /payments writes the row as pending and mints a virtual NUBAN against your org's deposit account (short-lived, expiring in 30 minutes by default). No ledger entry is posted yet; there's no money to account for. You hand the virtualAccount.accountNumber to your customer and wait for the webhook.

2. Payer pays → settle

Your customer transfers payableAmount (₦5,075.00 here) into the NUBAN over NIP. The provider fires an inbound webhook; our worker matches it by the virtual NUBAN, records a settlement row, captures the payer's account snapshot (you'll need it for bank refunds), and (when amountReceived >= payableAmount) posts the ledger transaction and bills the Acute fee.

This is the part worth internalising. Here's the exact posting that settles a bank-transfer payment:

Notice what's not there: the provider fee is invisible to the ledger. The provider deducts its own cut on the rail before the money reaches bank_inbound_suspense, so the ledger only ever moves base + the Acute fee. Debits equal credits, drift is zero, and the payer's ₦25.00 went straight to the provider. That's the whole double-entry promise: every leg accounts for itself, and the transaction balances or it doesn't post.

On settle we emit:

{
  "id": "acuinf604815923077evt",
  "type": "payment.settled",
  "createdAt": "2026-06-26T12:07:14.000Z",
  "data": {
    "id": "acuinf471028395610pay",
    "status": "settled",
    "baseAmount": 500000,
    "amountReceived": 507500,
    "currency": "NGN"
  }
}

Partial and overpayment

Real payers fat-finger amounts. Acute does not lose the money either way:

• Underpaid (0 < amountReceived < payableAmount): the payment goes partial and stays open. The same account number keeps accepting funds; further credits can carry it to settled. Each credit re-fires payment.settled with the updated amountReceived.
• Overpaid (amountReceived > payableAmount): the payment goes settled and the surplus is credited to the target wallet: the wallet leg becomes base + surplus, the suspense debit grows to match, and the books still balance.

3. Expiry

If the window closes with nothing (fully) paid, the payment-expiry cron flips the payment to expired and emits payment.expired. The NUBAN stops accepting. If a straggler credit lands on an expired NUBAN, it's reconciled to a manual-review path (no money is ever silently dropped), but the happy path is: expired means closed.

{
  "id": "acuinf771320948566evt",
  "type": "payment.expired",
  "createdAt": "2026-06-26T12:30:05.000Z",
  "data": {
    "id": "acuinf471028395610pay",
    "status": "expired",
    "baseAmount": 500000,
    "amountReceived": 0,
    "currency": "NGN"
  }
}

Statuses at a glance

refunded and partially_refunded only appear after you call /payments/:id/refund.

Don't poll. Listen.

You can GET /payments/:id to read state, but the right pattern is the webhook: register a payment.settled handler, verify the signature, and fulfil the order there. Polling a virtual account is how you discover that networks have latency at the worst possible moment.