Changelog

November 2026

One error format, with codes and request IDs

Action may be needed. Every error from every endpoint now has the same shape:

{
  "message": "The wallet balance cannot cover this amount plus fees.",
  "code": "insufficient_balance",
  "request_id": "req_01m6d5vfycvg029wd8brjnxnby"
}

• code is new and stable. Branch on it instead of on message. See all codes.
• Validation errors list the failing fields under errors, keyed by field name. Some endpoints (bills and banks) used to return a flat list of messages instead.
• The older shapes — {"error": …}, {"status": false, …}, {"success": false, …} and {"status": "error", "error_message": …} — are gone.
• Every response carries an X-Request-Id header, repeated as request_id in errors.
• Unexpected failures no longer include internal error text; quote the request_id to support instead.
• A resource belonging to another account now returns 404 not_found instead of 403.

The token endpoint keeps the OAuth 2.0 error format.

Signed webhooks

Every webhook now carries a Lint-Signature header. Verify it with your signing secret, shown under Integrations → Webhooks. See Verify signatures. Webhooks also carry Lint-Event and Lint-Delivery-Id.

Webhook retries

Failed webhook deliveries are retried six times over about eleven hours (1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours). Previously they were not retried.

Bill order outcomes are always reported

bill_order.completed and bill_order.failed are now sent however an order settles — including orders that were PENDING when you created them. bill_order.payment_refunded is now sent when a failed order's payment returns to your wallet. Each is sent once per order. Payloads now include order.processor_message, and amount and fees, which were null, now carry the order's values in kobo.

Fees in money-in webhooks

virtual_account.payment_received and business.customer.wallet.deposit now carry fees in kobo; it was null.

Amounts must be whole kobo

amount on virtual accounts and simulated transfers, and amount_entered on bill orders, now reject decimals with 422 validation_failed. These were always treated as kobo; a fractional value was silently truncated.

Idempotency keys

POST /wallets/initiate-transfer and POST /vas/billers/create-order accept an Idempotency-Key header. See Idempotent requests.

New and removed paths

• POST /payments/virtual-accounts/create is the documented path for creating a virtual account. POST /payments/virtual-accounts keeps working.
• POST /payments/transfer and GET /customers/identities/{id} are removed. Neither had ever worked.

Fixes

• Virtual accounts now return valid_until; it was always null.
• A payout sent without a remark no longer fails.
• PATCH /customers/{id}/update works. It failed on every request before; it now changes only the fields you send and returns the customer.
• Rate-limited responses (429) include Retry-After.