Create a payment

Collect money into a wallet by bank transfer or virtual wallet.

POST/v1/payments
Idempotentpayment

Creates a collection. For bank_transfer, the response carries a virtualAccount your customer pays into; the payment settles when the inbound credit arrives (a payment.settled webhook fires). For virtual_wallet, settle it with pay from wallet. Requires an Idempotency-Key.

Try it, for realPOST /paymentsscope: payment

Test keys only. Never paste a live key. Your key is stored only in this browser (localStorage) and sent only to the same-origin playground proxy.

›Equivalent request (curl / TypeScript)
curl
curl -X POST https://sandbox.api.acute.network/v1/payments \
  -H "Authorization: Bearer acuinf_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: …" \
  -d '{"method":"bank_transfer","baseAmount":250000,"description":"Order #8842","customer":{"name":"Ada Lovelace","email":"ada@example.com"}}'
TypeScript
const res = await fetch("https://sandbox.api.acute.network/v1/payments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ACUTE_TEST_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({"method":"bank_transfer","baseAmount":250000,"description":"Order #8842","customer":{"name":"Ada Lovelace","email":"ada@example.com"}}),
});
const { data, meta } = await res.json();

# collect ₦2,500 by bank transfer
curl -X POST https://sandbox.api.acute.network/v1/payments \
  -H "Authorization: Bearer acuinf_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 1c4e7a90-2b3d-4f56-8a9b-0c1d2e3f4a5b" \
  -d '{
    "method": "bank_transfer",
    "baseAmount": 250000,
    "description": "Order #8842",
    "customer": { "name": "Ada Lovelace", "email": "ada@example.com" }
  }'
{
  "success": true,
  "statusCode": 201,
  "data": {
    "id": "acuinf208844190037pay",
    "method": "bank_transfer",
    "status": "pending",
    "baseAmount": 250000,
    "fee": 3750,
    "payableAmount": 253750,
    "amountReceived": 0,
    "currency": "NGN",
    "targetWalletId": "acuinf771204938810wlt",
    "description": "Order #8842",
    "expiresAt": "2026-06-24T09:59:50.110Z",
    "settledAt": null,
    "createdAt": "2026-06-24T09:29:50.110Z",
    "virtualAccount": {
      "accountNumber": "7712049388",
      "bankName": "Providus Bank",
      "accountName": "ACUTE / ADA LOVELACE",
      "expiresAt": "2026-06-24T09:59:50.110Z"
    }
  },
  "meta": { "requestId": "req_4f9c2a7e1b0d8c3a5e6f10a2" }
}

Settlement is a webhook, not the response

The 201 returns a pending payment with a NUBAN. Money lands later - react to payment.settled (and handle payment.expired for unpaid NUBANs). Under- and over-payments surface as partial. The bank-transfer guide walks the full lifecycle.

method'bank_transfer' | 'virtual_wallet'bodyrequired

How the payer pays. bank_transfer mints a NUBAN; virtual_wallet is settled from an Acute wallet.

baseAmountinteger (kobo)bodyrequired

The amount you want to collect, in kobo. Positive integer. Fees are added on top for the payer

  • see payableAmount in the response and fees.
targetWalletIdstringbodyoptional

The wallet money settles into (acuinf…wlt). Omit to settle into your organization's settlement wallet.

descriptionstringbodyoptional

A note stored on the payment (e.g. an order id).

customer{ name?, email? }bodyoptional

An optional payer snapshot - name and a valid email.

expiresIninteger (seconds)bodyoptionaldefault: 1800

For bank_transfer only - how long the NUBAN stays payable, in seconds. Defaults to 1800 (30 minutes).

idstringrequired

The payment reference (acuinf…pay).

method'bank_transfer' | 'virtual_wallet'required

The method you created it with.

statusPaymentStatusrequired

One of pending, partial, settled, expired, failed, refunded, partially_refunded. New payments start pending.

baseAmountnumber (kobo)required

The amount you're collecting.

feenumber (kobo)required

The total fee charged on this payment.

payableAmountnumber (kobo)required

What the payer pays: baseAmount + fee.

amountReceivednumber (kobo)required

Cumulative amount received so far (drives partial vs settled).

currencystringrequired

The currency (NGN).

targetWalletIdstringrequired

The wallet money settles into (a wallet reference).

descriptionstring | nullrequired

The note, or null.

expiresAtstring | nullrequired

When the NUBAN expires (bank_transfer); null for virtual_wallet.

settledAtstring | nullrequired

When the payment fully settled; null until then.

createdAtstringrequired

ISO-8601 creation timestamp.

virtualAccountVirtualAccountData | nullrequired

For bank_transfer: { accountNumber, bankName, accountName, expiresAt } - the NUBAN to pay into. null for virtual_wallet.