Submit an outbound transfer (partner perimeter).

Creates an outbound transfer attributed to the authenticated partner. The partner identity (req.user.partnerId from PartnerHmacGuard) is recorded on bankrail.outbound_transfers.consumer_partner_id; the callback dispatcher will sign the terminal-state callback with the partner's active callback-signing credential when one exists. Returns 202 Accepted; the outbound contract is async — failure outcomes surface via state on the response body, not 4xx/5xx.

Authorization

X-Bankrail-Key-Id<token>

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.

clientReference*string

Partner-supplied idempotency key. Enforced unique per (server-derived consumer_id, clientReference). 8-128 chars, alphanumerics + _ . - only.

settlementAccount?string

Logical name of the bankrail-managed settlement account to debit. When omitted, bankrail uses the configured default ('primary').

beneficiaryAccountNumber*string

10-digit NUBAN account number of the beneficiary at the destination bank.

beneficiaryBankCode*string

NIP bank code of the destination bank. 3-digit (legacy CBN) or 6-digit (current NIP).

beneficiaryAccountName*string

Beneficiary account name as recorded with the destination bank.

amountKobo*integer

Amount in kobo (minor unit). Positive integer.

currency*string

ISO 4217 currency code. Today only 'NGN' is accepted.

narration*string

Human-readable description shown on the beneficiary's bank statement.

callbackUrl?string

Full HTTPS URL where bankrail delivers the terminal-state callback. When omitted, the partner must poll for outcome.

creatorMetadata?

Opaque key-value context the partner attaches to the transfer.

brrBearing?boolean

Per-call BRR-bearing upgrade flag (Reading 2). For fintech partners, set to true to upgrade this transfer from reference-only to BRR-bearing; omit or set false for reference-only (default). Government and corporate partners are unconditionally BRR-bearing; the flag is accepted but ignored. Citizens cannot request BRR-bearing.

counterpartyAccountId?string

Optional reference to a saved counterparty external account. When present, bankrail resolves it (scoped to the calling partner) to the stored, name-enquiry-verified beneficiary and ignores the inline beneficiary fields. When absent, the inline beneficiary is required.

Formatuuid

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/bankrail/outbound" \  -H "Content-Type: application/json" \  -d '{    "clientReference": "partner-ref-2026-001",    "beneficiaryAccountNumber": "0123456789",    "beneficiaryBankCode": "999058",    "beneficiaryAccountName": "string",    "amountKobo": 100000,    "currency": "NGN",    "narration": "string"  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "clientReference": "string",  "consumerId": "string",  "partnerId": "bf408d53-df49-40a6-8455-a34bd4360901",  "state": "pending",  "provider": "providus",  "brr": "string",  "providerSessionId": "string",  "providerResponseCode": "string",  "providerResponseMessage": "string",  "failureReason": {},  "rail": {},  "settlementAccountName": "string",  "beneficiaryAccountNumber": "string",  "beneficiaryBankCode": "string",  "beneficiaryAccountName": "string",  "amountKobo": 0,  "currency": "string",  "narration": "string",  "creatorMetadata": {},  "createdAt": "2019-08-24T14:15:22Z",  "stateChangedAt": "2019-08-24T14:15:22Z",  "terminalAt": "2019-08-24T14:15:22Z"}

Empty

Submit an outbound transfer (partner perimeter).

Authorization

Request Body

Response Body

202application/json

400

401

403

409

`application/json`