Create a persistent virtual account (partner perimeter).
Creates a persistent virtual account attributed to the authenticated partner. The partner identity (req.user.partnerId from PartnerHmacGuard) is recorded on bankrail.virtual_accounts.consumer_partner_id; the callback dispatcher will sign every credit-confirmed callback to this VA with the partner active callback-signing credential when one exists. Returns 200 OK with the allocated VA details (synchronous creation — bankrail calls Providus DCS during the request). BRR-bearing is governed by the partner customer class (the substrate rule). Government and corporate partners receive BRR-bearing VAs by default; fintech and citizen partners receive reference-only VAs (the brr field is null on the response). The response shape is identical across all classes; only the brr field differs. Fintech opt-in to BRR-bearing is a named future unit.
Partner-visible credential identifier issued by bank-rail at credential provisioning time. Names which credential signed the request; the corresponding signing secret never appears in any request.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "https://example.com/api/v1/bankrail/virtual-account" \ -H "Content-Type: application/json" \ -d '{ "reference": "partner-va-2026-001", "virtualAccountHolder": {}, "callbackUrl": "https://partner.example.com/webhooks/bankrail/credit", "purposeTag": "wallet_account" }'{ "trackingId": "string", "partnerId": "bf408d53-df49-40a6-8455-a34bd4360901", "reference": "string", "status": "active", "provider": "providus", "providerChannel": "dcs", "bankCode": "101", "bankName": "Providus Bank", "currency": "NGN", "virtualAccount": "string", "virtualAccountName": "string", "purposeTag": "string", "creatorMetadata": {}, "createdAt": "2019-08-24T14:15:22Z"}Create a payment intent (partner perimeter). POST
Creates a payment intent attributed to the authenticated partner. The partner identity (req.user.partnerId from PartnerHmacGuard) is recorded on bankrail.payment_intents.consumer_partner_id; the callback dispatcher will sign the credit-confirmed callback with the partner's active callback-signing credential when one exists. Returns 200 OK with the allocated virtual account details (synchronous creation — bankrail calls Providus DCS during the request).
Provision an identity-blind FBO pool virtual account (partner perimeter). POST
Provisions a pooled-collection virtual account into the FBO master, attributed to the authenticated partner and an opaque holderRef. Identity-blind: no customer name/phone is accepted or stored. Each credit on the VA emits an attributed, balance-free funding-event (eventKind=fbo.funding) carrying the holderRef. Reference-only (no BRR). Returns 200 OK synchronously.