curl --request POST \
  --url https://api.panoflow.io/v1/transfers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "type": "payout",
  "source_account_id": "acc_01JCWPQ5E6EYCNDY0YP57RCYBV",
  "recipient_id": "rcp_01JCS3C4DWA7N36096Q14DR9GP",
  "amount": {
    "amount": 48000000,
    "currency": "NGN"
  },
  "narration": "PO-2291 haulage, October"
}
'

{
  "id": "trf_01JCNPZX45HY43KWJRP1XPA7Z3",
  "object": "transfer",
  "type": "own_account",
  "status": "completed",
  "status_reason": "settled",
  "response_code": "00",
  "response_message": "Approved or completed successfully",
  "source_account": {
    "id": "acc_01JCWPQ5E6EYCNDY0YP57RCYBV",
    "name": "Naira · Main",
    "currency": "NGN",
    "account_number_last4": "6789"
  },
  "destination_account": {
    "id": "acc_01JCN5SXS5AA819X9YP981068V",
    "name": "Naira · Payroll",
    "currency": "NGN",
    "account_number_last4": "2214"
  },
  "counterparty_name": "Naira · Payroll",
  "amount": {
    "amount": 240000000,
    "currency": "NGN"
  },
  "fee": {
    "amount": 0,
    "currency": "NGN"
  },
  "total": {
    "amount": 240000000,
    "currency": "NGN"
  },
  "created_by": {
    "type": "user",
    "id": "usr_01JCMZ9J92V81E5128Q6RW31FZ",
    "name": "Adaeze Okafor"
  },
  "created_at": "2026-10-28T08:30:00Z",
  "updated_at": "2026-10-28T08:30:00Z",
  "completed_at": "2026-10-28T08:30:00Z"
}

Transfers

Create a transfer

Pays a bank account (type: payout) or moves money between two of the business’s own accounts in the same currency (type: own_account).

Payout (Pay → Review → Confirm it’s you → Sending → Sent):

Pay a saved recipient with recipient_id, or a new account with bank_account (account number + bank code). A new account is name-enquired (or the 24-hour cache is used). If bank_account.account_name is sent and differs from the bank’s answer, the request fails with 422 recipient_name_mismatch unless allow_name_mismatch: true. save_recipient: true saves it as a recipient (recipient_nickname optional) and the response carries the new recipient_id.
Step-up: a customer session must send X-Step-Up-Token; 403 step_up_required otherwise. API keys and agent tokens don’t step up (agents are held by guardrails and ask-first approvals instead).
Balance (amount + fee), per-payment and daily limits and risk rules are checked, then a hold is placed on the amount. Only then does the transfer exist. 422 insufficient_balance, limit_exceeded, daily_limit_exceeded, amount_too_small, amount_too_large, currency_not_enabled.
If the caller’s payments over the approval threshold need a second person, the transfer is created as pending_approval with an approval (kind transfer, or agent_payment for agents) and the response is 201. The hold stays in place until it is approved (→ processing), rejected (→ rejected), canceled or expires (→ canceled). approval_threshold_exceeded is not returned as an error here.
Otherwise the transfer is processing and the response is 202: poll GET /transfers/{id} or wait for payment.completed / payment.failed. It is sent over NIP; if the bank doesn’t answer in time we confirm the outcome with the bank, never by sending again.

Own account (“Transfer now”): no fee, no step-up, no approval, settles straight away and returns 201 with status: completed. destination_account_id must be another account of this business in the same currency (422 currency_mismatch).

Agents (OAuth tokens from the MCP server): type must be payout, source_account_id must be the agent’s own account and recipient_id is required (no raw bank accounts). Guardrails return 422 recipient_not_allowed, limit_exceeded or daily_limit_exceeded (concurrent payments can never take an agent over its daily limit), 403 agent_paused; a payment over the agent’s ask-first amount, or to a new recipient, becomes pending_approval with an agent_payment approval and fires agent.payment.held. The transfer carries agent_id.

Fires payment.created for every transfer created, including pending_approval ones.

Error codes: invalid_api_key, parameter_invalid, parameter_missing, resource_not_found, scope_missing, step_up_required, csrf_token_invalid, idempotency_key_reused, agent_paused, recipient_name_mismatch, insufficient_balance, limit_exceeded, daily_limit_exceeded, amount_too_small, amount_too_large, currency_not_enabled, currency_mismatch, recipient_not_allowed, partner_timeout, bank_unavailable, business_frozen, business_not_approved, rate_limited.

POST

transfers

curl --request POST \
  --url https://api.panoflow.io/v1/transfers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "type": "payout",
  "source_account_id": "acc_01JCWPQ5E6EYCNDY0YP57RCYBV",
  "recipient_id": "rcp_01JCS3C4DWA7N36096Q14DR9GP",
  "amount": {
    "amount": 48000000,
    "currency": "NGN"
  },
  "narration": "PO-2291 haulage, October"
}
'

