rexedge Paystack Payment Requests
The Payment Requests API lets you create and manage invoices for goods and services.
Depends on: paystack-setup for the
paystackRequesthelper.
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",
});