Validate a batch file or rows

curl --request POST \
  --url https://api.panoflow.io/v1/batches/validate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form source_account_id=acc_01JCWPQ5E6EYCNDY0YP57RCYBV \
  --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('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: {Authorization: 'Bearer <token>'}};

options.body = form;

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

import requests

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

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" }
headers = {"Authorization": "Bearer <token>"}

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

print(response.text)

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

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

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.

POST

batches

validate

Validate a batch file or rows

curl --request POST \
  --url https://api.panoflow.io/v1/batches/validate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form source_account_id=acc_01JCWPQ5E6EYCNDY0YP57RCYBV \
  --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('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: {Authorization: 'Bearer <token>'}};

options.body = form;

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

import requests

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

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" }
headers = {"Authorization": "Bearer <token>"}

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

print(response.text)

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

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

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

The validation result.

Result of POST /batches/validate. Nothing is created.

object

string

required

Always batch_validation.

Allowed value: "batch_validation"

source_account

object

required

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

Show child attributes

row_count

integer

required

Rows read (excluding the header).

valid_count

integer

required

Rows that can be paid.

skipped_count

integer

required

Rows that will be skipped.

total

object

required

Sum of the valid rows.

Show child attributes

fee_total

object

required

Fees for the valid rows.

Show child attributes

available_after

object

required

Source available balance after total + fees ("Available after this batch"). Negative means it can't be covered.

Show child attributes

requires_approval

boolean

required

True when creating it will return pending_approval for this caller.

valid_rows

object[]

required

Rows that can be paid, in file order.

Show child attributes

skipped_rows

object[]

required

Rows that can't be paid, with reasons.

Show child attributes

file_name

string

As sent.

Accounts & transactions

Payments

Collections

Payroll

Approvals

Webhooks & events

OAuth

Validate a batch file or rows

Authorizations

Headers

Body

Response