Create a batch

curl --request POST \
  --url https://api.panoflow.io/v1/batches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --form source_account_id=acc_01JCWPQ5E6EYCNDY0YP57RCYBV \
  --form skip_invalid_rows=true \
  --form 'reason=October supplier run' \
  --form '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
;type=text/csv'

const form = new FormData();
form.append('source_account_id', 'acc_01JCWPQ5E6EYCNDY0YP57RCYBV');
form.append('skip_invalid_rows', 'true');
form.append('reason', 'October supplier run');
form.append('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
');

const options = {
  method: 'POST',
  headers: {'Idempotency-Key': '<idempotency-key>', Authorization: 'Bearer <token>'}
};

options.body = form;

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

import requests

url = "https://api.panoflow.io/v1/batches"

files = {}
files["file"] = (None, "recipient_name,account_number,bank,amount_ngn,narration\nMusa Ibrahim,0213342210,GTBank,180000,Oct supplies\nNgozi Adeyemi,0119337731,GTBank,210000,Oct supplies\nZaria Haulage Co,0123454471,Access Bank,450000,Oct haulage\n", "text/csv")
payload = {
    "source_account_id": "acc_01JCWPQ5E6EYCNDY0YP57RCYBV",
    "skip_invalid_rows": "true",
    "reason": "October supplier run"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

{
  "id": "bat_01JCYFGCW8T7SWM4FV4DK79Q9G",
  "object": "batch",
  "status": "pending_approval",
  "status_reason": "awaiting_approval",
  "source_account": {
    "id": "acc_01JCWPQ5E6EYCNDY0YP57RCYBV",
    "name": "Naira · Main",
    "currency": "NGN",
    "account_number_last4": "6789"
  },
  "file_name": "october-suppliers.csv",
  "total": {
    "amount": 648000000,
    "currency": "NGN"
  },
  "fee_total": {
    "amount": 193500,
    "currency": "NGN"
  },
  "counts": {
    "items": 36,
    "skipped": 2,
    "pending_approval": 36,
    "processing": 0,
    "completed": 0,
    "failed": 0,
    "canceled": 0
  },
  "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"
      }
    }
  ],
  "approval": {
    "id": "apr_01JCNR5YHCF05G59S2S1KKE59R",
    "object": "approval",
    "kind": "batch",
    "subject_id": "bat_01JCYFGCW8T7SWM4FV4DK79Q9G",
    "summary": "Pay 36 recipients ₦6,480,000.00 (october-suppliers.csv)",
    "amount": {
      "amount": 648000000,
      "currency": "NGN"
    },
    "status": "pending",
    "requested_by": {
      "type": "user",
      "id": "usr_01JCG0X454YG4GFDEXZR4YJ2C4",
      "name": "Ngozi Uche"
    },
    "requested_at": "2026-10-28T08:30:00Z",
    "expires_at": "2026-10-29T08:30:00Z"
  },
  "created_by": {
    "type": "user",
    "id": "usr_01JCG0X454YG4GFDEXZR4YJ2C4",
    "name": "Ngozi Uche"
  },
  "created_at": "2026-10-28T08:30:00Z",
  "updated_at": "2026-10-28T08:30:00Z"
}

{
  "id": "bat_01JCYFGCW8T7SWM4FV4DK79Q9G",
  "object": "batch",
  "status": "processing",
  "status_reason": "sending",
  "source_account": {
    "id": "acc_01JCWPQ5E6EYCNDY0YP57RCYBV",
    "name": "Naira · Main",
    "currency": "NGN",
    "account_number_last4": "6789"
  },
  "file_name": "october-suppliers.csv",
  "total": {
    "amount": 648000000,
    "currency": "NGN"
  },
  "fee_total": {
    "amount": 193500,
    "currency": "NGN"
  },
  "counts": {
    "items": 36,
    "skipped": 2,
    "pending_approval": 0,
    "processing": 36,
    "completed": 0,
    "failed": 0,
    "canceled": 0
  },
  "created_by": {
    "type": "user",
    "id": "usr_01JCMZ9J92V81E5128Q6RW31FZ",
    "name": "Adaeze Okafor"
  },
  "created_at": "2026-10-28T08:30:00Z",
  "updated_at": "2026-10-28T08:30: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": {}
  }
}

{
  "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": {}
  }
}

Batches

Create a batch

Creates a batch from the same input as POST /batches/validate and validates it again on the server. With skip_invalid_rows: true (what “Send 36 payments” does after the warning) invalid rows are recorded in skipped_rows and never paid; with false (the default) any invalid row fails the request with 422 batch_row_invalid and details.rows.

Step-up: a customer session must send X-Step-Up-Token (“Enter the 6-digit code … to send 36 payments totalling ₦6,480,000.00”).

One hold is placed for the total of the valid rows plus fees (422 insufficient_balance otherwise), and each valid row becomes a transfer with batch_id and batch_line. If the batch total is over the caller’s approval threshold the batch and all its transfers are pending_approval with one approval of kind batch (201); otherwise the batch is processing (202) and its transfers are sent. Each row then succeeds or fails on its own and fires its own payment.* webhooks. The batch is completed once every row is final, with status_reason: some_items_failed if any row failed.

Agent tokens can’t create batches (403 role_not_permitted).

Error codes: invalid_api_key, parameter_invalid, parameter_missing, resource_not_found, role_not_permitted, scope_missing, step_up_required, csrf_token_invalid, idempotency_key_reused, batch_row_invalid, insufficient_balance, bank_unavailable, business_frozen, business_not_approved, batch_too_large, limit_exceeded, rate_limited.

POST

batches

Create a batch

