rexedge/paystack-payment-requests

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&currency=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",
});