Payment Request
A collection of endpoints for managing invoices for the payment of goods and services
Copy link List Payment Request
List all previously created payment requests to your customers
Query Parameters
Number of records to fetch per page
The section to retrieve
Customer ID
Invoice status to filter
Enumdraftpendingsuccessfailed
If your integration supports more than one currency, choose the one to filter
The start date
The end date
Response
200Payment Request List response
5 object properties
GET
/paymentrequestcurl https://api.paystack.co/paymentrequest \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.paymentRequest.list({
perPage: 100,
page: 100
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.payment_request.list({
per_page: 100,
page: 100
})
puts response.dataResponse
{
"status": true,
"message": "Payment requests retrieved",
"data": [
{
"id": 3136406,
"domain": "test",
"amount": 42000,
"currency": "NGN",
"due_date": "2020-07-08T00:00:00.000Z",
"has_invoice": true,
"invoice_number": 1,
"description": "a test invoice",
"pdf_url": null,
"line_items": [
{
"name": "item 1",
"amount": 20000
},
{
"name": "item 2",
"amount": 20000
}
],
"tax": [
{
"name": "VAT",
"amount": 2000
}
],
"request_code": "PRQ_1weqqsn2wwzgft8",
"status": "pending",
"paid": false,
"paid_at": null,
"metadata": null,
"notifications": [],
"offline_reference": "4286263136406",
"customer": {
"id": 25833615,
"first_name": "Damilola",
"last_name": "Odujoko",
"email": "[email protected]",
"customer_code": "CUS_xwaj0txjryg393b",
"phone": null,
"metadata": {
"calling_code": "+234"
},
"risk_action": "default",
"international_format_phone": null
},
"created_at": "2020-06-29T16:07:33.000Z"
}
],
"meta": {
"total": 1,
"skipped": 0,
"perPage": 50,
"page": 1,
"pageCount": 1
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Create Payment Request
Create a new payment request by issuing an invoice to a customer
Request Body
Customer id or code
Payment request amount. Only useful if line items and tax values are ignored.
The endpoint will throw a friendly warning if neither is available.
Specify the currency of the invoice. Allowed values are NGN, GHS, ZAR and USD. Defaults to NGN
Specify a URL for Paystack to redirect to on a successful payment
ISO 8601 representation of request due date
A short description of the payment request
Array of line items
Array of taxes
Indicates whether Paystack sends an email notification to customer. Defaults to true
Indicate if request should be saved as draft. Defaults to false and overrides send_notification
Set to true to create a draft invoice (adds an auto incrementing invoice number if none is provided) even if there are no line_items or tax passed
Numeric value of invoice. Invoice will start from 1 and auto increment from there. This field is to help override whatever value Paystack decides. Auto increment for subsequent invoices continue from this point.
The split code of the transaction split.
Response
200Payment Request Create response
21 object properties
POST
/paymentrequestcurl https://api.paystack.co/paymentrequest \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"customer": "CUS_xqp6o5oja5cackf",
"amount": 10000
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.paymentRequest.create({
customer: "CUS_xqp6o5oja5cackf",
amount: 10000
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.payment_request.create({
customer: "CUS_xqp6o5oja5cackf",
amount: 10000
})
puts response.dataResponse
{
"status": true,
"message": "Payment request created",
"data": {
"id": 3136406,
"domain": "test",
"amount": 42000,
"currency": "NGN",
"due_date": "2020-07-08T00:00:00.000Z",
"has_invoice": true,
"invoice_number": 1,
"description": "a test invoice",
"line_items": [
{
"name": "item 1",
"amount": 20000
},
{
"name": "item 2",
"amount": 20000
}
],
"tax": [
{
"name": "VAT",
"amount": 2000
}
],
"request_code": "PRQ_1weqqsn2wwzgft8",
"status": "pending",
"paid": false,
"metadata": null,
"notifications": [],
"offline_reference": "4286263136406",
"customer": 25833615,
"created_at": "2020-06-29T16:07:33.073Z"
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Fetch Payment Request
Fetch a previously created payment request
Path Parameters
The unique identifier of a previously created payment request
Response
200Payment Request List response
5 object properties
GET
/paymentrequest/{id}curl https://api.paystack.co/paymentrequest/18823736 \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.paymentRequest.fetch("18823736");
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.payment_request.fetch("18823736")
puts response.dataResponse
{
"status": true,
"message": "Payment request retrieved",
"data": {
"transactions": [],
"domain": "test",
"request_code": "PRQ_1weqqsn2wwzgft8",
"description": "a test invoice",
"line_items": [
{
"name": "item 1",
"amount": 20000
},
{
"name": "item 2",
"amount": 20000
}
],
"tax": [
{
"name": "VAT",
"amount": 2000
}
],
"amount": 42000,
"discount": null,
"currency": "NGN",
"due_date": "2020-07-08T00:00:00.000Z",
"status": "pending",
"paid": false,
"paid_at": null,
"metadata": null,
"has_invoice": true,
"invoice_number": 1,
"offline_reference": "4286263136406",
"pdf_url": null,
"notifications": [],
"archived": false,
"source": "user",
"payment_method": null,
"note": null,
"amount_paid": null,
"id": 3136406,
"integration": 428626,
"customer": {
"transactions": [],
"subscriptions": [],
"authorizations": [],
"first_name": "Damilola",
"last_name": "Odujoko",
"email": "[email protected]",
"phone": null,
"metadata": {
"calling_code": "+234"
},
"domain": "test",
"customer_code": "CUS_xwaj0txjryg393b",
"risk_action": "default",
"id": 25833615,
"integration": 428626,
"createdAt": "2020-06-29T16:06:53.000Z",
"updatedAt": "2020-06-29T16:06:53.000Z"
},
"createdAt": "2020-06-29T16:07:33.000Z",
"updatedAt": "2020-06-29T16:07:33.000Z",
"pending_amount": 42000
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Update Payment Request
Update a previously created payment request
Path Parameters
The unique identifier of a previously created payment request
Request Body
Customer id or code
Payment request amount. Only useful if line items and tax values are ignored.
The endpoint will throw a friendly warning if neither is available.
Specify the currency of the invoice. Allowed values are NGN, GHS, ZAR and USD. Defaults to NGN
ISO 8601 representation of request due date
A short description of the payment request
Array of line items
Array of taxes
Indicates whether Paystack sends an email notification to customer. Defaults to true
Indicate if request should be saved as draft. Defaults to false and overrides send_notification
Set to true to create a draft invoice (adds an auto incrementing invoice number if none is provided) even if there are no line_items or tax passed
Numeric value of invoice. Invoice will start from 1 and auto increment from there. This field is to help override whatever value Paystack decides. Auto increment for subsequent invoices continue from this point.
The split code of the transaction split.
Response
200Payment Request Update response
23 object properties
9 object properties
1 object property
PUT
/paymentrequest/{id}curl https://api.paystack.co/paymentrequest/18823736 \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"customer": "CUSTOMER",
"amount": 15000
}' \
-X PUTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.paymentRequest.update("18823736", {
customer: "CUSTOMER",
amount: 15000
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.payment_request.update("18823736", {
customer: "CUSTOMER",
amount: 15000
})
puts response.dataResponse
{
"status": true,
"message": "Payment request updated",
"data": {
"id": 3136496,
"domain": "test",
"amount": 45000,
"currency": "NGN",
"due_date": "2020-06-30T22:59:59.000Z",
"has_invoice": true,
"invoice_number": 2,
"description": "Update Testing",
"pdf_url": null,
"line_items": [
{
"name": "Water",
"amount": 15000,
"quantity": 1
},
{
"name": "Bread",
"amount": 30000,
"quantity": 1
}
],
"tax": [],
"request_code": "PRQ_rtjkfk1tpmvqo40",
"status": "pending",
"paid": false,
"paid_at": null,
"metadata": null,
"notifications": [],
"offline_reference": "4286263136496",
"customer": {
"id": 25833615,
"first_name": "Doc",
"last_name": "Test",
"email": "[email protected]",
"customer_code": "CUS_xwaj0txjryg393b",
"phone": null,
"metadata": {
"calling_code": "+234"
},
"risk_action": "default",
"international_format_phone": null
},
"created_at": "2020-06-29T16:22:35.000Z"
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Verify Payment Request
Verify the status of a previously created payment request
Path Parameters
The unique identifier of a previously created payment request
Response
200Payment Request Verify response
24 object properties
4 object properties
9 object properties
1 object property
GET
/paymentrequest/verify/{id}curl https://api.paystack.co/paymentrequest/verify/18823736 \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.paymentRequest.verify("18823736");
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.payment_request.verify("18823736")
puts response.dataResponse
{
"status": true,
"message": "Payment request retrieved",
"data": {
"id": 3136406,
"domain": "test",
"amount": 42000,
"currency": "NGN",
"due_date": "2020-07-08T00:00:00.000Z",
"has_invoice": true,
"invoice_number": 1,
"description": "a test invoice",
"pdf_url": null,
"line_items": [
{
"name": "item 1",
"amount": 20000
},
{
"name": "item 2",
"amount": 20000
}
],
"tax": [
{
"name": "VAT",
"amount": 2000
}
],
"request_code": "PRQ_1weqqsn2wwzgft8",
"status": "pending",
"paid": false,
"paid_at": null,
"metadata": null,
"notifications": [],
"offline_reference": "4286263136406",
"customer": {
"id": 25833615,
"first_name": "Damilola",
"last_name": "Odujoko",
"email": "[email protected]",
"customer_code": "CUS_xwaj0txjryg393b",
"phone": null,
"metadata": {
"calling_code": "+234"
},
"risk_action": "default",
"international_format_phone": null
},
"created_at": "2020-06-29T16:07:33.000Z",
"integration": {
"key": "pk_test_xxxxxxxx",
"name": "Paystack Documentation",
"logo": "https://s3-eu-west-1.amazonaws.com/pstk-integration-logos/paystack.jpg",
"allowed_currencies": [
"NGN",
"USD"
]
},
"pending_amount": 42000
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Send Notification
Trigger an email reminder to a customer for a previously created payment request
Path Parameters
The unique identifier of a previously created payment request
Response
200Payment Request Send Notification response
POST
/paymentrequest/notify/{id}curl https://api.paystack.co/paymentrequest/notify/18823736 \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.paymentRequest.notify("18823736");
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.payment_request.notify("18823736")
puts response.dataResponse
{
"status": true,
"message": "Notification sent"
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Payment Request Total
Get the metric of all pending and successful payment requests
Response
200Payment Request Total response
3 object properties
GET
/paymentrequest/totalscurl https://api.paystack.co/paymentrequest/totals \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.paymentRequest.totals();
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.payment_request.totals()
puts response.dataResponse
{
"status": true,
"message": "Payment request totals",
"data": {
"pending": [
{
"currency": "NGN",
"amount": 42000
},
{
"currency": "USD",
"amount": 0
}
],
"successful": [
{
"currency": "NGN",
"amount": 0
},
{
"currency": "USD",
"amount": 0
}
],
"total": [
{
"currency": "NGN",
"amount": 42000
},
{
"currency": "USD",
"amount": 0
}
]
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Finalize Payment Request
Finalise the creation of a draft payment request for a customer
Path Parameters
The unique identifier of a draft payment request
Response
200Payment Request Finalize response
24 object properties
9 object properties
1 object property
2 object properties
POST
/paymentrequest/finalize/{id}curl https://api.paystack.co/paymentrequest/finalize/18823736 \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.paymentRequest.finalize("18823736");
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.payment_request.finalize("18823736")
puts response.dataResponse
{
"status": true,
"message": "Payment request finalized",
"data": {
"id": 3136496,
"domain": "test",
"amount": 45000,
"currency": "NGN",
"due_date": "2020-06-30T22:59:59.000Z",
"has_invoice": true,
"invoice_number": 2,
"description": "Testing Invoice",
"pdf_url": null,
"line_items": [
{
"name": "Water",
"amount": 15000,
"quantity": 1
},
{
"name": "Bread",
"amount": 30000,
"quantity": 1
}
],
"tax": [],
"request_code": "PRQ_rtjkfk1tpmvqo40",
"status": "pending",
"paid": false,
"paid_at": null,
"metadata": null,
"notifications": [],
"offline_reference": "4286263136496",
"customer": {
"id": 25833615,
"first_name": "Damilola",
"last_name": "Odujoko",
"email": "[email protected]",
"customer_code": "CUS_xwaj0txjryg393b",
"phone": null,
"metadata": {
"calling_code": "+234"
},
"risk_action": "default",
"international_format_phone": null
},
"created_at": "2020-06-29T16:22:35.000Z",
"pending_amount": 45000
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Archive Payment Request
Archive a payment request to clean up your records. An archived payment request cannot be verified and will not be returned when listing all previously created payment requests.
Path Parameters
The unique identifier of a previously created payment request
Response
200Payment Request Archive response
POST
/paymentrequest/archive/{id}curl https://api.paystack.co/paymentrequest/archive/18823736 \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.paymentRequest.archive("18823736");
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.payment_request.archive("18823736")
puts response.dataResponse
{
"status": true,
"message": "Payment request has been archived"
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}