Paystack Payment Requests
The Payment Requests API lets you create and manage invoices for goods and services.
Depends on: paystack-setup for the paystackRequest helper. Related: paystack-customers for customer codes used in requests.Endpoints
| Method | Endpoint | Description |
|---|---|---|
| POST | /paymentrequest | Create a payment request |
| GET | /paymentrequest | List payment requests |
| GET | /paymentrequest/:id_or_code | Fetch a payment request |
| PUT | /paymentrequest/:id_or_code | Update a payment request |
| GET | /paymentrequest/verify/:code | Verify a payment request |
| POST | /paymentrequest/notify/:code | Send notification |
| GET | /paymentrequest/totals | Get totals/metrics |
| POST | /paymentrequest/finalize/:code | Finalize a draft |
| POST | /paymentrequest/archive/:code | Archive a request |
Create Payment Request
| Param | Type | Required | Description |
|---|---|---|---|
customer | string | Yes | Customer ID or code |
amount | integer | No | Amount in subunits (if no line items) |
due_date | datetime | No | ISO 8601 due date |
description | string | No | Short description |
line_items | array | No | [{name, amount, quantity?}] |
tax | array | No | [{name, amount}] |
currency | string | No | Currency code (default: NGN) |
send_notification | boolean | No | Send email (default: true) |
draft | boolean | No | Save as draft (default: false) |
has_invoice | boolean | No | Add auto-incrementing invoice number |
invoice_number | integer | No | Override invoice number |
split_code | string | No | Split code for revenue sharing |
// Invoice with line items and tax
const invoice = await paystackRequest<{
id: number;
request_code: string;
invoice_number: number;
}>("/paymentrequest", {
method: "POST",
body: JSON.stringify({
customer: "CUS_xwaj0txjryg393b",
description: "Q1 2024 Services",
due_date: "2024-03-31",
line_items: [
{ name: "Consulting (10 hours)", amount: 500000, quantity: 1 },
{ name: "Design work", amount: 200000, quantity: 1 },
],
tax: [
{ name: "VAT (7.5%)", amount: 52500 },
],
send_notification: true,
has_invoice: true,
}),
});
// invoice.data.request_code → "PRQ_1weqqsn2wwzgft8"
// Draft invoice (no notification sent)
await paystackRequest("/paymentrequest", {
method: "POST",
body: JSON.stringify({
customer: "CUS_xwaj0txjryg393b",
amount: 100000,
description: "Draft invoice",
draft: true,
}),
});List Payment Requests
const requests = await paystackRequest(
"/paymentrequest?status=pending¤cy=NGN&perPage=20"
);Fetch / Verify
// Fetch
const req = await paystackRequest(`/paymentrequest/${encodeURIComponent("PRQ_code")}`);
// Verify (includes payment status)
const verified = await paystackRequest(
`/paymentrequest/verify/${encodeURIComponent("PRQ_code")}`
);Send Notification
Re-send the payment request email to the customer:
await paystackRequest(`/paymentrequest/notify/${encodeURIComponent("PRQ_code")}`, {
method: "POST",
});Get Totals
const totals = await paystackRequest("/paymentrequest/totals");
// totals.data.pending → [{ currency: "NGN", amount: 42000 }]
// totals.data.successful → [{ currency: "NGN", amount: 0 }]
// totals.data.total → [{ currency: "NGN", amount: 42000 }]Finalize Draft
await paystackRequest(`/paymentrequest/finalize/${encodeURIComponent("PRQ_code")}`, {
method: "POST",
body: JSON.stringify({ send_notification: true }),
});Update Payment Request
await paystackRequest(`/paymentrequest/${encodeURIComponent("PRQ_code")}`, {
method: "PUT",
body: JSON.stringify({
customer: "CUS_xwaj0txjryg393b",
description: "Updated invoice",
due_date: "2024-06-30",
amount: 150000,
}),
});Archive
await paystackRequest(`/paymentrequest/archive/${encodeURIComponent("PRQ_code")}`, {
method: "POST",
});