Prepare a pay run

curl --request POST \
  --url https://api.panoflow.io/v1/payroll/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "period": "2026-11"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({period: '2026-11'})
};

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

import requests

url = "https://api.panoflow.io/v1/payroll/runs"

payload = { "period": "2026-11" }
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "id": "run_01JK31CZT5GEVQEZ2NTQSC0J4D",
  "object": "pay_run",
  "created_at": "2026-10-28T12:30:00Z",
  "updated_at": "2026-10-28T12:34:00Z",
  "period": "2026-11",
  "name": "November 2026 pay run",
  "pay_date": "2026-11-27",
  "approve_by": "2026-11-26T15:00:00Z",
  "status": "draft",
  "pay_timing": "pay_day",
  "narration": "Salary Nov 2026",
  "source_account": {
    "id": "acc_01JV4DK79Q9G8XE6SZAEAVSNTC",
    "name": "Naira · Payroll",
    "account_number": "8012457746"
  },
  "totals": {
    "people_count": 11,
    "gross": {
      "amount": 295000000,
      "currency": "NGN"
    },
    "bonuses": {
      "amount": 5000000,
      "currency": "NGN"
    },
    "deductions": {
      "amount": 60255000,
      "currency": "NGN"
    },
    "net": {
      "amount": 234745000,
      "currency": "NGN"
    }
  },
  "deductions_to_remit": [
    {
      "deduction_type_id": "ded_01J1JX4WHRDD459GQ8H7QEZZS1",
      "name": "PAYE (income tax)",
      "remits_to": "LIRS (Lagos), by the 10th",
      "amount": {
        "amount": 26200000,
        "currency": "NGN"
      }
    },
    {
      "deduction_type_id": "ded_01JA0ZWSK9TPRM7N0MNS7C0JGQ",
      "name": "Pension",
      "remits_to": "[Pension administrator]",
      "amount": {
        "amount": 23200000,
        "currency": "NGN"
      }
    },
    {
      "deduction_type_id": "ded_01J4SR4QVH3H63J9FHVMCQV1SD",
      "name": "National Housing Fund",
      "remits_to": "FMBN",
      "amount": {
        "amount": 855000,
        "currency": "NGN"
      }
    },
    {
      "deduction_type_id": "ded_01J53TW8JZ38AYTNJKGGSFKYS7",
      "name": "Staff loan",
      "amount": {
        "amount": 4000000,
        "currency": "NGN"
      }
    },
    {
      "deduction_type_id": "ded_01JAA4DZEWNWV8CF5BN5MFQGC1",
      "name": "Salary advance",
      "amount": {
        "amount": 3000000,
        "currency": "NGN"
      }
    },
    {
      "deduction_type_id": "ded_01JTRTDRHN3ZHQ8D5HFRSWVK18",
      "name": "Cooperative savings",
      "remits_to": "Adaeze Staff Cooperative",
      "amount": {
        "amount": 3000000,
        "currency": "NGN"
      }
    }
  ],
  "funding": {
    "available": {
      "amount": 354014000,
      "currency": "NGN"
    },
    "covered": true
  },
  "requires_second_approval": true,
  "second_approval_threshold": {
    "amount": 200000000,
    "currency": "NGN"
  },
  "approved_by": [],
  "prepared_by": {
    "type": "user",
    "id": "usr_01JNTH82F7AG3BCKKDJWBHP1G2",
    "name": "Adaeze Okafor"
  },
  "lines": [
    {
      "id": "pln_01J33BSWM75ANCBX2KRQNWA605",
      "object": "pay_run_line",
      "response_code": "09",
      "response_message": "Request processing in progress",
      "person": {
        "id": "ppl_01J9RMZ9J92V81E5128Q6RW31F",
        "name": "Musa Ibrahim",
        "role": "Fleet supervisor",
        "bank_name": "Access Bank",
        "account_number_last4": "1045"
      },
      "included": true,
      "status": "draft",
      "earnings": [
        {
          "type": "basic",
          "name": "Basic",
          "amount": {
            "amount": 18600000,
            "currency": "NGN"
          }
        },
        {
          "type": "housing",
          "name": "Housing",
          "amount": {
            "amount": 7750000,
            "currency": "NGN"
          }
        },
        {
          "type": "transport",
          "name": "Transport",
          "amount": {
            "amount": 4650000,
            "currency": "NGN"
          }
        }
      ],
      "bonus": {
        "amount": 5000000,
        "currency": "NGN"
      },
      "gross": {
        "amount": 36000000,
        "currency": "NGN"
      },
      "deductions": [
        {
          "deduction_type_id": "ded_01J1JX4WHRDD459GQ8H7QEZZS1",
          "name": "PAYE (income tax)",
          "short_name": "PAYE",
          "applies_to_everyone": true,
          "amount": {
            "amount": 3720000,
            "currency": "NGN"
          }
        },
        {
          "deduction_type_id": "ded_01JA0ZWSK9TPRM7N0MNS7C0JGQ",
          "name": "Pension",
          "short_name": "Pension",
          "applies_to_everyone": true,
          "amount": {
            "amount": 2480000,
            "currency": "NGN"
          }
        },
        {
          "deduction_type_id": "ded_01J53TW8JZ38AYTNJKGGSFKYS7",
          "person_deduction_id": "pdd_01J8GV764KCRGE00KXHMFYFF1T",
          "name": "Staff loan",
          "short_name": "Loan",
          "applies_to_everyone": false,
          "amount": {
            "amount": 2500000,
            "currency": "NGN"
          },
          "loan_remaining_after": {
            "amount": 5000000,
            "currency": "NGN"
          }
        }
      ],
      "deduction_total": {
        "amount": 8700000,
        "currency": "NGN"
      },
      "net": {
        "amount": 27300000,
        "currency": "NGN"
      }
    },
    {
      "id": "pln_01JH5PT7DRPKV53YCQWCMQY1TF",
      "object": "pay_run_line",
      "response_code": "21",
      "response_message": "No action taken",
      "person": {
        "id": "ppl_01J9NGK80Y3ZH6DZJJXXX7CK5Y",
        "name": "Ngozi Adeyemi",
        "role": "Operations assistant",
        "bank_name": "GTBank",
        "account_number_last4": "7731"
      },
      "included": false,
      "status": "draft",
      "earnings": [
        {
          "type": "basic",
          "name": "Basic",
          "amount": {
            "amount": 10200000,
            "currency": "NGN"
          }
        },
        {
          "type": "housing",
          "name": "Housing",
          "amount": {
            "amount": 4250000,
            "currency": "NGN"
          }
        },
        {
          "type": "transport",
          "name": "Transport",
          "amount": {
            "amount": 2550000,
            "currency": "NGN"
          }
        }
      ],
      "bonus": {
        "amount": 0,
        "currency": "NGN"
      },
      "gross": {
        "amount": 17000000,
        "currency": "NGN"
      },
      "deductions": [
        {
          "deduction_type_id": "ded_01J1JX4WHRDD459GQ8H7QEZZS1",
          "name": "PAYE (income tax)",
          "short_name": "PAYE",
          "applies_to_everyone": true,
          "amount": {
            "amount": 1275000,
            "currency": "NGN"
          }
        },
        {
          "deduction_type_id": "ded_01JA0ZWSK9TPRM7N0MNS7C0JGQ",
          "name": "Pension",
          "short_name": "Pension",
          "applies_to_everyone": true,
          "amount": {
            "amount": 1360000,
            "currency": "NGN"
          }
        }
      ],
      "deduction_total": {
        "amount": 2635000,
        "currency": "NGN"
      },
      "net": {
        "amount": 14365000,
        "currency": "NGN"
      }
    }
  ]
}

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

