curl --request POST \
--url http://localhost:3001/api/v1/business/payouts/schedules \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"payload": {
"items": [
{
"currency": "<string>",
"recipientId": "<string>",
"srcAmount": "50.00",
"dstAmount": "50000",
"reference": "<string>"
}
]
},
"dayOfMonth": 14.5,
"maxRunAmountUsd": 50000,
"endAt": "<string>",
"pin": "<string>",
"metadata": {},
"maxRunLocalCaps": [
{
"currency": "NGN",
"amount": "20000000"
}
]
}
'import requests
url = "http://localhost:3001/api/v1/business/payouts/schedules"
payload = {
"name": "<string>",
"payload": { "items": [
{
"currency": "<string>",
"recipientId": "<string>",
"srcAmount": "50.00",
"dstAmount": "50000",
"reference": "<string>"
}
] },
"dayOfMonth": 14.5,
"maxRunAmountUsd": 50000,
"endAt": "<string>",
"pin": "<string>",
"metadata": {},
"maxRunLocalCaps": [
{
"currency": "NGN",
"amount": "20000000"
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
payload: {
items: [
{
currency: '<string>',
recipientId: '<string>',
srcAmount: '50.00',
dstAmount: '50000',
reference: '<string>'
}
]
},
dayOfMonth: 14.5,
maxRunAmountUsd: 50000,
endAt: '<string>',
pin: '<string>',
metadata: {},
maxRunLocalCaps: [{currency: 'NGN', amount: '20000000'}]
})
};
fetch('http://localhost:3001/api/v1/business/payouts/schedules', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_PORT => "3001",
CURLOPT_URL => "http://localhost:3001/api/v1/business/payouts/schedules",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'payload' => [
'items' => [
[
'currency' => '<string>',
'recipientId' => '<string>',
'srcAmount' => '50.00',
'dstAmount' => '50000',
'reference' => '<string>'
]
]
],
'dayOfMonth' => 14.5,
'maxRunAmountUsd' => 50000,
'endAt' => '<string>',
'pin' => '<string>',
'metadata' => [
],
'maxRunLocalCaps' => [
[
'currency' => 'NGN',
'amount' => '20000000'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://localhost:3001/api/v1/business/payouts/schedules"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"payload\": {\n \"items\": [\n {\n \"currency\": \"<string>\",\n \"recipientId\": \"<string>\",\n \"srcAmount\": \"50.00\",\n \"dstAmount\": \"50000\",\n \"reference\": \"<string>\"\n }\n ]\n },\n \"dayOfMonth\": 14.5,\n \"maxRunAmountUsd\": 50000,\n \"endAt\": \"<string>\",\n \"pin\": \"<string>\",\n \"metadata\": {},\n \"maxRunLocalCaps\": [\n {\n \"currency\": \"NGN\",\n \"amount\": \"20000000\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://localhost:3001/api/v1/business/payouts/schedules")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"payload\": {\n \"items\": [\n {\n \"currency\": \"<string>\",\n \"recipientId\": \"<string>\",\n \"srcAmount\": \"50.00\",\n \"dstAmount\": \"50000\",\n \"reference\": \"<string>\"\n }\n ]\n },\n \"dayOfMonth\": 14.5,\n \"maxRunAmountUsd\": 50000,\n \"endAt\": \"<string>\",\n \"pin\": \"<string>\",\n \"metadata\": {},\n \"maxRunLocalCaps\": [\n {\n \"currency\": \"NGN\",\n \"amount\": \"20000000\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://localhost:3001/api/v1/business/payouts/schedules")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"payload\": {\n \"items\": [\n {\n \"currency\": \"<string>\",\n \"recipientId\": \"<string>\",\n \"srcAmount\": \"50.00\",\n \"dstAmount\": \"50000\",\n \"reference\": \"<string>\"\n }\n ]\n },\n \"dayOfMonth\": 14.5,\n \"maxRunAmountUsd\": 50000,\n \"endAt\": \"<string>\",\n \"pin\": \"<string>\",\n \"metadata\": {},\n \"maxRunLocalCaps\": [\n {\n \"currency\": \"NGN\",\n \"amount\": \"20000000\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"id": "<string>",
"businessId": "<string>",
"name": "<string>",
"itemCount": 123,
"nextRunAt": "<string>",
"runCount": 123,
"maxRunAmountUsd": "<string>",
"authorizedAt": "<string>",
"createdAt": "<string>",
"updatedAt": "<string>",
"dayOfMonth": {},
"lastRunAt": {},
"endAt": {},
"maxRunLocalCaps": [
{
"currency": "NGN",
"amount": "20000000"
}
]
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "email must be an email",
"statusCode": 400,
"errors": {}
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "email must be an email",
"statusCode": 400,
"errors": {}
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "email must be an email",
"statusCode": 400,
"errors": {}
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "email must be an email",
"statusCode": 400,
"errors": {}
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "email must be an email",
"statusCode": 400,
"errors": {}
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "email must be an email",
"statusCode": 400,
"errors": {}
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "email must be an email",
"statusCode": 400,
"errors": {}
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "email must be an email",
"statusCode": 400,
"errors": {}
}
}Create + authorize a scheduled payout
Validates the cadence (MONTHLY day-of-month 1–28, optional) and the per-run USD cap (defaults to 50k,rejectedabovethe250k admin ceiling), sanctions-screens every recipient in the payload, verifies the transaction PIN on the dashboard path (api-key exempt), stamps authorizedAt/By, and computes the first nextRunAt. Unattended runs execute without re-authorization, bounded by maxRunAmountUsd.
curl --request POST \
--url http://localhost:3001/api/v1/business/payouts/schedules \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"payload": {
"items": [
{
"currency": "<string>",
"recipientId": "<string>",
"srcAmount": "50.00",
"dstAmount": "50000",
"reference": "<string>"
}
]
},
"dayOfMonth": 14.5,
"maxRunAmountUsd": 50000,
"endAt": "<string>",
"pin": "<string>",
"metadata": {},
"maxRunLocalCaps": [
{
"currency": "NGN",
"amount": "20000000"
}
]
}
'import requests
url = "http://localhost:3001/api/v1/business/payouts/schedules"
payload = {
"name": "<string>",
"payload": { "items": [
{
"currency": "<string>",
"recipientId": "<string>",
"srcAmount": "50.00",
"dstAmount": "50000",
"reference": "<string>"
}
] },
"dayOfMonth": 14.5,
"maxRunAmountUsd": 50000,
"endAt": "<string>",
"pin": "<string>",
"metadata": {},
"maxRunLocalCaps": [
{
"currency": "NGN",
"amount": "20000000"
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
payload: {
items: [
{
currency: '<string>',
recipientId: '<string>',
srcAmount: '50.00',
dstAmount: '50000',
reference: '<string>'
}
]
},
dayOfMonth: 14.5,
maxRunAmountUsd: 50000,
endAt: '<string>',
pin: '<string>',
metadata: {},
maxRunLocalCaps: [{currency: 'NGN', amount: '20000000'}]
})
};
fetch('http://localhost:3001/api/v1/business/payouts/schedules', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_PORT => "3001",
CURLOPT_URL => "http://localhost:3001/api/v1/business/payouts/schedules",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'payload' => [
'items' => [
[
'currency' => '<string>',
'recipientId' => '<string>',
'srcAmount' => '50.00',
'dstAmount' => '50000',
'reference' => '<string>'
]
]
],
'dayOfMonth' => 14.5,
'maxRunAmountUsd' => 50000,
'endAt' => '<string>',
'pin' => '<string>',
'metadata' => [
],
'maxRunLocalCaps' => [
[
'currency' => 'NGN',
'amount' => '20000000'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://localhost:3001/api/v1/business/payouts/schedules"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"payload\": {\n \"items\": [\n {\n \"currency\": \"<string>\",\n \"recipientId\": \"<string>\",\n \"srcAmount\": \"50.00\",\n \"dstAmount\": \"50000\",\n \"reference\": \"<string>\"\n }\n ]\n },\n \"dayOfMonth\": 14.5,\n \"maxRunAmountUsd\": 50000,\n \"endAt\": \"<string>\",\n \"pin\": \"<string>\",\n \"metadata\": {},\n \"maxRunLocalCaps\": [\n {\n \"currency\": \"NGN\",\n \"amount\": \"20000000\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://localhost:3001/api/v1/business/payouts/schedules")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"payload\": {\n \"items\": [\n {\n \"currency\": \"<string>\",\n \"recipientId\": \"<string>\",\n \"srcAmount\": \"50.00\",\n \"dstAmount\": \"50000\",\n \"reference\": \"<string>\"\n }\n ]\n },\n \"dayOfMonth\": 14.5,\n \"maxRunAmountUsd\": 50000,\n \"endAt\": \"<string>\",\n \"pin\": \"<string>\",\n \"metadata\": {},\n \"maxRunLocalCaps\": [\n {\n \"currency\": \"NGN\",\n \"amount\": \"20000000\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://localhost:3001/api/v1/business/payouts/schedules")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"payload\": {\n \"items\": [\n {\n \"currency\": \"<string>\",\n \"recipientId\": \"<string>\",\n \"srcAmount\": \"50.00\",\n \"dstAmount\": \"50000\",\n \"reference\": \"<string>\"\n }\n ]\n },\n \"dayOfMonth\": 14.5,\n \"maxRunAmountUsd\": 50000,\n \"endAt\": \"<string>\",\n \"pin\": \"<string>\",\n \"metadata\": {},\n \"maxRunLocalCaps\": [\n {\n \"currency\": \"NGN\",\n \"amount\": \"20000000\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"id": "<string>",
"businessId": "<string>",
"name": "<string>",
"itemCount": 123,
"nextRunAt": "<string>",
"runCount": 123,
"maxRunAmountUsd": "<string>",
"authorizedAt": "<string>",
"createdAt": "<string>",
"updatedAt": "<string>",
"dayOfMonth": {},
"lastRunAt": {},
"endAt": {},
"maxRunLocalCaps": [
{
"currency": "NGN",
"amount": "20000000"
}
]
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "email must be an email",
"statusCode": 400,
"errors": {}
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "email must be an email",
"statusCode": 400,
"errors": {}
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "email must be an email",
"statusCode": 400,
"errors": {}
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "email must be an email",
"statusCode": 400,
"errors": {}
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "email must be an email",
"statusCode": 400,
"errors": {}
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "email must be an email",
"statusCode": 400,
"errors": {}
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "email must be an email",
"statusCode": 400,
"errors": {}
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "email must be an email",
"statusCode": 400,
"errors": {}
}
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Active business context
Merchant API key (alternative to dashboard JWT)
Body
Human label, e.g. "Monthly payroll".
1 - 120ONCE | WEEKLY | BIWEEKLY | MONTHLY.
ONCE, WEEKLY, BIWEEKLY, MONTHLY SINGLE | BATCH.
SINGLE, BATCH The frozen payout spec.
Show child attributes
Show child attributes
MONTHLY only: day-of-month (1–28) to fire on. Absent → the creation day-of-month. Ignored for other cadences.
1 <= x <= 28Per-run USD cap (compliance). Defaults to SCHEDULE_RUN_USD_DEFAULT ($50k); rejected if above the SCHEDULE_RUN_USD_CEILING admin cap ($250k).
50000
Optional natural end. After this instant the schedule auto-completes.
Transaction PIN, required on the dashboard path to authorize the schedule (verified server-side). Not required on the api-key path. Future runs execute automatically.
Optional caller metadata persisted on the schedule.
Optional per-currency caps for locally-denominated runs. A currency listed here is checked against the run total in that currency and is immune to FX movement; every other currency still falls under maxRunAmountUsd. Omit for USD-only capping (the existing behaviour).
Show child attributes
Show child attributes