{
  "id": "trf_01JCNPZX45HY43KWJRP1XPA7Z3",
  "object": "transfer",
  "type": "own_account",
  "status": "completed",
  "status_reason": "settled",
  "response_code": "00",
  "response_message": "Approved or completed successfully",
  "source_account": {
    "id": "acc_01JCWPQ5E6EYCNDY0YP57RCYBV",
    "name": "Naira · Main",
    "currency": "NGN",
    "account_number_last4": "6789"
  },
  "destination_account": {
    "id": "acc_01JCN5SXS5AA819X9YP981068V",
    "name": "Naira · Payroll",
    "currency": "NGN",
    "account_number_last4": "2214"
  },
  "counterparty_name": "Naira · Payroll",
  "amount": {
    "amount": 240000000,
    "currency": "NGN"
  },
  "fee": {
    "amount": 0,
    "currency": "NGN"
  },
  "total": {
    "amount": 240000000,
    "currency": "NGN"
  },
  "created_by": {
    "type": "user",
    "id": "usr_01JCMZ9J92V81E5128Q6RW31FZ",
    "name": "Adaeze Okafor"
  },
  "created_at": "2026-10-28T08:30:00Z",
  "updated_at": "2026-10-28T08:30:00Z",
  "completed_at": "2026-10-28T08:30:00Z"
}

Authorizations

Authorization

string

header

required

Server API key, scoped. pk_test_ keys hit the sandbox tenant.

Headers

Idempotency-Key

string

required

Required on money-moving POSTs. Same key + same body replays the first response; same key + different body returns 409 idempotency_key_reused. Kept 7 days.

Required string length: 1 - 255

X-Step-Up-Token

string

Step-up proof (2FA within the last 5 minutes, from POST /v1/auth/step-up). Required when the caller is a customer session and the request would send money to someone else (payouts, batches, scheduled payments); missing or stale returns 403 step_up_required. Not used for own_account transfers, API keys or agent tokens. Same header as the shared StepUpToken parameter, which is unconditionally required.

X-Request-Id

string

Optional client correlation id, up to 128 characters. It is not echoed: the response's X-Request-Id is always our own req_… id. We log your value with the request as client_request_id, so support can find a request by either id. A longer value is refused with 400 parameter_invalid.

Maximum string length: 128

Body

application/json