Pay runs

Prepare a pay run

Creates the draft run for period and computes one line per person who is active, on_leave (paid) or starting on or before the pay date. People starting after the pay date are not included; people whose start date falls in the period are included but included: false by default, so you decide. Lines use current pay items and enabled deductions; drafts are recomputed whenever those change.

A pay run creates a money-moving object, so Idempotency-Key is required. 409 duplicate_resource if a run for that period already exists and is not canceled.

Error codes: invalid_api_key, parameter_invalid, parameter_missing, scope_missing, csrf_token_invalid, idempotency_key_reused, duplicate_resource, schedule_in_past, net_pay_negative, rate_limited.

POST

payroll

runs

Prepare a pay run

curl --request POST \
  --url https://api.panoflow.io/v1/payroll/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "period": "2026-11"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({period: '2026-11'})
};

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

import requests

url = "https://api.panoflow.io/v1/payroll/runs"

payload = { "period": "2026-11" }
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "id": "run_01JK31CZT5GEVQEZ2NTQSC0J4D",
  "object": "pay_run",
  "created_at": "2026-10-28T12:30:00Z",
  "updated_at": "2026-10-28T12:34:00Z",
  "period": "2026-11",
  "name": "November 2026 pay run",
  "pay_date": "2026-11-27",
  "approve_by": "2026-11-26T15:00:00Z",
  "status": "draft",
  "pay_timing": "pay_day",
  "narration": "Salary Nov 2026",
  "source_account": {
    "id": "acc_01JV4DK79Q9G8XE6SZAEAVSNTC",
    "name": "Naira · Payroll",
    "account_number": "8012457746"
  },
  "totals": {
    "people_count": 11,
    "gross": {
      "amount": 295000000,
      "currency": "NGN"
    },
    "bonuses": {
      "amount": 5000000,
      "currency": "NGN"
    },
    "deductions": {
      "amount": 60255000,
      "currency": "NGN"
    },
    "net": {
      "amount": 234745000,
      "currency": "NGN"
    }
  },
  "deductions_to_remit": [
    {
      "deduction_type_id": "ded_01J1JX4WHRDD459GQ8H7QEZZS1",
      "name": "PAYE (income tax)",
      "remits_to": "LIRS (Lagos), by the 10th",
      "amount": {
        "amount": 26200000,
        "currency": "NGN"
      }
    },
    {
      "deduction_type_id": "ded_01JA0ZWSK9TPRM7N0MNS7C0JGQ",
      "name": "Pension",
      "remits_to": "[Pension administrator]",
      "amount": {
        "amount": 23200000,
        "currency": "NGN"
      }
    },
    {
      "deduction_type_id": "ded_01J4SR4QVH3H63J9FHVMCQV1SD",
      "name": "National Housing Fund",
      "remits_to": "FMBN",
      "amount": {
        "amount": 855000,
        "currency": "NGN"
      }
    },
    {
      "deduction_type_id": "ded_01J53TW8JZ38AYTNJKGGSFKYS7",
      "name": "Staff loan",
      "amount": {
        "amount": 4000000,
        "currency": "NGN"
      }
    },
    {
      "deduction_type_id": "ded_01JAA4DZEWNWV8CF5BN5MFQGC1",
      "name": "Salary advance",
      "amount": {
        "amount": 3000000,
        "currency": "NGN"
      }
    },
    {
      "deduction_type_id": "ded_01JTRTDRHN3ZHQ8D5HFRSWVK18",
      "name": "Cooperative savings",
      "remits_to": "Adaeze Staff Cooperative",
      "amount": {
        "amount": 3000000,
        "currency": "NGN"
      }
    }
  ],
  "funding": {
    "available": {
      "amount": 354014000,
      "currency": "NGN"
    },
    "covered": true
  },
  "requires_second_approval": true,
  "second_approval_threshold": {
    "amount": 200000000,
    "currency": "NGN"
  },
  "approved_by": [],
  "prepared_by": {
    "type": "user",
    "id": "usr_01JNTH82F7AG3BCKKDJWBHP1G2",
    "name": "Adaeze Okafor"
  },
  "lines": [
    {
      "id": "pln_01J33BSWM75ANCBX2KRQNWA605",
      "object": "pay_run_line",
      "response_code": "09",
      "response_message": "Request processing in progress",
      "person": {
        "id": "ppl_01J9RMZ9J92V81E5128Q6RW31F",
        "name": "Musa Ibrahim",
        "role": "Fleet supervisor",
        "bank_name": "Access Bank",
        "account_number_last4": "1045"
      },
      "included": true,
      "status": "draft",
      "earnings": [
        {
          "type": "basic",
          "name": "Basic",
          "amount": {
            "amount": 18600000,
            "currency": "NGN"
          }
        },
        {
          "type": "housing",
          "name": "Housing",
          "amount": {
            "amount": 7750000,
            "currency": "NGN"
          }
        },
        {
          "type": "transport",
          "name": "Transport",
          "amount": {
            "amount": 4650000,
            "currency": "NGN"
          }
        }
      ],
      "bonus": {
        "amount": 5000000,
        "currency": "NGN"
      },
      "gross": {
        "amount": 36000000,
        "currency": "NGN"
      },
      "deductions": [
        {
          "deduction_type_id": "ded_01J1JX4WHRDD459GQ8H7QEZZS1",
          "name": "PAYE (income tax)",
          "short_name": "PAYE",
          "applies_to_everyone": true,
          "amount": {
            "amount": 3720000,
            "currency": "NGN"
          }
        },
        {
          "deduction_type_id": "ded_01JA0ZWSK9TPRM7N0MNS7C0JGQ",
          "name": "Pension",
          "short_name": "Pension",
          "applies_to_everyone": true,
          "amount": {
            "amount": 2480000,
            "currency": "NGN"
          }
        },
        {
          "deduction_type_id": "ded_01J53TW8JZ38AYTNJKGGSFKYS7",
          "person_deduction_id": "pdd_01J8GV764KCRGE00KXHMFYFF1T",
          "name": "Staff loan",
          "short_name": "Loan",
          "applies_to_everyone": false,
          "amount": {
            "amount": 2500000,
            "currency": "NGN"
          },
          "loan_remaining_after": {
            "amount": 5000000,
            "currency": "NGN"
          }
        }
      ],
      "deduction_total": {
        "amount": 8700000,
        "currency": "NGN"
      },
      "net": {
        "amount": 27300000,
        "currency": "NGN"
      }
    },
    {
      "id": "pln_01JH5PT7DRPKV53YCQWCMQY1TF",
      "object": "pay_run_line",
      "response_code": "21",
      "response_message": "No action taken",
      "person": {
        "id": "ppl_01J9NGK80Y3ZH6DZJJXXX7CK5Y",
        "name": "Ngozi Adeyemi",
        "role": "Operations assistant",
        "bank_name": "GTBank",
        "account_number_last4": "7731"
      },
      "included": false,
      "status": "draft",
      "earnings": [
        {
          "type": "basic",
          "name": "Basic",
          "amount": {
            "amount": 10200000,
            "currency": "NGN"
          }
        },
        {
          "type": "housing",
          "name": "Housing",
          "amount": {
            "amount": 4250000,
            "currency": "NGN"
          }
        },
        {
          "type": "transport",
          "name": "Transport",
          "amount": {
            "amount": 2550000,
            "currency": "NGN"
          }
        }
      ],
      "bonus": {
        "amount": 0,
        "currency": "NGN"
      },
      "gross": {
        "amount": 17000000,
        "currency": "NGN"
      },
      "deductions": [
        {
          "deduction_type_id": "ded_01J1JX4WHRDD459GQ8H7QEZZS1",
          "name": "PAYE (income tax)",
          "short_name": "PAYE",
          "applies_to_everyone": true,
          "amount": {
            "amount": 1275000,
            "currency": "NGN"
          }
        },
        {
          "deduction_type_id": "ded_01JA0ZWSK9TPRM7N0MNS7C0JGQ",
          "name": "Pension",
          "short_name": "Pension",
          "applies_to_everyone": true,
          "amount": {
            "amount": 1360000,
            "currency": "NGN"
          }
        }
      ],
      "deduction_total": {
        "amount": 2635000,
        "currency": "NGN"
      },
      "net": {
        "amount": 14365000,
        "currency": "NGN"
      }
    }
  ]
}

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

