Cancel a transfer before it is processed

curl --request POST \
  --url https://api.panoflow.io/v1/transfers/{transfer_id}/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "note": "Paid by cheque instead."
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({note: 'Paid by cheque instead.'})
};

fetch('https://api.panoflow.io/v1/transfers/{transfer_id}/cancel', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.panoflow.io/v1/transfers/{transfer_id}/cancel"

payload = { "note": "Paid by cheque instead." }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "trf_01JCDJ8FSSZ5AWSH8VHTPRE95B",
  "object": "transfer",
  "type": "payout",
  "status": "canceled",
  "status_reason": "canceled_by_user",
  "response_code": "21",
  "response_message": "No action taken",
  "source_account": {
    "id": "acc_01JCWPQ5E6EYCNDY0YP57RCYBV",
    "name": "Naira · Main",
    "currency": "NGN",
    "account_number_last4": "6789"
  },
  "counterparty_name": "Swift Couriers Ltd",
  "bank_account": {
    "account_number": "2041188273",
    "bank_code": "033",
    "bank_name": "UBA",
    "account_name": "SWIFT COURIERS LIMITED"
  },
  "amount": {
    "amount": 87500000,
    "currency": "NGN"
  },
  "fee": {
    "amount": 5375,
    "currency": "NGN"
  },
  "total": {
    "amount": 87505375,
    "currency": "NGN"
  },
  "narration": "Last-mile Oct",
  "created_by": {
    "type": "user",
    "id": "usr_01JCG0X454YG4GFDEXZR4YJ2C4",
    "name": "Ngozi Uche"
  },
  "created_at": "2026-10-28T07:40:00Z",
  "updated_at": "2026-10-28T08:05:00Z"
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

Transfers

Cancel a transfer before it is processed

Only from pending_approval or scheduled (CONVENTIONS §8); anything else returns 409 invalid_state with details.status. Once a transfer is processing it has gone to the bank and can’t be stopped. The hold on the amount is released, a pending approval becomes canceled, and status_reason is canceled_by_user. Canceling the next run of a scheduled payment is the same as POST /scheduled-payments/{id}/skip-next. Batch rows are canceled with their batch (POST /batches/{id}/cancel), not one by one (409 invalid_state).

Error codes: invalid_api_key, parameter_invalid, parameter_missing, resource_not_found, scope_missing, csrf_token_invalid, idempotency_key_reused, invalid_state, rate_limited.

POST

transfers

{transfer_id}

cancel

Cancel a transfer before it is processed

curl --request POST \
  --url https://api.panoflow.io/v1/transfers/{transfer_id}/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "note": "Paid by cheque instead."
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({note: 'Paid by cheque instead.'})
};

fetch('https://api.panoflow.io/v1/transfers/{transfer_id}/cancel', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.panoflow.io/v1/transfers/{transfer_id}/cancel"

payload = { "note": "Paid by cheque instead." }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "trf_01JCDJ8FSSZ5AWSH8VHTPRE95B",
  "object": "transfer",
  "type": "payout",
  "status": "canceled",
  "status_reason": "canceled_by_user",
  "response_code": "21",
  "response_message": "No action taken",
  "source_account": {
    "id": "acc_01JCWPQ5E6EYCNDY0YP57RCYBV",
    "name": "Naira · Main",
    "currency": "NGN",
    "account_number_last4": "6789"
  },
  "counterparty_name": "Swift Couriers Ltd",
  "bank_account": {
    "account_number": "2041188273",
    "bank_code": "033",
    "bank_name": "UBA",
    "account_name": "SWIFT COURIERS LIMITED"
  },
  "amount": {
    "amount": 87500000,
    "currency": "NGN"
  },
  "fee": {
    "amount": 5375,
    "currency": "NGN"
  },
  "total": {
    "amount": 87505375,
    "currency": "NGN"
  },
  "narration": "Last-mile Oct",
  "created_by": {
    "type": "user",
    "id": "usr_01JCG0X454YG4GFDEXZR4YJ2C4",
    "name": "Ngozi Uche"
  },
  "created_at": "2026-10-28T07:40:00Z",
  "updated_at": "2026-10-28T08:05:00Z"
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

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

Headers

Idempotency-Key

string

Optional on non-money POSTs; honoured when sent.

Required string length: 1 - 255

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

Path Parameters

transfer_id

string

required

trf_…

Pattern: ^trf_[0-9A-HJKMNP-TV-Z]{26}$

Body

application/json

Optional note kept in the audit log.

note

string

Why it was canceled.

Maximum string length: 500

Response

Canceled.

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

Cancel a transfer before it is processed

Authorizations

Headers

Path Parameters

Body

Response