Body of POST /transfers and POST /transfers/quote. A payout takes exactly one of recipient_id or bank_account; an own_account transfer takes destination_account_id. Breaking either rule returns 400 parameter_missing (or parameter_unknown for a field that doesn't apply) with param set.

type

enum<string>

required

Customers create payout or own_account; only PanoFlow creates reversal.

Available options:

payout,

own_account

source_account_id

string

required

acc_… to pay from. For agents, the agent's own account.

amount

object

required

What the recipient receives. The fee is charged on top. Currency must match the source account.

Show child attributes

recipient_id

string

rcp_…, a saved recipient (payout). Required for agents.

bank_account

object

A new account to pay (payout). Name-enquired before the transfer is created.

Show child attributes

allow_name_mismatch

boolean

default:false

Pay even though bank_account.account_name differs from the bank's name.

destination_account_id

string

acc_…, another account of this business in the same currency (own_account).

narration

string

Shows on the recipient's bank statement.

Maximum string length: 60

reason

string

Why this payment is being made. Shown to the approver if it needs approval; agents should always send it.

Maximum string length: 500

save_recipient

boolean

default:false

With bank_account, also save it as a recipient ("Save as a recipient for next time").

recipient_nickname

string

Nickname for the recipient saved with save_recipient.

Maximum string length: 60

document_ids

string[]

doc_… files already uploaded (Documents API) to keep with the payment, e.g. the invoice.

Maximum array length: 5

metadata

object

Up to 20 string keys (≤ 40 chars) with string values (≤ 500 chars). Returned on the resource and its events.

Show child attributes

Response

Created and not processing: an own_account transfer that has completed, or a payout waiting for approval (pending_approval, with approval).

Money leaving (or, for a reversal, coming back to) an account. Lifecycle is MovementStatus. A payout always has one source account and, once sent, one NIP session id.

Carries the ISO 8583 outcome (ResponseOutcome, CONVENTIONS §7a). Batch rows and scheduled-payment runs are transfers, so they carry it too:

status	`response_code`
`pending_approval`, `scheduled`, `processing`	`09`
`processing` with `status_reason: awaiting_bank_confirmation` (the status query can't confirm yet)	`01`
`completed`, `reversed`, and a `reversal`	`00`
`failed` after reaching the bank	the bank's NIP code, e.g. `07`, `08`, `51`, `57`, `91`, `97`
`failed` before reaching the bank	ours, from the error mapping in errors.yaml (e.g. `51` for `insufficient_balance` on a scheduled run, `61` for `limit_exceeded`)
`rejected`, `canceled` (never sent)	`21`

response_code

enum<string>

required

Two-character ISO 8583 response code, using the NIBSS NIP meanings (CONVENTIONS §7a). 00 is success. Carried on every error (mapped from error.code, see errors.yaml x-codes) and on every money-movement object (the bank's final code, or our own while it is in flight). Clients must tolerate codes added later.

Available options:

00,

01,

03,

05,

06,

07,

08,

09,

12,

13,

14,

15,

16,

17,

21,

25,

26,

30,

34,

35,

51,

57,

58,

61,

63,

65,

68,

91,

92,

94,

96,

97

Pattern: ^[0-9A-Z]{2}$

response_message

string

required

Standard meaning of the code (the x-codes text), not customer copy. Customer-safe wording is in status_reason / error.message.

Example:

"Approved or completed successfully"

string

required

trf_…

object

string

required

Always transfer.

Allowed value: "transfer"

type

enum<string>

required

payout: to a bank account outside PanoFlow, over NIP.
own_account: between two of this business's accounts in the same currency.
reversal: created by PanoFlow to reverse a completed transfer; read-only for customers and linked by reversal_of.

Available options:

payout,

own_account,

reversal

status

enum<string>

required

Lifecycle shared by every money-moving resource (CONVENTIONS §8). UI labels: completed → "Settled", pending_approval → "Pending approval".

Available options:

draft,

pending_approval,

scheduled,

processing,

completed,

failed,

rejected,

canceled,

reversed

amount

object

required

What the recipient receives.

Show child attributes

fee

object

required

Fee charged on top (zero for own_account). Refunded with the amount if the transfer fails.

Show child attributes

total

object

required

Amount + fee taken from the source account.

Show child attributes

created_by

object

required

Who did something. Shown in activity, approvals and the audit log.

Show child attributes

created_at

string<date-time>

required

RFC 3339, UTC.

Example:

"2026-10-27T08:41:00Z"

updated_at

string<date-time>

required

RFC 3339, UTC.

Example:

"2026-10-27T08:41:00Z"

status_reason

enum<string>

Sub-state of status (clients must tolerate new values):

status	status_reason
`pending_approval`	`awaiting_approval`
`scheduled`	`awaiting_run_date`
`processing`	`queued` (checks and hold done, not yet sent), `sent_to_bank`, `awaiting_bank_confirmation` (no answer from the bank; a status query is running and it will not be re-sent until it answers)
`completed`	`settled`
`failed`	`rejected_by_receiving_bank`, `name_enquiry_failed`, `insufficient_balance`, `limit_exceeded`, `could_not_process`
`rejected`	`rejected_by_approver`
`canceled`	`canceled_by_user`, `approval_expired`, `schedule_skipped`, `schedule_canceled`, `batch_canceled`
`reversed`	`reversed`

Available options:

awaiting_approval,

awaiting_run_date,

queued,

sent_to_bank,

awaiting_bank_confirmation,

settled,

rejected_by_receiving_bank,

name_enquiry_failed,

insufficient_balance,

limit_exceeded,

could_not_process,

rejected_by_approver,

canceled_by_user,

approval_expired,

schedule_skipped,

schedule_canceled,

batch_canceled,

reversed

source_account

object

Account the money left. Omitted on a reversal (the other side is not shown).

Show child attributes

destination_account

object

For own_account and reversal, this business's account that received the money.

Show child attributes

recipient_id

string

rcp_… when paid to (or saved as) a recipient.

counterparty_name

string

Who was paid, as the UI shows it ("Kano Freight Services", "Naira · Payroll").

bank_account

object

For payouts, the account paid, with the name-enquiry account_name.

Show child attributes

narration

string

Shows on the recipient's bank statement.

reason

string

Why it was made (shown to approvers; sent by agents).

nip_session_id

string

NIP session id, present once the payout has been sent. Quote it to the receiving bank.

Pattern: ^\d{30}$

transaction_id

string

txn_…, the line in the Transactions view and on the receipt.

failure

object

Present when status is failed.

Show child attributes

approval

object

The approval, when this transfer needed one (not on batch rows; see the batch).

Show child attributes

batch_id

string

bat_… when this is a row of a batch.

batch_line

integer

The row's line number in the batch file.

Required range: x >= 1

scheduled_payment_id

string

sch_… when this is a run of a scheduled payment.

scheduled_for

string<date>

Run date, for a scheduled transfer.

Example:

"2026-11-07"

agent_id

string

agt_… when an agent created it.

reversal_of

string

On a reversal, the trf_… it reverses.

reversed_by

string

On a reversed transfer, the trf_… of the reversal.

document_ids

string[]

doc_… files kept with the payment (invoice, receipt).

estimated_arrival_at

string<date-time>

Expected arrival while processing.

Example:

"2026-10-27T08:41:00Z"

timeline

object[]

Tracking steps, oldest first. Returned on GET /transfers/{id}; omitted in lists.

Show child attributes

completed_at

string<date-time>

RFC 3339, UTC.

Example:

"2026-10-27T08:41:00Z"

metadata

object

Up to 20 string keys (≤ 40 chars) with string values (≤ 500 chars). Returned on the resource and its events.

Show child attributes

Accounts & transactions

Payments

Collections

Payroll

Approvals

Webhooks & events

OAuth

Create a transfer

Authorizations

Headers

Body

Response