curl --request POST \
  --url https://api.panoflow.io/v1/batches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --form source_account_id=acc_01JCWPQ5E6EYCNDY0YP57RCYBV \
  --form skip_invalid_rows=true \
  --form 'reason=October supplier run' \
  --form '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
;type=text/csv'

const form = new FormData();
form.append('source_account_id', 'acc_01JCWPQ5E6EYCNDY0YP57RCYBV');
form.append('skip_invalid_rows', 'true');
form.append('reason', 'October supplier run');
form.append('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
');

const options = {
  method: 'POST',
  headers: {'Idempotency-Key': '<idempotency-key>', Authorization: 'Bearer <token>'}
};

options.body = form;

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

import requests

url = "https://api.panoflow.io/v1/batches"

files = {}
files["file"] = (None, "recipient_name,account_number,bank,amount_ngn,narration\nMusa Ibrahim,0213342210,GTBank,180000,Oct supplies\nNgozi Adeyemi,0119337731,GTBank,210000,Oct supplies\nZaria Haulage Co,0123454471,Access Bank,450000,Oct haulage\n", "text/csv")
payload = {
    "source_account_id": "acc_01JCWPQ5E6EYCNDY0YP57RCYBV",
    "skip_invalid_rows": "true",
    "reason": "October supplier run"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

{
  "id": "bat_01JCYFGCW8T7SWM4FV4DK79Q9G",
  "object": "batch",
  "status": "pending_approval",
  "status_reason": "awaiting_approval",
  "source_account": {
    "id": "acc_01JCWPQ5E6EYCNDY0YP57RCYBV",
    "name": "Naira · Main",
    "currency": "NGN",
    "account_number_last4": "6789"
  },
  "file_name": "october-suppliers.csv",
  "total": {
    "amount": 648000000,
    "currency": "NGN"
  },
  "fee_total": {
    "amount": 193500,
    "currency": "NGN"
  },
  "counts": {
    "items": 36,
    "skipped": 2,
    "pending_approval": 36,
    "processing": 0,
    "completed": 0,
    "failed": 0,
    "canceled": 0
  },
  "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"
      }
    }
  ],
  "approval": {
    "id": "apr_01JCNR5YHCF05G59S2S1KKE59R",
    "object": "approval",
    "kind": "batch",
    "subject_id": "bat_01JCYFGCW8T7SWM4FV4DK79Q9G",
    "summary": "Pay 36 recipients ₦6,480,000.00 (october-suppliers.csv)",
    "amount": {
      "amount": 648000000,
      "currency": "NGN"
    },
    "status": "pending",
    "requested_by": {
      "type": "user",
      "id": "usr_01JCG0X454YG4GFDEXZR4YJ2C4",
      "name": "Ngozi Uche"
    },
    "requested_at": "2026-10-28T08:30:00Z",
    "expires_at": "2026-10-29T08:30:00Z"
  },
  "created_by": {
    "type": "user",
    "id": "usr_01JCG0X454YG4GFDEXZR4YJ2C4",
    "name": "Ngozi Uche"
  },
  "created_at": "2026-10-28T08:30:00Z",
  "updated_at": "2026-10-28T08:30:00Z"
}

{
  "id": "bat_01JCYFGCW8T7SWM4FV4DK79Q9G",
  "object": "batch",
  "status": "processing",
  "status_reason": "sending",
  "source_account": {
    "id": "acc_01JCWPQ5E6EYCNDY0YP57RCYBV",
    "name": "Naira · Main",
    "currency": "NGN",
    "account_number_last4": "6789"
  },
  "file_name": "october-suppliers.csv",
  "total": {
    "amount": 648000000,
    "currency": "NGN"
  },
  "fee_total": {
    "amount": 193500,
    "currency": "NGN"
  },
  "counts": {
    "items": 36,
    "skipped": 2,
    "pending_approval": 0,
    "processing": 36,
    "completed": 0,
    "failed": 0,
    "canceled": 0
  },
  "created_by": {
    "type": "user",
    "id": "usr_01JCMZ9J92V81E5128Q6RW31FZ",
    "name": "Adaeze Okafor"
  },
  "created_at": "2026-10-28T08:30:00Z",
  "updated_at": "2026-10-28T08:30: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": {}
  }
}

{
  "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

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

Multipart body for validate and create with a CSV file.

file

string

required

The CSV, in the template format.

source_account_id

string

required

acc_… to pay from.

skip_invalid_rows

boolean

default:false

Create only. Skip invalid rows instead of failing the whole batch.

reason

string

Create only. Shown to the approver.

Maximum string length: 500

Response

Created and waiting for approval (pending_approval, with approval).

A Pay many batch. Its rows are transfers with batch_id.

string

required

bat_…

object

string

required

Always batch.

Allowed value: "batch"

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

source_account

object

required

Enough of a PanoFlow account to show it ("Naira · Main · ••••6789"). Full account in the Accounts API.

Show child attributes

total

object

required

Sum of the rows being paid.

Show child attributes

fee_total

object

required

Sum of the rows' fees.

Show child attributes

counts

object

required

How many of the batch's rows are in each state.

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 a batch's status. Clients must tolerate new values.

Available options:

awaiting_approval,

sending,

all_items_completed,

some_items_failed,

all_items_failed,

rejected_by_approver,

canceled_by_user,

approval_expired

file_name

string

File name, or "Pasted rows".

skipped_rows

object[]

Rows that were skipped and will never be paid. Returned on GET /batches/{id}; omitted in lists.

Show child attributes

approval

object

The batch's approval, when it needed one.

Show child attributes

reason

string

Why it was made (shown to the approver).

completed_at

string<date-time>

When the last row became final.

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 batch

Authorizations

Headers

Body

Response