period

string

required

Pay month, YYYY-MM.

Pattern: ^\d{4}-\d{2}$

pay_date

string<date>

Overrides the date from settings for this run. Must be a working day in period, not in the past.

Example:

"2026-11-07"

Response

The draft run with its lines.

A month's pay run (run_…).

string

required

run_…

object

string

required

Always pay_run.

Allowed value: "pay_run"

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"

period

string

required

Pay month.

Pattern: ^\d{4}-\d{2}$

name

string

required

"November 2026 pay run".

pay_date

string<date>

required

Calendar date, interpreted in Africa/Lagos.

Example:

"2026-11-07"

status

enum<string>

required

CONVENTIONS §8 lifecycle: draft → pending_approval (second approver) → scheduled (waits for pay day) → processing → completed | failed; rejected by the second approver; canceled from draft, pending_approval or scheduled. UI: completed → "Paid". Pay runs are never reversed.

Available options:

draft,

pending_approval,

scheduled,

processing,

completed,

failed,

rejected,

canceled,

reversed

pay_timing

enum<string>

required

pay_day: pays on pay_date once approved. now: pays as soon as it is fully approved.

Available options:

pay_day,

now

narration

string

required

Narration on every salary transfer ("Salary Nov 2026").

source_account

object

required

One of the business's own PanoFlow accounts (owned by the Accounts service).

