> ## Documentation Index > Fetch the complete documentation index at: https://docs.panoflow.io/llms.txt > Use this file to discover all available pages before exploring further. # Validate a batch file or rows > Checks a Pay many file without creating anything, for the summary and the "Rows 12 and 27 need fixing" warning. Send the CSV as `multipart/form-data` (`file`), or JSON with either `csv` (pasted rows) or `rows`. CSV format (the template): header `recipient_name,account_number,bank,amount_ngn,narration`, one payment per line. `amount_ngn` is in **naira** (e.g. `450000` or `450000.00`), not kobo, because people fill it in a spreadsheet; every amount in the response is `Money` in kobo. `bank` is matched against bank names and aliases from `GET /banks`. Lines are numbered from 1 after the header. Each row is checked for: name present, a 10-digit numeric account number, a known bank, an amount above zero and within the per-payment limit, narration length. Rows that fail are returned in `skipped_rows` with a `reason` and a customer-safe `message`. Names are **not** enquired here; each row is name-enquired when the batch runs and a failure shows on that row's transfer. A file that can't be read at all (empty, not CSV, no rows under the header) is `422 batch_row_invalid` with `details.fatal`. More rows than the plan allows is `422 batch_too_large` (`details.max_rows`). **Error codes:** `invalid_api_key`, `parameter_invalid`, `parameter_missing`, `resource_not_found`, `scope_missing`, `csrf_token_invalid`, `batch_row_invalid`, `batch_too_large`, `rate_limited`. ## OpenAPI ````yaml /api-reference/openapi.yaml post /batches/validate openapi: 3.1.0 info: title: PanoFlow API version: 0.3.0 description: >- Identity, business, team, customer-side onboarding (KYB), accounts, statements, the customer transactions view, in-app notifications and search for the PanoFlow public API. The customer web app (app.panoflow.io) uses exactly these endpoints; it has no private API. Rules: `CONVENTIONS.md`. Behaviour: `docs/architecture.md`. Design/architecture conflicts: `docs/discrepancies/identity-accounts.md`. ## Authentication * **Customer session** (`__Host-pf_session` cookie; the web app only). The browser calls the API through the web app's same-origin proxy, `https://app.panoflow.io/api/v1/...`, which forwards to `https://api.panoflow.io/v1/...` (ADR 0004). The cookie is host-only on app.panoflow.io (`__Host-` prefix, Secure, HttpOnly, SameSite=Lax, Path=/, no Domain), so the browser never sends it to api.panoflow.io and no credentialed CORS is needed; api.panoflow.io ignores a session cookie that didn't come through the proxy. The session ends after 15 minutes without activity or 12 hours after sign-in, whichever comes first, and is revoked on a password or 2FA change (ADR 0005). A session starts `pending` and becomes `active` once sign-up is finished (legal name, phone verified, authenticator enrolled) or, for a returning user, once 2FA is passed. * **CSRF.** Every state-changing request (POST, PATCH, DELETE) made with the session cookie sends `X-CSRF-Token` with the `csrf_token` of the current session. The proxy passes the header and the browser's `Origin` through unchanged and never adds a token itself; the API checks the token against the session and that `Origin` is `https://app.panoflow.io`, and answers 403 `csrf_token_invalid` otherwise. Sign-up, sign-in and the other unauthenticated auth calls have no token yet, so through the proxy only the `Origin` check applies to them. API keys and OAuth tokens never send the header. * **API key** (`Authorization: Bearer pk_live_…`) and **OAuth 2.1** access tokens (agents, MCP) can call the business, team-read, onboarding-read, account, statement, transaction and search operations allowed by their scopes. They can never call `/v1/auth/*`, `/v1/users/me/*` or `/v1/notifications*` (session only), and agent tokens never hold `team:*`. ## `x-required-scope` * `none`: unauthenticated (sign-up, sign-in, password reset, invite links). Rate-limited per IP and per account. * `self`: any signed-in user acting on their own user, session or notifications. Session only. * `:`: the scope an API key or token needs. For sessions the scope comes from the member's role: | Role | Scopes (this file) | Notes | | --- | --- | --- | | owner | business:read/write, team:read/write, accounts:read/write | Everything, including closing the business account. | | admin | business:read/write, team:read/write, accounts:read/write | Everything except changing the owner. | | finance | business:read, team:read, accounts:read/write | Pays up to the approval threshold alone. | | approver | business:read, team:read, accounts:read | Decides pending approvals; can't start payments. | | developer | business:read, team:read | API keys, webhooks, logs. No balances or payments. | | viewer | business:read, team:read, accounts:read | Read only. | Some writes are limited further by role ("**Roles:**" in the operation description); a disallowed role gets 403 `role_not_permitted`. ## Step-up Operations marked "**Step-up**" need `X-Step-Up-Token` from `POST /v1/auth/step-up` (TOTP or backup code within 5 minutes). ## Errors Errors use the shared `Error` shape, with `error.response_code` (ISO 8583, CONVENTIONS §7a) mapped from `error.code`. Each operation lists the codes it can return. Non-money resources in this file carry no `response_code`; `Transaction` (a view of money movements) composes `ResponseOutcome`. Generated from panobaas-contracts; only operations marked `x-audience: public`. contact: name: PanoFlow API url: https://docs.panoflow.io email: api@panoflow.io servers: - url: https://api.panoflow.io/v1 description: Live and sandbox (sandbox is chosen by `pk_test_` keys and test sessions). - url: https://api-dev-9d8b.up.railway.app/v1 description: >- Development (Railway). Synthetic data and fake partners; redeployed from main, may be reset at any time. security: [] tags: - name: Business description: >- The business (`/v1/businesses/me`): CAC record, how it appears, and the approval threshold for the customer-side two-person rule. x-displayName: Business - name: Accounts description: >- Main, Payroll and sub-accounts with their balances; open, rename, close, share details, confirmation letters and balance totals. Static virtual accounts are in the collections API. x-displayName: Accounts - name: Statements description: >- Monthly and custom-range account statements, generated asynchronously as PDF and CSV. x-displayName: Statements - name: Transactions description: >- The customer transactions view: every movement in and out of the business's accounts, with filters, notes, attachments, receipts and CSV export. x-displayName: Transactions - name: Banks description: > The bank picker and bank name enquiry. Name enquiry asks the receiving bank for the name on an account before anyone pays it or saves it as a recipient. x-displayName: Banks - name: Recipients description: > The people and businesses a business pays (Payments → Recipients). Every recipient is name-enquiry verified when it is saved. Recipients are archived, never deleted. x-displayName: Recipients - name: Transfers description: > One resource for money leaving an account: `payout` to a bank account outside PanoFlow (NIP), and `own_account` moves between the business's own accounts in the same currency. `reversal` transfers made by PanoFlow also appear here, read-only. x-displayName: Transfers - name: Batches description: > Pay many: validate a CSV (or JSON rows), then create a batch. Each valid row becomes its own transfer with `batch_id`; rows that fail validation are skipped and listed with a reason. x-displayName: Batches - name: Scheduled payments description: > Payments that repeat (or run once on a future date). Each run creates a normal transfer, checked like any other. x-displayName: Scheduled payments - name: Approvals description: > When a second person on your team must approve. One generic endpoint for every customer `ApprovalKind`: transfers and batches over the approval threshold, agent payments over an agent's ask-first amount, pay runs, role changes and limit changes. x-displayName: Approvals - name: Limits description: >- Read-only payment limits for the business (per payment, daily, approval threshold). x-displayName: Limits - name: Collections description: >- Header figures for the Collections screen (outstanding, overdue, collected this month, average days to pay) and saved customers (payers). x-displayName: Collections - name: Invoices description: > Create, send, chase, void and track invoices. VAT (7.5%) is computed server-side. An invoice can have its own account number; payments into it are recorded against the invoice automatically, including part payments. x-displayName: Invoices - name: Payment links description: >- Reusable pay pages at `pay.panoflow.io/` with a fixed or customer-entered amount. Can be paused and turned back on. x-displayName: Payment links - name: Virtual accounts description: > Static virtual accounts only: one permanent account number per customer, settling into one of your accounts. Per-invoice account numbers live on the invoice (`virtual_account`), not here. x-displayName: Virtual accounts - name: Inbound credits description: >- Money in. Every transfer received into an invoice account, a static virtual account, a pay page checkout or one of your accounts, and what it was matched to. x-displayName: Inbound credits - name: People description: >- Add, list, update and offboard the people you pay, and the deductions added to each person. x-displayName: People - name: Deduction types description: >- Deductions set up once and applied to everyone or to selected people (PAYE, pension, NHF, loans, advances, savings, custom levies). x-displayName: Deduction types - name: Payroll settings description: >- Pay day, payslip emails, reminders, automatic pay, the second approver and the account runs are paid from. x-displayName: Payroll settings - name: Pay runs description: > Prepare a month's run (computes lines), adjust who is paid and one-off bonuses, approve with 2FA (and a second approver above the threshold), then execute. Execution is asynchronous (202); poll the run or wait for `payrun.completed`. x-displayName: Pay runs - name: Payslips description: Payslips issued for paid lines. Download as PDF or email to the person. x-displayName: Payslips - name: OAuth description: >- OAuth 2.1 authorization server for MCP clients and other apps: metadata, dynamic client registration, the consent page's API (2FA at grant time), grants (connected apps), token and revocation endpoints. Access tokens live 15 minutes; refresh tokens rotate and are bound to the grant. x-displayName: OAuth - name: Webhooks description: >- Endpoints that receive signed events (HMAC-SHA256, `PanoFlow-Signature`), their signing secrets, test events, and deliveries with response codes and latency, retry and replay. x-displayName: Webhooks - name: Events description: >- The event log behind webhooks (30 days), replay, and the event-type catalogue. x-displayName: Events paths: /batches/validate: post: tags: - Batches summary: Validate a batch file or rows description: >- Checks a Pay many file without creating anything, for the summary and the "Rows 12 and 27 need fixing" warning. Send the CSV as `multipart/form-data` (`file`), or JSON with either `csv` (pasted rows) or `rows`. CSV format (the template): header `recipient_name,account_number,bank,amount_ngn,narration`, one payment per line. `amount_ngn` is in **naira** (e.g. `450000` or `450000.00`), not kobo, because people fill it in a spreadsheet; every amount in the response is `Money` in kobo. `bank` is matched against bank names and aliases from `GET /banks`. Lines are numbered from 1 after the header. Each row is checked for: name present, a 10-digit numeric account number, a known bank, an amount above zero and within the per-payment limit, narration length. Rows that fail are returned in `skipped_rows` with a `reason` and a customer-safe `message`. Names are **not** enquired here; each row is name-enquired when the batch runs and a failure shows on that row's transfer. A file that can't be read at all (empty, not CSV, no rows under the header) is `422 batch_row_invalid` with `details.fatal`. More rows than the plan allows is `422 batch_too_large` (`details.max_rows`). **Error codes:** `invalid_api_key`, `parameter_invalid`, `parameter_missing`, `resource_not_found`, `scope_missing`, `csrf_token_invalid`, `batch_row_invalid`, `batch_too_large`, `rate_limited`. operationId: validateBatch parameters: - $ref: '#/components/parameters/RequestId' requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/BatchUpload' encoding: file: contentType: text/csv examples: csv_file: summary: PaySetupMany, october-suppliers.csv uploaded value: source_account_id: acc_01JCWPQ5E6EYCNDY0YP57RCYBV file: | recipient_name,account_number,bank,amount_ngn,narration Musa Ibrahim,0213342210,GTBank,180000,Oct supplies Ngozi Adeyemi,0119337731,GTBank,210000,Oct supplies Zaria Haulage Co,0123454471,Access Bank,450000,Oct haulage application/json: schema: $ref: '#/components/schemas/BatchRowsRequest' examples: pasted: summary: Or paste the rows instead value: source_account_id: acc_01JCWPQ5E6EYCNDY0YP57RCYBV file_name: Pasted rows csv: | recipient_name,account_number,bank,amount_ngn,narration Zaria Haulage Co,0123454471,Access Bank,450000,Oct haulage rows: summary: JSON rows from a customer's own system value: source_account_id: acc_01JCWPQ5E6EYCNDY0YP57RCYBV file_name: october-suppliers.csv rows: - recipient_name: Musa Ibrahim account_number: '0213342210' bank_code: '058' amount: amount: 18000000 currency: NGN narration: Oct supplies - recipient_name: Ngozi Adeyemi account_number: '0119337731' bank: GTBank amount: amount: 21000000 currency: NGN narration: Oct supplies responses: '200': description: The validation result. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/BatchValidation' examples: october_suppliers: summary: MovePayMany, october-suppliers.csv (38 rows, 2 skipped) value: object: batch_validation source_account: id: acc_01JCWPQ5E6EYCNDY0YP57RCYBV name: Naira · Main currency: NGN account_number_last4: '6789' file_name: october-suppliers.csv row_count: 38 valid_count: 36 skipped_count: 2 total: amount: 648000000 currency: NGN fee_total: amount: 193500 currency: NGN available_after: amount: 1415856550 currency: NGN requires_approval: false valid_rows: - line: 1 recipient_name: Musa Ibrahim account_number: '0213342210' bank_code: '058' bank_name: GTBank amount: amount: 18000000 currency: NGN narration: Oct supplies - line: 2 recipient_name: Ngozi Adeyemi account_number: '0119337731' bank_code: '058' bank_name: GTBank amount: amount: 21000000 currency: NGN narration: Oct supplies - line: 3 recipient_name: Benue Agro Supplies account_number: '6012340418' bank_code: '50515' bank_name: Moniepoint MFB amount: amount: 125000000 currency: NGN narration: Oct supplies skipped_rows: - line: 12 reason: account_number_wrong_length message: >- The account number has 9 digits. Naira account numbers have 10. row: recipient_name: Kano Loaders account_number: '012345678' bank: Access Bank amount_ngn: '150000' narration: Oct supplies - line: 27 reason: account_number_wrong_length message: >- The account number has 9 digits. Naira account numbers have 10. row: recipient_name: Zaria Pallets account_number: '204001447' bank: UBA amount_ngn: '200000' narration: Oct supplies '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/Unprocessable' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - ApiKey: [] - OAuth2: [] components: parameters: RequestId: name: X-Request-Id in: header required: false description: > 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`. schema: type: string maxLength: 128 schemas: BatchUpload: type: object description: Multipart body for validate and create with a CSV file. required: - file - source_account_id properties: file: type: string contentMediaType: text/csv description: The CSV, in the template format. source_account_id: type: string description: '`acc_…` to pay from.' skip_invalid_rows: type: boolean default: false description: Create only. Skip invalid rows instead of failing the whole batch. reason: type: string maxLength: 500 description: Create only. Shown to the approver. BatchRowsRequest: type: object description: > JSON body for validate and create. Send either `rows`, or `csv` with the text of a CSV in the template format (what "Or paste the rows instead" sends). required: - source_account_id properties: source_account_id: type: string description: '`acc_…` to pay from (NGN at launch).' file_name: type: string maxLength: 255 description: >- Shown on the batch and its receipt, e.g. "october-suppliers.csv" or "Pasted rows". csv: type: string description: CSV text in the template format (amounts in naira). rows: type: array minItems: 1 items: $ref: '#/components/schemas/BatchRowInput' description: The payments, in order; line numbers start at 1. skip_invalid_rows: type: boolean default: false description: Create only. Skip invalid rows instead of failing the whole batch. reason: type: string maxLength: 500 description: Create only. Shown to the approver if the batch needs approval. oneOf: - required: - rows - required: - csv BatchValidation: type: object description: Result of `POST /batches/validate`. Nothing is created. required: - object - source_account - row_count - valid_count - skipped_count - total - fee_total - available_after - requires_approval - valid_rows - skipped_rows properties: object: type: string const: batch_validation description: Always `batch_validation`. source_account: $ref: '#/components/schemas/AccountSummary' file_name: type: string description: As sent. row_count: type: integer description: Rows read (excluding the header). valid_count: type: integer description: Rows that can be paid. skipped_count: type: integer description: Rows that will be skipped. total: $ref: '#/components/schemas/Money' description: Sum of the valid rows. fee_total: $ref: '#/components/schemas/Money' description: Fees for the valid rows. available_after: $ref: '#/components/schemas/Money' description: >- Source available balance after total + fees ("Available after this batch"). Negative means it can't be covered. requires_approval: type: boolean description: >- True when creating it will return `pending_approval` for this caller. valid_rows: type: array items: $ref: '#/components/schemas/BatchValidRow' description: Rows that can be paid, in file order. skipped_rows: type: array items: $ref: '#/components/schemas/BatchSkippedRow' description: Rows that can't be paid, with reasons. BatchRowInput: type: object description: >- One payment in a JSON batch. Give `bank_code`, or `bank` (a name or alias from `GET /banks`). required: - recipient_name - account_number - amount properties: recipient_name: type: string maxLength: 140 description: Who is being paid. account_number: type: string description: Should be a 10-digit NUBAN; anything else is skipped with a reason. bank_code: $ref: '#/components/schemas/BankCode' bank: type: string description: Bank name or alias, when `bank_code` is not given. amount: $ref: '#/components/schemas/Money' narration: type: string maxLength: 60 description: Shows on the recipient's statement. anyOf: - required: - bank_code - required: - bank AccountSummary: type: object description: >- Enough of a PanoFlow account to show it ("Naira · Main · ••••6789"). Full account in the Accounts API. required: - id - name - currency properties: id: type: string description: '`acc_…`' name: type: string description: >- Display label, e.g. "Naira · Main", "Naira · Payroll", "US dollar · Main". currency: $ref: '#/components/schemas/Currency' account_number_last4: type: string pattern: ^\d{4}$ description: Last four digits of the account number. Money: type: object description: >- An amount in minor units (kobo, cents) with its currency. Never a decimal. required: - amount - currency properties: amount: type: integer format: int64 description: Amount in minor units. ₦450,000.00 is 45000000. examples: - 45000000 currency: $ref: '#/components/schemas/Currency' BatchValidRow: type: object description: A row that passed validation, normalised. required: - line - recipient_name - account_number - bank_code - bank_name - amount properties: line: type: integer minimum: 1 description: Line number. recipient_name: type: string description: Who is being paid. account_number: $ref: '#/components/schemas/NubanAccountNumber' bank_code: $ref: '#/components/schemas/BankCode' bank_name: type: string description: Resolved bank name. amount: $ref: '#/components/schemas/Money' narration: type: string description: Narration. BatchSkippedRow: type: object required: - line - reason - message - row properties: line: type: integer minimum: 1 description: Line number, counting from 1 after the header. reason: $ref: '#/components/schemas/BatchSkipReason' message: type: string description: >- Customer-safe, e.g. "The account number has 9 digits. Naira account numbers have 10." row: $ref: '#/components/schemas/BatchRawRow' Error: type: object required: - error properties: error: type: object required: - response_code - type - code - message - request_id properties: response_code: $ref: '#/components/schemas/ResponseCode' type: type: string enum: - invalid_request - authentication - permission - not_found - conflict - rate_limited - partner - internal description: >- Error class, fixed per `code` (errors.yaml `x-codes` `type`; CONVENTIONS §7). code: $ref: '#/components/schemas/ErrorCode' message: type: string description: >- Safe to show the customer. Never reveals screening, fraud or STR state. param: type: string description: Dot path of the offending field. request_id: type: string description: '`req_…`' doc_url: type: string format: uri description: Page explaining the code. details: type: object additionalProperties: true description: Machine-readable extra context for the code. BankCode: type: string description: The bank's NIBSS NIP institution code (CBN bank code). examples: - '058' Currency: type: string description: >- ISO 4217. Only NGN is live at launch; others return 422 `currency_not_enabled`. enum: - NGN - USD - GBP - EUR - GHS - KES NubanAccountNumber: type: string description: 10-digit Nigerian NUBAN account number. pattern: ^\d{10}$ examples: - '8012457739' BatchSkipReason: type: string description: Why a row can't be paid. Clients must tolerate new values. enum: - recipient_name_missing - account_number_not_numeric - account_number_wrong_length - bank_missing - bank_unknown - amount_invalid - amount_too_small - amount_too_large - narration_too_long - currency_mismatch BatchRawRow: type: object description: >- The row as it was received, so the customer can find and fix it. All values are strings. properties: recipient_name: type: string description: As given. account_number: type: string description: As given. bank: type: string description: Bank name or code as given. amount_ngn: type: string description: >- Amount as given in the CSV (naira), or the JSON amount in minor units as a string. narration: type: string description: As given. ResponseCode: type: string pattern: ^[0-9A-Z]{2}$ description: > 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. enum: - '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' x-codes: '12': Invalid transaction '13': Invalid amount '14': Invalid batch number '15': Invalid session or record id '16': Unknown bank code '17': Invalid channel '21': No action taken '25': Unable to locate record '26': Duplicate record '30': Format error '34': Suspected fraud '35': Contact sending bank '51': No sufficient funds '57': Transaction not permitted to sender '58': Transaction not permitted on channel '61': Transfer limit exceeded '63': Security violation '65': Exceeds withdrawal frequency '68': Response received too late '91': Beneficiary bank not available '92': Routing error '94': Duplicate transaction '96': System malfunction '97': Timeout waiting for response from destination '00': Approved or completed successfully '01': Status unknown, please wait for settlement report '03': Invalid sender '05': Do not honour '06': Dormant account '07': Invalid account '08': Account name mismatch '09': Request processing in progress ErrorCode: type: string description: >- Stable machine-readable error code. Clients must tolerate codes added later. enum: - invalid_json - parameter_missing - parameter_invalid - parameter_unknown - invalid_api_key - session_expired - invalid_credentials - two_factor_required - two_factor_invalid - token_expired - staff_account_not_allowed - role_not_permitted - scope_missing - step_up_required - business_frozen - business_not_approved - account_closed - ip_not_allowed - agent_paused - test_key_on_live - email_not_verified - two_factor_enrolment_required - csrf_token_invalid - resource_not_found - idempotency_key_reused - invalid_state - self_approval_not_allowed - already_decided - duplicate_resource - version_conflict - insufficient_balance - limit_exceeded - daily_limit_exceeded - approval_threshold_exceeded - recipient_not_allowed - recipient_name_mismatch - name_enquiry_failed - account_number_invalid - currency_not_enabled - currency_mismatch - amount_too_small - amount_too_large - schedule_in_past - batch_row_invalid - batch_too_large - document_rejected - checks_incomplete - rate_expired - payroll_short_funds - webhook_url_invalid - password_too_weak - password_breached - scope_not_allowed - application_incomplete - account_balance_not_zero - verification_code_invalid - link_expired - invite_expired - net_pay_negative - notification_channel_locked - phone_not_verified - rate_limited - bank_unavailable - identity_provider_unavailable - registry_unavailable - partner_timeout - screening_unavailable - messaging_unavailable - internal_error x-codes: invalid_json: status: 400 type: invalid_request response_code: '30' meaning: Body is not valid JSON. parameter_missing: status: 400 type: invalid_request response_code: '30' meaning: A required field is missing; see `param`. parameter_invalid: status: 400 type: invalid_request response_code: '30' meaning: A field has the wrong type or format; see `param`. parameter_unknown: status: 400 type: invalid_request response_code: '30' meaning: An unknown field was sent. invalid_api_key: status: 401 type: authentication response_code: '63' meaning: >- Key unknown, revoked, or its business inactive. Never treated as anonymous. session_expired: status: 401 type: authentication response_code: '63' meaning: Session timed out or was revoked. invalid_credentials: status: 401 type: authentication response_code: '63' meaning: Email or password wrong (no hint which). two_factor_required: status: 401 type: authentication response_code: '63' meaning: Password accepted; a 2FA code is needed to finish sign-in. two_factor_invalid: status: 401 type: authentication response_code: '63' meaning: 2FA or backup code wrong or already used. token_expired: status: 401 type: authentication response_code: '63' meaning: OAuth access token expired; refresh it. role_not_permitted: status: 403 type: permission response_code: '57' meaning: The caller's role can't do this. scope_missing: status: 403 type: permission response_code: '57' meaning: The key or token lacks the scope in `details.required_scope`. step_up_required: status: 403 type: permission response_code: '63' meaning: Send a fresh X-Step-Up-Token (2FA within 5 minutes). business_frozen: status: 403 type: permission response_code: '57' meaning: The business is frozen; money can't move. Message stays neutral. business_not_approved: status: 403 type: permission response_code: '57' meaning: Onboarding not approved yet; live money movement is closed. account_closed: status: 403 type: permission response_code: '57' meaning: The account is closed. ip_not_allowed: status: 403 type: permission response_code: '63' meaning: Request came from outside the allowed IP ranges. agent_paused: status: 403 type: permission response_code: '57' meaning: The agent is paused by its owner; its tokens are revoked. test_key_on_live: status: 403 type: permission response_code: '58' meaning: A pk_test_ key was used against a live-only operation. resource_not_found: status: 404 type: not_found response_code: '25' meaning: Not found or not visible to this tenant. idempotency_key_reused: status: 409 type: conflict response_code: '94' meaning: Same Idempotency-Key with a different body. invalid_state: status: 409 type: conflict response_code: '12' meaning: >- The resource's status doesn't allow this action; see `details.status`. self_approval_not_allowed: status: 409 type: conflict response_code: '57' meaning: The requester can't decide their own approval. already_decided: status: 409 type: conflict response_code: '21' meaning: The approval was already approved, rejected or expired. duplicate_resource: status: 409 type: conflict response_code: '26' meaning: An identical resource already exists (e.g. recipient). version_conflict: status: 409 type: conflict response_code: '21' meaning: The resource changed since it was read; re-read and retry. insufficient_balance: status: 422 type: invalid_request response_code: '51' meaning: Available balance can't cover amount + fee; `details.available`. limit_exceeded: status: 422 type: invalid_request response_code: '61' meaning: Over a per-payment limit; `details.limit`. daily_limit_exceeded: status: 422 type: invalid_request response_code: '61' meaning: Over the daily limit. approval_threshold_exceeded: status: 422 type: invalid_request response_code: '09' meaning: >- Over the caller's approval threshold; a pending approval was created instead (see `details.approval_id`). recipient_not_allowed: status: 422 type: invalid_request response_code: '57' meaning: Agent tried to pay a recipient outside its allowlist. recipient_name_mismatch: status: 422 type: invalid_request response_code: '08' meaning: >- Name on the account doesn't match the name given and confirmation wasn't sent. name_enquiry_failed: status: 422 type: invalid_request response_code: '25' meaning: The bank couldn't confirm the account name. account_number_invalid: status: 422 type: invalid_request response_code: '07' meaning: Not a valid NUBAN for that bank. currency_not_enabled: status: 422 type: invalid_request response_code: '12' meaning: Currency not live for this business yet. currency_mismatch: status: 422 type: invalid_request response_code: '12' meaning: Amount currency doesn't match the account's currency. amount_too_small: status: 422 type: invalid_request response_code: '13' meaning: Below the minimum for this payment type. amount_too_large: status: 422 type: invalid_request response_code: '13' meaning: Above the maximum for this payment type. schedule_in_past: status: 422 type: invalid_request response_code: '12' meaning: Scheduled date is not in the future. batch_row_invalid: status: 422 type: invalid_request response_code: '30' meaning: One or more batch rows failed validation; `details.rows`. batch_too_large: status: 422 type: invalid_request response_code: '14' meaning: Batch exceeds the row limit for this plan. document_rejected: status: 422 type: invalid_request response_code: '30' meaning: Upload is the wrong type, too large, or unreadable. checks_incomplete: status: 422 type: invalid_request response_code: '21' meaning: Can't approve; not every KYB check has passed. rate_expired: status: 422 type: invalid_request response_code: '12' meaning: FX quote expired; get a new one. payroll_short_funds: status: 422 type: invalid_request response_code: '51' meaning: Payroll account can't cover the run; `details.short_by`. webhook_url_invalid: status: 422 type: invalid_request response_code: '30' meaning: Webhook URL must be https and publicly reachable. password_too_weak: status: 422 type: invalid_request response_code: '30' meaning: Password fails the strength rules. password_breached: status: 422 type: invalid_request response_code: '30' meaning: Password appears in a known breach. email_not_verified: status: 403 type: permission response_code: '63' meaning: Verify the email address before continuing. two_factor_enrolment_required: status: 403 type: permission response_code: '63' meaning: Set up two-factor authentication before doing anything else. staff_account_not_allowed: status: 401 type: authentication response_code: '63' meaning: >- Sign-in with this Google account is not allowed. Not returned to customers. scope_not_allowed: status: 422 type: invalid_request response_code: '57' meaning: None of the requested OAuth scopes can be granted to this client. application_incomplete: status: 422 type: invalid_request response_code: '21' meaning: >- The onboarding application is missing required details; see `details.issues`. account_balance_not_zero: status: 422 type: invalid_request response_code: '12' meaning: Move the balance out before closing the account. verification_code_invalid: status: 422 type: invalid_request response_code: '63' meaning: The verification code is wrong or expired. link_expired: status: 422 type: invalid_request response_code: '63' meaning: The link has expired; request a new one. invite_expired: status: 422 type: invalid_request response_code: '15' meaning: The invite has expired; ask for a new one. net_pay_negative: status: 422 type: invalid_request response_code: '13' meaning: >- Deductions exceed gross pay for this person; see `details.person_id`. notification_channel_locked: status: 422 type: invalid_request response_code: '57' meaning: >- This notification channel can't be turned off (e.g. email for `compliance_request`); see `param`. phone_not_verified: status: 422 type: invalid_request response_code: '63' meaning: >- Needs a verified phone number first (SMS notifications, SMS recovery codes). csrf_token_invalid: status: 403 type: permission response_code: '63' meaning: >- A state-changing request made with a session cookie had a missing or wrong `X-CSRF-Token`, or came from another origin. rate_limited: status: 429 type: rate_limited response_code: '65' meaning: Too many requests; wait `Retry-After` seconds. bank_unavailable: status: 503 type: partner response_code: '91' meaning: >- Partner bank is down or degraded. Retry with the same Idempotency-Key. identity_provider_unavailable: status: 503 type: partner response_code: '96' meaning: Identity checks provider unavailable. registry_unavailable: status: 503 type: partner response_code: '96' meaning: >- CAC registry unavailable; onboarding continues as "pending registry". partner_timeout: status: 502 type: partner response_code: '97' meaning: >- A partner (the bank, or the SMS provider) didn't answer in time. For payments we confirm the status with the bank before any retry. screening_unavailable: status: 503 type: partner response_code: '96' meaning: >- Sanctions and PEP screening is unavailable; nothing was changed. Retry with the same Idempotency-Key. messaging_unavailable: status: 503 type: partner response_code: '96' meaning: We couldn't send the email or text message right now. Retry shortly. internal_error: status: 500 type: internal response_code: '96' meaning: Our fault. Safe to retry with the same Idempotency-Key. headers: X-Request-Id: description: >- Our request id (`req_…`), on every response. Always ours, never the client's `X-Request-Id`. Quote it to support. schema: type: string X-RateLimit-Limit: description: Requests allowed per minute for this key, token or session. schema: type: integer X-RateLimit-Remaining: description: Requests left in the current window. schema: type: integer X-RateLimit-Reset: description: Unix time when the window resets. schema: type: integer Retry-After: description: Seconds to wait before retrying. schema: type: integer responses: BadRequest: description: Malformed request. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing, invalid or expired credentials. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Authenticated but not allowed (role, scope, step-up, frozen business). headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Not found, or not visible to this tenant. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/Error' Unprocessable: description: Valid request that failed a business rule. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: Too many requests. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/Error' InternalError: description: >- Something went wrong on our side (`internal_error`). Safe to retry with the same Idempotency-Key. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: pk_live_… / pk_test_… description: Server API key, scoped. `pk_test_` keys hit the sandbox tenant. OAuth2: type: oauth2 description: >- OAuth 2.1 with PKCE. Used by agents (MCP) and third-party apps. Access tokens live 15 minutes. flows: authorizationCode: authorizationUrl: https://app.panoflow.io/oauth/authorize tokenUrl: https://api.panoflow.io/v1/oauth/token refreshUrl: https://api.panoflow.io/v1/oauth/token scopes: accounts:read: Read balances, accounts and transactions transfers:read: Read payments transfers:write: Create payments (guardrails-checked for agents) recipients:read: Read recipients recipients:write: Create recipients (allowlist-checked for agents) collections:read: Read invoices, payment links and virtual accounts collections:write: Create invoices and payment links ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.