curl --request POST \
  --url https://api.panoflow.io/v1/scheduled-payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "name": "Warehouse rent",
  "recipient_id": "rcp_01JCQY77ZXYYK596NGYA1DQ91K",
  "source_account_id": "acc_01JCWPQ5E6EYCNDY0YP57RCYBV",
  "amount": {
    "amount": 275000000,
    "currency": "NGN"
  },
  "narration": "Warehouse rent",
  "schedule": {
    "frequency": "monthly",
    "interval": 3,
    "day_of_month": 1,
    "start_on": "2027-01-01"
  }
}
'

{
  "id": "sch_01JC8XE6SZAEAVSNTCPM5Q1NXW",
  "object": "scheduled_payment",
  "name": "Warehouse rent",
  "status": "active",
  "recipient_id": "rcp_01JCQY77ZXYYK596NGYA1DQ91K",
  "counterparty_name": "Garki Properties",
  "bank_account": {
    "account_number": "0021345516",
    "bank_code": "221",
    "bank_name": "Stanbic IBTC",
    "account_name": "GARKI PROPERTIES LTD"
  },
  "source_account": {
    "id": "acc_01JCWPQ5E6EYCNDY0YP57RCYBV",
    "name": "Naira · Main",
    "currency": "NGN",
    "account_number_last4": "6789"
  },
  "amount": {
    "amount": 275000000,
    "currency": "NGN"
  },
  "narration": "Warehouse rent",
  "schedule": {
    "frequency": "monthly",
    "interval": 3,
    "day_of_month": 1,
    "start_on": "2027-01-01"
  },
  "schedule_description": "Every 3 months",
  "next_run_on": "2027-01-01",
  "next_transfer_id": "trf_01JCNPZX45HY43KWJRP1XPA7Z3",
  "run_count": 0,
  "created_by": {
    "type": "user",
    "id": "usr_01JCMZ9J92V81E5128Q6RW31FZ",
    "name": "Adaeze Okafor"
  },
  "created_at": "2026-10-28T08:40:00Z",
  "updated_at": "2026-10-28T08:40: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": {}
  }
}

Scheduled payments

Schedule a payment

A payment to a saved recipient that runs once on a future date (frequency: once) or repeats. Step-up for customer sessions, like any payout.

The next run always exists as a transfer with status: scheduled (next_transfer_id), so it shows in Transactions and can be skipped. On its date (08:00 Africa/Lagos) that transfer goes through the same checks as POST /transfers — balance, limits, risk, approval threshold — and then becomes processing, pending_approval, or failed (failure.code: insufficient_balance when the balance doesn’t cover it: “Scheduled payments leave on their date if the balance covers them”). The following run is then scheduled. The business is emailed the day before each run (Notifications).

422 schedule_in_past if the first run date is not in the future.

Error codes: invalid_api_key, parameter_invalid, parameter_missing, resource_not_found, scope_missing, step_up_required, csrf_token_invalid, idempotency_key_reused, schedule_in_past, business_frozen, business_not_approved, rate_limited.

POST

scheduled-payments

curl --request POST \
  --url https://api.panoflow.io/v1/scheduled-payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "name": "Warehouse rent",
  "recipient_id": "rcp_01JCQY77ZXYYK596NGYA1DQ91K",
  "source_account_id": "acc_01JCWPQ5E6EYCNDY0YP57RCYBV",
  "amount": {
    "amount": 275000000,
    "currency": "NGN"
  },
  "narration": "Warehouse rent",
  "schedule": {
    "frequency": "monthly",
    "interval": 3,
    "day_of_month": 1,
    "start_on": "2027-01-01"
  }
}
'

{
  "id": "sch_01JC8XE6SZAEAVSNTCPM5Q1NXW",
  "object": "scheduled_payment",
  "name": "Warehouse rent",
  "status": "active",
  "recipient_id": "rcp_01JCQY77ZXYYK596NGYA1DQ91K",
  "counterparty_name": "Garki Properties",
  "bank_account": {
    "account_number": "0021345516",
    "bank_code": "221",
    "bank_name": "Stanbic IBTC",
    "account_name": "GARKI PROPERTIES LTD"
  },
  "source_account": {
    "id": "acc_01JCWPQ5E6EYCNDY0YP57RCYBV",
    "name": "Naira · Main",
    "currency": "NGN",
    "account_number_last4": "6789"
  },
  "amount": {
    "amount": 275000000,
    "currency": "NGN"
  },
  "narration": "Warehouse rent",
  "schedule": {
    "frequency": "monthly",
    "interval": 3,
    "day_of_month": 1,
    "start_on": "2027-01-01"
  },
  "schedule_description": "Every 3 months",
  "next_run_on": "2027-01-01",
  "next_transfer_id": "trf_01JCNPZX45HY43KWJRP1XPA7Z3",
  "run_count": 0,
  "created_by": {
    "type": "user",
    "id": "usr_01JCMZ9J92V81E5128Q6RW31FZ",
    "name": "Adaeze Okafor"
  },
  "created_at": "2026-10-28T08:40:00Z",
  "updated_at": "2026-10-28T08:40: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": {}
  }
}

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

application/json

name

string

required

Display name.

Maximum string length: 80

recipient_id

string

required

rcp_…, a saved active recipient.

source_account_id

string

required

acc_… to pay from.

amount

object

required

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

Show child attributes

schedule

object

required

When it runs. Examples: "Every Monday" = weekly, day_of_week: monday; "Monthly, on the 28th" = monthly, day_of_month: 28; "Every 3 months" = monthly, interval: 3. Runs at 08:00 Africa/Lagos. A day_of_month past the end of a month runs on the month's last day.

Show child attributes

narration

string

Narration on every run.

Maximum string length: 60

metadata

object

Up to 20 string keys (≤ 40 chars) with string values (≤ 500 chars). Returned on the resource and its events.

Show child attributes

Response

Scheduled.

A payment to a saved recipient on a schedule.

string

required

sch_…

object

string

required

Always scheduled_payment.

Allowed value: "scheduled_payment"

name

string

required

e.g. "Warehouse rent".

Maximum string length: 80

status

enum<string>

required

State of the schedule itself (its runs are transfers with MovementStatus). completed when a once schedule has run or end_on has passed.

Available options:

active,

paused,

canceled,

completed

recipient_id

string

required

rcp_…

source_account

object

required

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

Show child attributes

amount

object

required

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

Show child attributes

schedule

object

required

Show child attributes

schedule_description

string

required

Human text, e.g. "Every 3 months", "Every Monday", "Monthly, on the 28th".

run_count

integer

required

Runs so far.

Required range: x >= 0

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"

counterparty_name

string

The recipient's display name.

bank_account

object

The recipient's account.

Show child attributes

narration

string

Narration on every run.

next_run_on

string<date>

Next run date. Omitted when paused, canceled or completed.

Example:

"2026-11-07"

next_transfer_id

string

The scheduled transfer for the next run.

last_run

object

The most recent run, with its transfer's ISO 8583 outcome (ResponseOutcome).

Show child attributes

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

Schedule a payment

Authorizations

Headers

Body

Response