Show child attributes

totals

object

required

Totals over included lines. gross − deductions = net, always.

Show child attributes

requires_second_approval

boolean

required

Net is above second_approval_threshold.

approve_by

string<date-time>

Approve by this time to pay on pay_date ("26 Nov, 4pm").

Example:

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

status_reason

enum<string>

Sub-state.

Available options:

awaiting_second_approval,

awaiting_pay_day,

awaiting_execution,

changed_after_approval,

some_lines_failed,

rejected_by_approver

deductions_to_remit

object[]

Deduction totals by type, with where each goes. Stays in the source account; PanoFlow does not remit them.

Show child attributes

funding

object

Whether the source account covers the run, worked out at read time. Absent once executing.

Show child attributes

second_approval_threshold

object

An amount in minor units (kobo, cents) with its currency. Never a decimal.

Show child attributes

approval

object

The pending or decided approval (kind is pay_run), when one was needed.

Show child attributes

approved_by

object[]

Everyone who approved, in order ("Approved by Adaeze Okafor and Tolu Martins").

Show child attributes

prepared_by

object

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

Show child attributes

executed_at

string<date-time>

RFC 3339, UTC.

Example:

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

completed_at

string<date-time>

RFC 3339, UTC.

Example:

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

lines

object[]

One per person. Returned by getPayRun and run actions; omitted from lists.

Show child attributes

Accounts & transactions

Payments

Collections

Payroll

Approvals

Webhooks & events

OAuth

Prepare a pay run

Authorizations

Headers

Body

Response