Introduction

Learn how to integrate our APIs into your application

The Paystack API gives you access to pretty much all the features you can use on our dashboard and lets you extend them for use in your application. It strives to be RESTful and is organized around the main resources you would be interacting with - with a few notable exceptions.

Before you do anything
You should create a free Paystack account that you can test the API against. We will provide you with test keys that you can use to make API calls

We provide sample API calls next to each method using cURL. All you need to do is insert your specific parameters, and you can test the calls from the command line. See this tutorial on using cURL with APIs.

You can also use Postman if you aren't familiar with cURL. Postman is an easy to use API development environment for making HTTP requests. You can download the Paystack Postman Collection to make testing the API easier.

Both request body data and response data are formatted as JSON. Content type for responses will always be application/json. Generally, all responses will be in the following format:

1{
2 "status": [boolean], // Only true if the details provided could be processed and no error occured while processing
3 "message": [string], // Explains why status is false... Entirely informational. Please only log this but do not use for your checks
4 "data": [object] // contains actionable result of processing if present
5}

While we generally recommend that developers use HTTP status codes to determine the result of an API call, we have provided a handy status key to let you know upfront if the request was successful or not.

The message key is a string which will contain a summary of the response and its status. For instance when trying to retrieve a list of customers, message might read “Customers retrieved”. In the event of an error, the message key will contain a description of the error as with the authorization header situation above. This is the only key that is universal across requests.

The data key is where you want to look at for the result of your request. It can either be an object, or an array depending on the request made. For instance, a request to retrieve a single customer will return a customer object in the data key, while the key would be an array of customers if a list is requested instead.

The meta key is used to provide context for the contents of the data key. For instance, if a list of transactions performed by a customer is being retrieved, pagination parameters can be passed along to limit the result set. The meta key will then contain an object with the following attributes:

1"meta": {
2 "total": 2,
3 "skipped": 0,
4 "perPage": 50,
5 "page": 1,
6 "pageCount": 1
7}
Keys
TotalNumberThis is the total number of transactions that were performed by the customer.
SkippedNumberThis is the number of records skipped before the first record in the array returned.
PerPageNumber[object Object]
PageNumber[object Object]
PageCountNumberThis is how many pages in total are available for retrieval considering the maximum records per page specified. For context, if there are 51 records and perPage is left at its default value, pageCount will have a value of 2.

Authentication

Authenticate your API calls by including your secret key in the Authorization header of every request you make. You can manage your API keys from the dashboard .

Generally, we provide both public and secret keys. Public keys are meant to be used from your front-end when integrating using Paystack Inline and in our Mobile SDKs only. By design, public keys cannot modify any part of your account besides initiating transactions to you. The secret keys however, are to be kept secret. If for any reason you believe your secret key has been compromised or you wish to reset them, you can do so from the dashboard.

Secure your secret key
Do not commit your secret keys to git, or use them in client-side code.

Authorization headers should be in the following format: Authorization: Bearer SECRET_KEY

Sample Authorization Header
Authorization: Bearer sk_test_shdjkhdj827391nV4Lid

API requests made without authentication will fail with the status code 401: Unauthorized. All API requests must be made over HTTPS.

Secure your requests
Do not set VERIFY_PEER to FALSE. Ensure your server verifies the SSL connection to Paystack.

Errors

As stated earlier, Paystack's API is RESTful and as such, uses conventional HTTP response codes to indicate the success or failure of requests.

We discuss some common errors and their causes below

Authorization code does not exist or has been deactivated

  1. All authorizations are inactive until one transaction succeeds on the card. Attempting charge auth on an inactive authorization will give this message.
  2. You can only charge an authorization for the customer who saved it. If an authorization is paired with the wrong email, you may get this error message.

This authorization is not reusable

Only reusable authorizations can be used with our charge authorization endpoint. Please confirm reusability on the authorization object before making an attempt to avoid this message.

Invalid Subaccount

All subaccounts codes on Paystack start with ACCT_ and only exist on the integration that created them. And in the domain they were created. Common situations when you will get this message include:

  1. Sending subaccount id or name or any value other than a valid code. Rather don't send any subaccount if you do not intend to split the transaction.
  2. Sending subaccount code from another integration.
  3. Sending subaccount code created in the test domain while specifying a live key and vice-versa.

Email does not match Authorization code. Please confirm

You can only charge an authorization for the customer who saved it. If an authorization is paired with the wrong email, you may get this error message.

Invalid Split transaction values

This happens when you have attempted to split the payment in a way that is mathematically impossible. The transaction may have specified the subaccount as bearer though the subaccount's share doesn't cover paystack's fees or vice-versa.

You may also have specified a transaction charge that was above the amount being paid.

Duplicate Transaction Reference

Every transaction on your integration in a domain must have a unique refrence. You will get this message if you attempt to start a new transaction with a reference that has already been used.

Invalid ****

All objects on Paystack are tied to a domain and integration. Getting an Invalid X message might mean the one specified does not exist in the space commanded by the key presented.

Error Codes
200, 201Request was successful and intended action was carried out. Note that we will always send a 200 if a charge or verify request was made. Do check the data object to know how the charge went (i.e. successful or failed).
400A validation or client side error occurred and the request was not fulfilled.
401The request was not authorized. This can be triggered by passing an invalid secret key in the authorization header or the lack of one
404Request could not be fulfilled as the request resource does not exist.
500, 501, 502, 503, 504Request could not be fulfilled due to an error on Paystack's end. This shouldn't happen so please report as soon as you encounter any instance of this.

Transactions

The Transactions API allows you create and manage payments on your integration

Initialize a transaction from your backend

Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Content-TypeStringSet value to application/json
Body Param
amountStringAmount should be in kobo if currency is NGN and pesewas for GHS
emailStringCustomer's email address
currency
String
The transaction currency (NGN, GHS or USD). Defaults to your integration currency.
reference
String
Unique transaction reference. Only -, ., = and alphanumeric characters allowed.
callback_url
String
Fully qualified url, e.g. https://example.com/ . Use this to override the callback url provided on the dashboard for this transaction
plan
String
If transaction is to create a subscription to a predefined plan, provide plan code here. This would invalidate the value provided in amount
invoice_limit
Integer
Number of times to charge customer during subscription to plan
metadata
String
Stringified JSON object. Add a custom_fields attribute which has an array of objects if you would like the fields to be added to your transaction when displayed on the dashboard. Sample: {"custom_fields":[{"display_name":"Cart ID","variable_name": "cart_id","value": "8393"}]}
channels
Array
An array of payment channels to control what channels you want to make available to the user to make a payment with. Available channels include: ['card', 'bank', 'ussd', 'qr', 'mobile_money', 'bank_transfer']
subaccount
String
The code for the subaccount that owns the payment. e.g. ACCT_8f4s1eq7ml6rlzj
transaction_charge
Integer
A flat fee to charge the subaccount for this transaction, in kobo if currency is NGN and pesewas if currency is GHS. This overrides the split percentage set when the subaccount was created. Ideally, you will need to use this if you are splitting in flat rates (since subaccount creation only allows for percentage split). e.g. 7000 for a 70 naira flat fee.
bearer
String
Who bears Paystack charges? account or subaccount (defaults to account).
Show optional parameters
POST/transaction/initialize
cURL
1curl https://api.paystack.co/transaction/initialize
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ email: "[email protected]", amount: "20000" }'
5-X POST
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Authorization URL created",
4 "data": {
5 "authorization_url": "https://checkout.paystack.com/0peioxfhpn",
6 "access_code": "0peioxfhpn",
7 "reference": "7PVGX8MEk85tgeEpVDtD"
8 }
9}
Confirm the status of a transaction
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Path Param
referenceStringThe transaction reference used to intiate the transaction
GET/transaction/verify/:reference
cURL
1curl https://api.paystack.co/transaction/verify/:reference
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-X GET
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Verification successful",
4 "data": {
5 "amount": 27000,
6 "currency": "NGN",
7 "transaction_date": "2016-10-01T11:03:09.000Z",
8 "status": "success",
9 "reference": "DG4uishudoq90LD",
10 "domain": "test",
11 "metadata": 0,
12 "gateway_response": "Successful",
13 "message": null,
14 "channel": "card",
15 "ip_address": "41.1.25.1",
16 "log": {
17 "time_spent": 9,
18 "attempts": 1,
19 "authentication": null,
20 "errors": 0,
21 "success": true,
22 "mobile": false,
23 "input": [],
24 "channel": null,
25 "history": [{
26 "type": "input",
27 "message": "Filled these fields: card number, card expiry, card cvv",
28 "time": 7
29 },
30 {
31 "type": "action",
32 "message": "Attempted to pay",
33 "time": 7
34 },
35 {
36 "type": "success",
37 "message": "Successfully paid",
38 "time": 8
39 },
40 {
41 "type": "close",
42 "message": "Page closed",
43 "time": 9
44 }
45 ]
46 }
47 "fees": null,
48 "authorization": {
49 "authorization_code": "AUTH_8dfhjjdt",
50 "card_type": "visa",
51 "last4": "1381",
52 "exp_month": "08",
53 "exp_year": "2018",
54 "bin": "412345",
55 "bank": "TEST BANK",
56 "channel": "card",
57 "signature": "SIG_idyuhgd87dUYSHO92D",
58 "reusable": true,
59 "country_code": "NG"
60 },
61 "customer": {
62 "id": 84312,
63 "customer_code": "CUS_hdhye17yj8qd2tx",
64 "first_name": "BoJack",
65 "last_name": "Horseman",
66 "email": "[email protected]"
67 },
68 "plan": "PLN_0as2m9n02cl0kp6",
69 "requested_amount": 1500000
70 }
71}
List transactions carried out on your integration.
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Query Param
perPageIntegerSpecify how many records you want to retrieve per page. If not specify we use a default value of 50.
pageIntegerSpecify exactly what page you want to retrieve. If not specify we use a default value of 1.
customer
Integer
Specify an ID for the customer whose transactions you want to retrieve
status
String
Filter transactions by status ('failed', 'success', 'abandoned')
from
Datetime
A timestamp from which to start listing transaction e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
to
Datetime
A timestamp at which to stop listing transaction e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
amount
Integer
Filter transactions by amount. Specify the amount, in kobo if currency is NGN and pesewas if currency is GHS.
Show optional parameters
GET/transaction
cURL
1curl https://api.paystack.co/transaction
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-X GET
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Transactions retrieved",
4 "data": [{
5 "id": 5833,
6 "domain": "test",
7 "status": "failed",
8 "reference": "icy9ma6jd1",
9 "amount": 100,
10 "message": null,
11 "gateway_response": "Declined",
12 "paid_at": null,
13 "created_at": "2016-09-29T00:00:05.000Z",
14 "channel": "card",
15 "currency": "NGN",
16 "ip_address": null,
17 "metadata": null,
18 "timeline": null,
19 "customer": {
20 "first_name": "Ezra",
21 "last_name": "Olubi",
22 "email": "[email protected]",
23 "phone": "16504173147",
24 "metadata": null,
25 "customer_code": "CUS_1uld4hluw0g2gn0"
26 },
27 "authorization": {},
28 "plan": {},
29 "requested_amount": 100
30 },
31 {
32 "id": 298126,
33 "domain": "live",
34 "status": "failed",
35 "reference": "z1gsnks86e6kfo8",
36 "amount": 10000,
37 "message": null,
38 "gateway_response": "Declined",
39 "paid_at": null,
40 "created_at": "2016-09-29T00:03:22.000Z",
41 "channel": "card",
42 "currency": "NGN",
43 "ip_address": null,
44 "metadata": {
45 "custom_fields": [{
46 "display_name": "Mobile Number",
47 "variable_name": "mobile_number",
48 "value": "+2348012345678"
49 }]
50 },
51 "log": null,
52 "fees": null,
53 "paidAt": "2016-09-29T00:03:25.000Z",
54 "createdAt": "2016-09-29T00:03:22.000Z",
55 "authorization": {
56 "authorization_code": "AUTH_86gs11dr",
57 "bin": "539983",
58 "last4": "0061",
59 "exp_month": "08",
60 "exp_year": "2018",
61 "card_type": "mastercard DEBIT",
62 "bank": "Guaranty Trust Bank",
63 "country_code": "NG",
64 "brand": "mastercard"
65 },
66 "customer": {
67 "id": 8279,
68 "first_name": "Ezra",
69 "last_name": "Olubi",
70 "email": "[email protected]",
71 "phone": "16504173147",
72 "customer_code": "CUS_1uld4hluw0g2gn0",
73 "metadata": null,
74 "risk_action": "default"
75 },
76 "requested_amount": 10000
77 }],
78 "meta": {
79 "total": 1,
80 "skipped": 0,
81 "perPage": 50,
82 "page": 1,
83 "pageCount": 1
84 }
85}
Get details of a transaction carried out on your integration.
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Path Param
idIntegerAn ID for the transaction to fetch
GET/transaction/:id
cURL
1curl https://api.paystack.co/transaction/:id
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-X GET
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Transaction retrieved",
4 "data": {
5 "id": 292584114,
6 "domain": "test",
7 "status": "success",
8 "reference": "203520101",
9 "amount": 10000,
10 "message": null,
11 "gateway_response": "Successful",
12 "paid_at": "2019-10-09T13:03:28.000Z",
13 "created_at": "2019-10-09T13:00:16.000Z",
14 "channel": "card",
15 "currency": "NGN",
16 "ip_address": "197.211.43.98",
17 "metadata": {
18 "custom_fields": [
19 {
20 "display_name": "Mobile Number",
21 "variable_name": "mobile_number",
22 "value": "+2348012345678"
23 }
24 ],
25 "referrer": "http://localhost:3001/integration/microphone.html?"
26 },
27 "log": {
28 "start_time": 1570626018,
29 "time_spent": 192,
30 "attempts": 1,
31 "errors": 0,
32 "success": true,
33 "mobile": false,
34 "input": [],
35 "history": [
36 {
37 "type": "action",
38 "message": "Attempted to pay with card",
39 "time": 191
40 },
41 {
42 "type": "success",
43 "message": "Successfully paid with card",
44 "time": 192
45 }
46 ]
47 },
48 "fees": 150,
49 "fees_split": null,
50 "authorization": {
51 "authorization_code": "AUTH_2e4k18sj52",
52 "bin": "408408",
53 "last4": "4081",
54 "exp_month": "12",
55 "exp_year": "2020",
56 "channel": "card",
57 "card_type": "visa DEBIT",
58 "bank": "Test Bank",
59 "country_code": "NG",
60 "brand": "visa",
61 "reusable": true,
62 "signature": "SIG_JrPFkMYhcu8AD75eQWKl"
63 },
64 "customer": {
65 "id": 1809887,
66 "first_name": null,
67 "last_name": null,
68 "email": "[email protected]",
69 "customer_code": "CUS_0c35ys9w8ma5tbr",
70 "phone": null,
71 "metadata": null,
72 "risk_action": "deny"
73 },
74 "plan": {},
75 "subaccount": {},
76 "order_id": null,
77 "paidAt": "2019-10-09T13:03:28.000Z",
78 "createdAt": "2019-10-09T13:00:16.000Z",
79 "requested_amount": 1500000
80 }
81}
All authorizations marked as reusable can be charged with this endpoint whenever you need to recieve payments.
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Content-TypeStringSet value to application/json
Body Param
amountStringAmount should be in kobo if currency is NGN and pesewas for GHS
emailStringCustomer's email address
authorization_codeStringValid authorization code to charge
reference
String
Unique transaction reference. Only -, ., = and alphanumeric characters allowed.
plan
String
If transaction is to create a subscription to a predefined plan, provide plan code here. This would invalidate the value provided in amount
currency
String
Currency in which amount should be charged
invoice_limit
Integer
Number of times to charge customer during subscription to plan
metadata
String
Stringified JSON object. Add a custom_fields attribute which has an array of objects if you would like the fields to be added to your transaction when displayed on the dashboard. Sample: {"custom_fields":[{"display_name":"Cart ID","variable_name": "cart_id","value": "8393"}]}
channels
Array
Send us 'card' or 'bank' or 'card','bank' as an array to specify what options to show the user paying
subaccount
String
The code for the subaccount that owns the payment. e.g. ACCT_8f4s1eq7ml6rlzj
transaction_charge
Integer
A flat fee to charge the subaccount for this transaction, in kobo if currency is NGN and pesewas if currency is GHS. This overrides the split percentage set when the subaccount was created. Ideally, you will need to use this if you are splitting in flat rates (since subaccount creation only allows for percentage split). e.g. 7000 for a 70 naira flat fee.
bearer
String
Who bears Paystack charges? account or subaccount (defaults to account).
queue
Boolean
If you are making a scheduled charge call, it is a good idea to queue them so the processing system does not get overloaded causing transaction processing errors. Send queue:true to take advantage of our queued charging.
Show optional parameters
POST/transaction/charge_authorization
cURL
1curl https://api.paystack.co/transaction/charge_authorization
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ email: "[email protected]", amount: "20000", "authorization_code": "AUTH_72btv547" }'
5-X POST
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Charge attempted",
4 "data": {
5 "amount": 27000,
6 "currency": "NGN",
7 "transaction_date": "2020-05-27T11:45:03.000Z",
8 "status": "success",
9 "reference": "cn65lf4ixmkzvda",
10 "domain": "test",
11 "metadata": "",
12 "gateway_response": "Approved",
13 "message": null,
14 "channel": "card",
15 "ip_address": null,
16 "log": null,
17 "fees": 14500,
18 "authorization": {
19 "authorization_code": "AUTH_pmx3mgawyd",
20 "bin": "408408",
21 "last4": "4081",
22 "exp_month": "12",
23 "exp_year": "2020",
24 "channel": "card",
25 "card_type": "visa DEBIT",
26 "bank": "Test Bank",
27 "country_code": "NG",
28 "brand": "visa",
29 "reusable": true,
30 "signature": "SIG_2Gvc6pNuzJmj4TCchXfp",
31 "account_name": null
32 },
33 "customer": {
34 "id": 23215815,
35 "first_name": null,
36 "last_name": null,
37 "email": "[email protected]",
38 "customer_code": "CUS_wt0zmhzb0xqd4nr",
39 "phone": null,
40 "metadata": null,
41 "risk_action": "default"
42 },
43 "plan": null,
44 "id": 696105928
45 }
46}

All mastercard and visa authorizations can be checked with this endpoint to know if they have funds for the payment you seek.

This endpoint should be used when you do not know the exact amount to charge a card when rendering a service. It should be used to check if a card has enough funds based on a maximum range value. It is well suited for:

  • Ride hailing services
  • Logistics services
Warning
You shouldn't use this endpoint to check a card for sufficient funds if you are going to charge the user immediately. This is because we hold funds when this endpoint is called which can lead to an insufficient funds error.
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Content-TypeStringSet value to application/json
Body Param
amountStringAmount should be in kobo if currency is NGN and pesewas for GHS
emailStringCustomer's email address
authorization_codeStringValid authorization code to charge
currency
String
Currency in which amount should be charged
Show optional parameters
POST/transaction/check_authorization
cURL
1curl https://api.paystack.co/transaction/check_authorization
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ email: "[email protected]", amount: "20000", "authorization_code": "AUTH_72btv547" }'
5-X POST
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Authorization is valid for this amount",
4 "data": {
5 "amount": "400",
6 "currency": "NGN"
7 }
8}
View the timeline of a transaction
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Path Param
id_or_referenceStringThe ID or the reference of the transaction
GET/transaction/timeline/:id_or_reference
cURL
1curl https://api.paystack.co/transaction/timeline/:id_or_reference
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-X GET
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Timeline retrieved",
4 "data": {
5 "time_spent": 9061,
6 "attempts": 1,
7 "authentication": null,
8 "errors": 1,
9 "success": false,
10 "mobile": false,
11 "input": [],
12 "channel": "card",
13 "history": [
14 {
15 "type": "open",
16 "message": "Opened payment page",
17 "time": 1
18 },
19 {
20 "type": "input",
21 "message": "Filled these fields: card number, card expiry, card cvc",
22 "time": 39
23 },
24 {
25 "type": "action",
26 "message": "Attempted to pay",
27 "time": 39
28 },
29 {
30 "type": "error",
31 "message": "Error: Declined",
32 "time": 48
33 },
34 {
35 "type": "input",
36 "message": "Filled these fields: card expiry, card cvc",
37 "time": 9061
38 },
39 {
40 "type": "close",
41 "message": "Page closed",
42 "time": 9061
43 }
44 ]
45 }
46}
Total amount received on your account
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Path Param
perPageIntegerSpecify how many records you want to retrieve per page. If not specify we use a default value of 50.
pageIntegerSpecify exactly what page you want to retrieve. If not specify we use a default value of 1.
from
Datetime
A timestamp from which to start listing transaction e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
to
Datetime
A timestamp at which to stop listing transaction e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
Show optional parameters
GET/transaction/totals
cURL
1curl https://api.paystack.co/transaction/totals
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-X GET
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Transaction totals",
4 "data": {
5 "total_transactions": 10,
6 "unique_customers": 3,
7 "total_volume": 14000,
8 "total_volume_by_currency": [
9 {
10 "currency": "NGN",
11 "amount": 14000
12 }
13 ],
14 "pending_transfers": 24000,
15 "pending_transfers_by_currency": [
16 {
17 "currency": "NGN",
18 "amount": 24000
19 }
20 ]
21 }
22}
List transactions carried out on your integration.
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Query Param
perPageIntegerSpecify how many records you want to retrieve per page. If not specify we use a default value of 50.
pageIntegerSpecify exactly what page you want to retrieve. If not specify we use a default value of 1.
from
Datetime
A timestamp from which to start listing transaction e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
to
Datetime
A timestamp at which to stop listing transaction e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
customer
Integer
Specify an ID for the customer whose transactions you want to retrieve
status
String
Filter transactions by status ('failed', 'success', 'abandoned')
currency
String
Specify the transaction currency to export
amount
Integer
Filter transactions by amount. Specify the amount, in kobo if currency is NGN and pesewas if currency is GHS.
settled
Boolean
Set to true to export only settled transactions. false for pending transactions. Leave undefined to export all transactions
settlement
Integer
An ID for the settlement whose transactions we should export
payment_page
Integer
Specify a payment page's id to export only transactions conducted on said page
Show optional parameters
GET/transaction/export
cURL
1curl https://api.paystack.co/transaction/export
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-X GET
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Export successful",
4 "data": {
5 "path": "https://files.paystack.co/exports/100032/1460290758207.csv"
6 }
7}
Retrieve part of a payment from a customer
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Content-TypeStringSet value to application/json
Body Param
authorizationStringAurhorization Code
currencyStringSpecify the currency you want to debit
amountStringAmount should be in kobo if currency is NGN and pesewas for GHS
email
String
Customer's email address (attached to the authorization code)
reference
String
Unique transaction reference. Only -, ., = and alphanumeric characters allowed.
at_least
String
Minimum amount to charge
Show optional parameters
POST/transaction/partial_debit
cURL
1curl https://api.paystack.co/transaction/partial_debit
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ authorization: "AUTH_72btv547", currency: "NGN", amount: "20000" }'
5-X POST
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Charge attempted",
4 "data": {
5 "amount": 2000,
6 "currency": "NGN",
7 "transaction_date": "2020-01-23T14:39:37.000Z",
8 "status": "success",
9 "reference": "REF_0000000001",
10 "domain": "test",
11 "metadata": "",
12 "gateway_response": "Approved",
13 "message": null,
14 "channel": "card",
15 "ip_address": null,
16 "log": null,
17 "fees": 30,
18 "authorization": {
19 "authorization_code": "AUTH_4edwayn8k4",
20 "bin": "408408",
21 "last4": "0409",
22 "exp_month": "12",
23 "exp_year": "2020",
24 "channel": "card",
25 "card_type": "visa DEBIT",
26 "bank": "Test Bank",
27 "country_code": "NG",
28 "brand": "visa",
29 "reusable": true,
30 "signature": "SIG_GfJIf2Dg1N1BwN5ddXmh"
31 },
32 "customer": {
33 "id": 16702,
34 "first_name": "",
35 "last_name": "",
36 "email": "[email protected]",
37 "customer_code": "CUS_096t7vsogztygg4",
38 "phone": "",
39 "metadata": null,
40 "risk_action": "default"
41 },
42 "plan": 0,
43 "amount": 2000
44 }
45}

Transaction Splits

The Transaction Splits API enables merchants split the settlement for a transaction across their payout account, and one or more Subaccounts.

Create a split payment on your integration
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Content-TypeStringSet value to application/json
Body Param
nameStringName of the transaction split
typeStringThe type of transaction split you want to create. You can use one of the following: percentage | flat
currencyStringNGN, GHS, or USD
subaccountsArray of ObjectsA list of object containing subaccount code and number of shares: [{subaccount_code: ‘ACT_xxxxxxxxxx’, share: xxx},{...}]
bearer_typeStringAny of subaccounts|subaccount|account|all
bearer_subaccountStringSubaccount code
main_account_shareStringThe main account share
POST/split
cURL
1curl https://api.paystack.co/split
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "name":"Percentage Split",
5 "type":"percentage",
6 "currency": "NGN",
7 "subaccounts":[{
8 "subaccount": "ACCT_z3x6z3nbo14xsil",
9 "share": 20
10 },
11 {
12 "subaccount": "ACCT_pwwualwty4nhq9d",
13 "share": 30
14 }],
15 "bearer_type":"subaccount",
16 "bearer_subaccount":"ACCT_hdl8abxl8drhrl3",
17 "main_account_share":100
18 }'
19-X POST
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Split created",
4 "data": {
5 "id": 142,
6 "name": "Test Doc",
7 "type": "percentage",
8 "currency": "NGN",
9 "integration": 428626,
10 "domain": "test",
11 "split_code": "SPL_e7jnRLtzla",
12 "active": true,
13 "bearer_type": "subaccount",
14 "bearer_subaccount": 40809,
15 "createdAt": "2020-06-30T11:42:29.150Z",
16 "updatedAt": "2020-06-30T11:42:29.150Z",
17 "subaccounts": [
18 {
19 "subaccount": {
20 "id": 40809,
21 "subaccount_code": "ACCT_z3x6z3nbo14xsil",
22 "business_name": "Business Name",
23 "description": "Business Description",
24 "primary_contact_name": null,
25 "primary_contact_email": null,
26 "primary_contact_phone": null,
27 "metadata": null,
28 "percentage_charge": 20,
29 "settlement_bank": "Business Bank",
30 "account_number": "1234567890"
31 },
32 "share": 20
33 },
34 {
35 "subaccount": {
36 "id": 40809,
37 "subaccount_code": "ACCT_pwwualwty4nhq9d",
38 "business_name": "Business Name",
39 "description": "Business Description",
40 "primary_contact_name": null,
41 "primary_contact_email": null,
42 "primary_contact_phone": null,
43 "metadata": null,
44 "percentage_charge": 20,
45 "settlement_bank": "Business Bank",
46 "account_number": "0123456789"
47 },
48 "share": 30
49 }
50 ],
51 "total_subaccounts": 2
52 }
53}
List/search for the transaction splits available on your integration.
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Query Param
nameStringThe name of the split
activeBooleanAny of true or false
sort_by
String
Sort by name, defaults to createdAt date
perPage
Integer
Number of splits per page. If not specify we use a default value of 50.
page
Integer
Page number to view. If not specify we use a default value of 1.
from
Datetime
A timestamp from which to start listing splits e.g. 2019-09-24T00:00:05.000Z, 2019-09-21
to
Datetime
A timestamp at which to stop listing splits e.g. 2019-09-24T00:00:05.000Z, 2019-09-21
Show optional parameters
GET/split
cURL
1curl https://api.paystack.co/split
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-X GET
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Split retrieved",
4 "data": [
5 {
6 "id": 143,
7 "name": "Test Doc",
8 "split_code": "SPL_UO2vBzEqHW",
9 "integration": 428626,
10 "domain": "test",
11 "type": "percentage",
12 "active": 1,
13 "currency": "NGN",
14 "bearer_type": "subaccount",
15 "bearer_subaccount": 40809,
16 "created_at": "2020-06-30T11:52:24.000Z",
17 "updated_at": "2020-06-30T11:52:24.000Z",
18 "subaccounts": [
19 {
20 "subaccount": {
21 "id": 40809,
22 "subaccount_code": "ACCT_z3x6z3nbo14xsil",
23 "business_name": "Business Name",
24 "description": "Business Description",
25 "primary_contact_name": null,
26 "primary_contact_email": null,
27 "primary_contact_phone": null,
28 "metadata": null,
29 "percentage_charge": 80,
30 "settlement_bank": "Business Bank",
31 "account_number": "1234567890"
32 },
33 "share": 30
34 },
35 {
36 "subaccount": {
37 "id": 40811,
38 "subaccount_code": "ACCT_pwwualwty4nhq9d",
39 "business_name": "Business Name",
40 "description": "Business Description",
41 "primary_contact_name": null,
42 "primary_contact_email": null,
43 "primary_contact_phone": null,
44 "metadata": null,
45 "percentage_charge": 80,
46 "settlement_bank": "Business Bank",
47 "account_number": "0123456789"
48 },
49 "share": 20
50 }
51 ],
52 "total_subaccounts": 2
53 }
54 ],
55 "meta": {
56 "total": 1,
57 "skipped": 0,
58 "perPage": 50,
59 "page": 1,
60 "pageCount": 1
61 }
62}
Get details of a split on your integration.
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Path Param
idStringThe id of the split
GET/split/:id
cURL
1curl https://api.paystack.co/split/:id
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-X GET
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Split retrieved",
4 "data": {
5 "id": 143,
6 "name": "Test Doc",
7 "split_code": "SPL_UO2vBzEqHW",
8 "integration": 428626,
9 "domain": "test",
10 "type": "percentage",
11 "active": 1,
12 "currency": "NGN",
13 "bearer_type": "subaccount",
14 "bearer_subaccount": 40809,
15 "created_at": "2020-06-30T11:52:24.000Z",
16 "updated_at": "2020-06-30T11:52:24.000Z",
17 "subaccounts": [
18 {
19 "subaccount": {
20 "id": 40809,
21 "subaccount_code": "ACCT_z3x6z3nbo14xsil",
22 "business_name": "Business Name",
23 "description": "Business Description",
24 "primary_contact_name": null,
25 "primary_contact_email": null,
26 "primary_contact_phone": null,
27 "metadata": null,
28 "percentage_charge": 80,
29 "settlement_bank": "Business Bank",
30 "account_number": "1234567890"
31 },
32 "share": 30
33 },
34 {
35 "subaccount": {
36 "id": 40811,
37 "subaccount_code": "ACCT_pwwualwty4nhq9d",
38 "business_name": "Business Name",
39 "description": "Business Description",
40 "primary_contact_name": null,
41 "primary_contact_email": null,
42 "primary_contact_phone": null,
43 "metadata": null,
44 "percentage_charge": 80,
45 "settlement_bank": "Business Bank",
46 "account_number": "0123456789"
47 },
48 "share": 20
49 }
50 ],
51 "total_subaccounts": 2
52 }
53}
Update a transaction split details on your integration
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Content-TypeStringSet value to application/json
Path Param
idStringSplit ID
Body Param
nameStringName of the transaction split
typeStringThe type of transaction split you want to create. You can use one of the following: percentage | flat
subaccounts
Array of Objects
A list of object containing subaccount code and number of shares: [{subaccount_code: ‘ACT_xxxxxxxxxx’, share: xxx},{...}]
active
Boolean
True or False
Show optional parameters
PUT/split/:id
cURL
1curl https://api.paystack.co/split/:id
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "name": "Updated Name", "active": true }'
5-X PUT
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Split group updated",
4 "data": {
5 "id": 95,
6 "name": "Updated Name",
7 "type": "percentage",
8 "currency": "NGN",
9 "integration": 165956,
10 "domain": "live",
11 "split_code": "SPL_uMzcGbG5ca",
12 "active": false,
13 "bearer_type": "all",
14 "bearer_subaccount": null,
15 "createdAt": "2020-06-22T16:20:53.000Z",
16 "updatedAt": "2020-06-22T17:26:59.000Z",
17 "subaccounts": [
18 {
19 "subaccount": {
20 "id": 12700,
21 "subaccount_code": "ACCT_jsuq5uwf3n8la7b",
22 "business_name": "Ayobami GTB",
23 "description": "Ayobami GTB",
24 "primary_contact_name": null,
25 "primary_contact_email": null,
26 "primary_contact_phone": null,
27 "metadata": null,
28 "percentage_charge": 20,
29 "settlement_bank": "Guaranty Trust Bank",
30 "account_number": "0259198351"
31 },
32 "share": 80
33 }
34 ],
35 "total_subaccounts": 1
36 }
37}

Add a Subaccount to a Transaction Split, or update the share of an existing Subaccount in a Transaction Split

Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Content-TypeStringSet value to application/json
Path Param
idStringSplit Id
Body Param
subaccountStringThis is the sub account code
shareIntegerThis is the transaction share for the subaccount
POST/split/:id/subaccount/add
cURL
1curl https://api.paystack.co/split/:id/subaccount/add
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "subaccount": "ACCT_hdl8abxl8drhrl3", "share": 40000 }'
5-X POST
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Subaccount added",
4 "data": {
5 "id": 143,
6 "name": "Test Doc",
7 "type": "percentage",
8 "currency": "NGN",
9 "integration": 428626,
10 "domain": "test",
11 "split_code": "SPL_UO2vBzEqHW",
12 "active": true,
13 "bearer_type": "subaccount",
14 "bearer_subaccount": 40809,
15 "createdAt": "2020-06-30T11:52:24.000Z",
16 "updatedAt": "2020-06-30T11:52:24.000Z",
17 "subaccounts": [
18 {
19 "subaccount": {
20 "id": 40809,
21 "subaccount_code": "ACCT_sv6roe394nkpu6j",
22 "business_name": "Business Name",
23 "description": "Business Description",
24 "primary_contact_name": null,
25 "primary_contact_email": null,
26 "primary_contact_phone": null,
27 "metadata": null,
28 "percentage_charge": 20,
29 "settlement_bank": "Business Bank",
30 "account_number": "1234567890"
31 },
32 "share": 30
33 },
34 {
35 "subaccount": {
36 "id": 40811,
37 "subaccount_code": "ACCT_7i76qpjh7rr6q3z",
38 "business_name": "Business Name",
39 "description": "Business Description",
40 "primary_contact_name": null,
41 "primary_contact_email": null,
42 "primary_contact_phone": null,
43 "metadata": null,
44 "percentage_charge": 20,
45 "settlement_bank": "Business Bank",
46 "account_number": "0123456789"
47 },
48 "share": 30
49 }
50 ],
51 "total_subaccounts": 2
52 }
53}
Remove a subaccount from a transaction split
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Content-TypeStringSet value to application/json
Path Param
idStringSplit Id
Body Param
subaccountStringThis is the sub account code
POST/split/:id/subaccount/remove
cURL
1curl https://api.paystack.co/split/:id/subaccount/remove
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "subaccount": "ACCT_hdl8abxl8drhrl3" }'
5-X POST
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Subaccount removed"
4}

Customers

The Customers API allows you create and manage customers on your integration.

Create a customer on your integration
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Content-TypeStringSet value to application/json
Body Param
emailStringCustomer's email address
first_nameStringCustomer's first name
last_nameStringCustomer's last name
phone
String
Customer's phone number
metadata
Object
A set of key/value pairs that you can attach to the customer. It can be used to store additional information in a structured format.
Show optional parameters
POST/customer
cURL
1curl https://api.paystack.co/customer
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ email: "[email protected]" }'
5-X POST
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Customer created",
4 "data": {
5 "email": "[email protected]",
6 "integration": 100032,
7 "domain": "test",
8 "customer_code": "CUS_xnxdt6s1zg1f4nx",
9 "id": 1173,
10 "createdAt": "2016-03-29T20:03:09.584Z",
11 "updatedAt": "2016-03-29T20:03:09.584Z"
12 }
13}
List customers available on your integration.
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Query Param
perPageIntegerSpecify how many records you want to retrieve per page. If not specify we use a default value of 50.
pageIntegerSpecify exactly what page you want to retrieve. If not specify we use a default value of 1.
from
Datetime
A timestamp from which to start listing customers e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
to
Datetime
A timestamp at which to stop listing customers e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
Show optional parameters
GET/customer
cURL
1curl https://api.paystack.co/customer
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-X GET
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Customers retrieved",
4 "data": [
5 {
6 "integration": 100032,
7 "first_name": "Bojack",
8 "last_name": "Horseman",
9 "email": "[email protected]",
10 "phone": null,
11 "metadata": {
12 "photos": [
13 {
14 "type": "twitter",
15 "typeId": "twitter",
16 "typeName": "Twitter",
17 "url": "https://d2ojpxxtu63wzl.cloudfront.net/static/61b1a0a1d4dda2c9fe9e165fed07f812_a722ae7148870cc2e33465d1807dfdc6efca33ad2c4e1f8943a79eead3c21311",
18 "isPrimary": true
19 }
20 ]
21 },
22 "domain": "test",
23 "customer_code": "CUS_xnxdt6s1zg1f4nx",
24 "id": 1173,
25 "createdAt": "2016-03-29T20:03:09.000Z",
26 "updatedAt": "2016-03-29T20:03:10.000Z"
27 },
28 {
29 "integration": 100032,
30 "first_name": "Diane",
31 "last_name": "Nguyen",
32 "email": "[email protected]",
33 "phone": "16504173147",
34 "metadata": null,
35 "domain": "test",
36 "customer_code": "CUS_1uld4hluw0g2gn0",
37 "id": 63,
38 "createdAt": "2016-01-13T01:15:47.000Z",
39 "updatedAt": "2016-02-24T16:56:48.000Z"
40 },
41 {
42 "integration": 100032,
43 "first_name": null,
44 "last_name": null,
45 "email": "[email protected]",
46 "phone": null,
47 "metadata": null,
48 "domain": "test",
49 "customer_code": "CUS_soirsjdqkyjfwcr",
50 "id": 65,
51 "createdAt": "2016-01-13T01:15:47.000Z",
52 "updatedAt": "2016-01-13T01:15:47.000Z"
53 }
54 ],
55 "meta": {
56 "total": 3,
57 "skipped": 0,
58 "perPage": 50,
59 "page": 1,
60 "pageCount": 1
61 }
62}
Get details of a customer on your integration.
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Path Param
email_or_codeStringAn email or customer code for the customer you want to fetch
GET/customer/:email_or_code
cURL
1curl https://api.paystack.co/customer/:email_or_code
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-X GET
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Customer retrieved",
4 "data": {
5 "integration": 100032,
6 "first_name": "Bojack",
7 "last_name": "Horseman",
8 "email": "[email protected]",
9 "phone": null,
10 "metadata": {
11 "photos": [
12 {
13 "type": "twitter",
14 "typeId": "twitter",
15 "typeName": "Twitter",
16 "url": "https://d2ojpxxtu63wzl.cloudfront.net/static/61b1a0a1d4dda2c9fe9e165fed07f812_a722ae7148870cc2e33465d1807dfdc6efca33ad2c4e1f8943a79eead3c21311",
17 "isPrimary": true
18 }
19 ]
20 "domain": "test",
21 "customer_code": "CUS_xnxdt6s1zg1f4nx",
22 "id": 1173,
23 "transactions": [],
24 "subscriptions": [],
25 "authorizations": [],
26 "createdAt": "2016-03-29T20:03:09.000Z",
27 "updatedAt": "2016-03-29T20:03:10.000Z"
28 }
29}
Update a customer's details on your integration
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Content-TypeStringSet value to application/json
Query Param
codeStringCustomer's code
Body Param
first_nameStringCustomer's first name
last_nameStringCustomer's last name
phone
String
Customer's phone number
metadata
Object
A set of key/value pairs that you can attach to the customer. It can be used to store additional information in a structured format.
Show optional parameters
PUT/customer/:code
cURL
1curl https://api.paystack.co/customer/:code
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ first_name: "BoJack" }'
5-X PUT
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Customer updated",
4 "data": {
5 "integration": 100032,
6 "first_name": "BoJack",
7 "last_name": "Horseman",
8 "email": "[email protected]",
9 "phone": null,
10 "metadata": {
11 "photos": [
12 {
13 "type": "twitter",
14 "typeId": "twitter",
15 "typeName": "Twitter",
16 "url": "https://d2ojpxxtu63wzl.cloudfront.net/static/61b1a0a1d4dda2c9fe9e165fed07f812_a722ae7148870cc2e33465d1807dfdc6efca33ad2c4e1f8943a79eead3c21311",
17 "isPrimary": true
18 }
19 ]
20 },
21 "domain": "test",
22 "customer_code": "CUS_xnxdt6s1zg1f4nx",
23 "id": 1173,
24 "transactions": [],
25 "subscriptions": [],
26 "authorizations": [],
27 "createdAt": "2016-03-29T20:03:09.000Z",
28 "updatedAt": "2016-03-29T20:03:10.000Z"
29 }
30}
Whitelist or blacklist a customer on your integration
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Content-TypeStringSet value to application/json
Body Param
customerStringCustomer's code, or email address
risk_action
String
One of the possible risk actions [ default, allow, deny ]. allow to whitelist. deny to blacklist. Customers start with a default risk action.
Show optional parameters
POST/customer/set_risk_action
cURL
1curl https://api.paystack.co/customer/set_risk_action
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ customer: "CUS_xr58yrr2ujlft9k", risk_action: "allow" }'
5-X POST
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Customer updated",
4 "data": {
5 "first_name": "Peter",
6 "last_name": "Griffin",
7 "email": "[email protected]",
8 "phone": null,
9 "metadata": {},
10 "domain": "test",
11 "customer_code": "CUS_xr58yrr2ujlft9k",
12 "risk_action": "allow",
13 "id": 2109,
14 "integration": 100032,
15 "createdAt": "2016-01-26T13:43:38.000Z",
16 "updatedAt": "2016-08-23T03:56:43.000Z"
17 }
18}
Deactivate an authorization when the card needs to be forgotten
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Content-TypeStringSet value to application/json
Body Param
authorization_codeStringAuthorization code to be deactivated
POST/customer/deactivate_authorization
cURL
1curl https://api.paystack.co/customer/deactivate_authorization
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "authorization_code": "AUTH_72btv547" }'
5-X POST
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Authorization is valid for this amount",
4 "data": {
5 "amount": "400",
6 "currency": "NGN"
7 }
8}

Subaccounts

The Subaccounts API allows you create and manage subaccounts on your integration. Subaccounts can be used to split payment between two accounts (your main account and a sub account)

Create a subacount on your integration
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Content-TypeStringSet value to application/json
Body Param
business_nameStringName of business for subaccount
settlement_bankStringBank Code for the bank (see list of corresponding bank codes by calling List Bank)
account_numberStringNUBAN Bank Account Number
percentage_chargeFloatThe default percentage charged when receiving on behalf of this subaccount
descriptionStringA description for this subaccount
primary_contact_email
String
A contact email for the subaccount
primary_contact_name
String
A name for the contact person for this subaccount
primary_contact_phone
String
A phone number to call for this subaccount
metadata
String
Stringified JSON object. Add a custom_fields attribute which has an array of objects if you would like the fields to be added to your transaction when displayed on the dashboard. Sample: {"custom_fields":[{"display_name":"Cart ID","variable_name": "cart_id","value": "8393"}]}
Show optional parameters
POST/subaccount
cURL
1curl https://api.paystack.co/subaccount
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "business_name": "Sunshine Studios", "settlement_bank": "044", "account_number": "0193274682", "percentage_charge": 18.2 }'
5-X POST
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Subaccount created",
4 "data": {
5 "integration": 100973,
6 "domain": "test",
7 "subaccount_code": "ACCT_4hl4xenwpjy5wb",
8 "business_name": "Sunshine Studios",
9 "description": null,
10 "primary_contact_name": null,
11 "primary_contact_email": null,
12 "primary_contact_phone": null,
13 "metadata": null,
14 "percentage_charge": 18.2,
15 "is_verified": false,
16 "settlement_bank": "Access Bank",
17 "account_number": "0193274682",
18 "settlement_schedule": "AUTO",
19 "active": true,
20 "migrate": false,
21 "id": 55,
22 "createdAt": "2016-10-05T13:22:04.000Z",
23 "updatedAt": "2016-10-21T02:19:47.000Z"
24 }
25}
List subaccounts available on your integration.
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Query Param
perPageIntegerSpecify how many records you want to retrieve per page. If not specify we use a default value of 50.
pageIntegerSpecify exactly what page you want to retrieve. If not specify we use a default value of 1.
from
Datetime
A timestamp from which to start listing subaccounts e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
to
Datetime
A timestamp at which to stop listing subaccounts e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
Show optional parameters
GET/subaccount
cURL
1curl https://api.paystack.co/subaccount
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-X GET
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Subaccounts retrieved",
4 "data": [
5 {
6 "integration": 129938,
7 "domain": "test",
8 "subaccount_code": "ACCT_cljt3j4cp0kb2gq",
9 "business_name": "Business 2",
10 "description": null,
11 "primary_contact_name": null,
12 "primary_contact_email": null,
13 "primary_contact_phone": null,
14 "metadata": null,
15 "percentage_charge": 20,
16 "is_verified": false,
17 "settlement_bank": "Zenith Bank",
18 "account_number": "0193274382",
19 "active": true,
20 "migrate": false,
21 "id": 53,
22 "createdAt": "2016-10-05T12:55:47.000Z",
23 "updatedAt": "2016-10-05T12:55:47.000Z"
24 },
25 {
26 "integration": 129938,
27 "domain": "test",
28 "subaccount_code": "ACCT_vwy3d1gck2c9gxi",
29 "business_name": "Sunshine Studios",
30 "description": null,
31 "primary_contact_name": null,
32 "primary_contact_email": null,
33 "primary_contact_phone": null,
34 "metadata": null,
35 "percentage_charge": 20,
36 "is_verified": false,
37 "settlement_bank": "Access Bank",
38 "account_number": "0128633833",
39 "active": true,
40 "migrate": false,
41 "id": 35,
42 "createdAt": "2016-10-04T09:06:00.000Z",
43 "updatedAt": "2016-10-04T09:06:00.000Z"
44 },
45 {
46 "integration": 129938,
47 "domain": "test",
48 "subaccount_code": "ACCT_5mikcokeaknxk1f",
49 "business_name": "Business 2",
50 "description": null,
51 "primary_contact_name": null,
52 "primary_contact_email": null,
53 "primary_contact_phone": null,
54 "percentage_charge": 20,
55 "is_verified": false,
56 "settlement_bank": "Access Bank",
57 "account_number": "0000000000",
58 "active": true,
59 "migrate": false,
60 "id": 34,
61 "createdAt": "2016-10-04T08:46:18.000Z",
62 "updatedAt": "2016-10-04T08:46:18.000Z"
63 }
64 ],
65 "meta": {
66 "total": 20,
67 "skipped": 0,
68 "perPage": "3",
69 "page": 1,
70 "pageCount": 7
71 }
72}
Get details of a subaccount on your integration.
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Path Param
id_or_codeStringThe subaccount ID or code you want to fetch
GET/subaccount/:id_or_code
cURL
1curl https://api.paystack.co/subaccount/:id_or_code
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-X GET
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Subaccount retrieved",
4 "data": {
5 "integration": 100973,
6 "domain": "test",
7 "subaccount_code": "ACCT_4hl4xenwpjy5wb",
8 "business_name": "Sunshine Studios",
9 "description": null,
10 "primary_contact_name": null,
11 "primary_contact_email": "[email protected]",
12 "primary_contact_phone": null,
13 "metadata": null,
14 "percentage_charge": 18.9,
15 "is_verified": false,
16 "settlement_bank": "Access Bank",
17 "account_number": "0193274682",
18 "settlement_schedule": "AUTO",
19 "active": true,
20 "migrate": false,
21 "id": 55,
22 "createdAt": "2016-10-05T13:22:04.000Z",
23 "updatedAt": "2016-10-21T02:19:47.000Z"
24 }
25}
Update a subaccount details on your integration
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Content-TypeStringSet value to application/json
Headers
id_or_codeStringSubaccount's ID or code
Body Param
business_nameStringName of business for subaccount
settlement_bankStringBank Code for the bank (see list of corresponding bank codes by calling List Bank)
account_number
String
NUBAN Bank Account Number
active
Boolean
Activate or deactivate a subaccount. Set value to true to activate subaccount or false to deactivate the subaccount.
percentage_charge
Float
The default percentage charged when receiving on behalf of this subaccount
description
String
A description for this subaccount
primary_contact_email
String
A contact email for the subaccount
primary_contact_name
String
A name for the contact person for this subaccount
primary_contact_phone
String
A phone number to call for this subaccount
settlement_schedule
String
Any of auto, weekly, `monthly`, `manual`. Auto means payout is T+1 and manual means payout to the subaccount should only be made when requested. Defaults to auto
metadata
String
Stringified JSON object. Add a custom_fields attribute which has an array of objects if you would like the fields to be added to your transaction when displayed on the dashboard. Sample: {"custom_fields":[{"display_name":"Cart ID","variable_name": "cart_id","value": "8393"}]}
Show optional parameters
PUT/subaccount/:id_or_code
cURL
1curl https://api.paystack.co/subaccount/:id_or_code
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ primary_contact_email: "[email protected]", percentage_charge: 18.9 }'
5-X PUT
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Subaccount updated",
4 "data": {
5 "integration": 100973,
6 "domain": "test",
7 "subaccount_code": "ACCT_4hl4xenwpjy5wb",
8 "business_name": "Sunshine Studios",
9 "description": null,
10 "primary_contact_name": null,
11 "primary_contact_email": "[email protected]",
12 "primary_contact_phone": null,
13 "metadata": null,
14 "percentage_charge": 18.9,
15 "is_verified": false,
16 "settlement_bank": "Access Bank",
17 "account_number": "0193274682",
18 "settlement_schedule": "AUTO",
19 "active": true,
20 "migrate": false,
21 "id": 55,
22 "createdAt": "2016-10-05T13:22:04.000Z",
23 "updatedAt": "2016-10-21T02:19:47.000Z"
24 }
25}

Plans

The Plans API allows you create and manage installment payment options on your integration

Create a plan on your integration
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Content-TypeStringSet value to application/json
Body Param
nameStringName of plan
amountIntegerAmount should be in kobo if currency is NGN and pesewas for GHS
intervalStringInterval in words. Valid intervals are hourly, daily, weekly, monthly,biannually, annually.
description
String
A description for this plan
send_invoices
Boolean
Set to false if you don't want invoices to be sent to your customers
send_sms
String
Set to false if you don't want text messages to be sent to your customers
currency
String
Currency in which amount is set
invoice_limit
Integer
Number of invoices to raise during subscription to this plan. Can be overridden by specifying an invoice_limit while subscribing.
Show optional parameters
POST/plan
cURL
1curl https://api.paystack.co/plan
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "name": "Monthly retainer", "interval": "monthly", "amount": "500000" }'
5-X POST
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Plan created",
4 "data": {
5 "name": "Monthly retainer",
6 "amount": 500000,
7 "interval": "monthly",
8 "integration": 100032,
9 "domain": "test",
10 "plan_code": "PLN_gx2wn530m0i3w3m",
11 "send_invoices": true,
12 "send_sms": true,
13 "hosted_page": false,
14 "currency": "NGN",
15 "id": 28,
16 "createdAt": "2016-03-29T22:42:50.811Z",
17 "updatedAt": "2016-03-29T22:42:50.811Z"
18 }
19}
List plans available on your integration.
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Query Param
perPageIntegerSpecify how many records you want to retrieve per page. If not specify we use a default value of 50.
pageIntegerSpecify exactly what page you want to retrieve. If not specify we use a default value of 1.
interval
Integer
Filter list by plans with specified interval
amount
Integer
Filter list by plans with specified amount ( kobo if currency is NGN and pesewas for GHS)
Show optional parameters
GET/plan
cURL
1curl https://api.paystack.co/plan
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-X GET
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Plans retrieved",
4 "data": [
5 {
6 "subscriptions": [
7 {
8 "customer": 63,
9 "plan": 27,
10 "integration": 100032,
11 "domain": "test",
12 "start": 1458505748,
13 "status": "complete",
14 "quantity": 1,
15 "amount": 100000,
16 "subscription_code": "SUB_birvokwpp0sftun",
17 "email_token": "9y62mxp4uh25das",
18 "authorization": 79,
19 "easy_cron_id": null,
20 "cron_expression": "0 0 * * 0",
21 "next_payment_date": "2016-03-27T07:00:00.000Z",
22 "open_invoice": null,
23 "id": 8,
24 "createdAt": "2016-03-20T20:29:08.000Z",
25 "updatedAt": "2016-03-22T16:23:52.000Z"
26 }
27 ],
28 "integration": 100032,
29 "domain": "test",
30 "name": "Satin Flower",
31 "plan_code": "PLN_lkozbpsoyd4je9t",
32 "description": null,
33 "amount": 100000,
34 "interval": "weekly",
35 "send_invoices": true,
36 "send_sms": true,
37 "hosted_page": false,
38 "hosted_page_url": null,
39 "hosted_page_summary": null,
40 "currency": "NGN",
41 "id": 27,
42 "createdAt": "2016-03-21T02:44:14.000Z",
43 "updatedAt": "2016-03-21T02:44:14.000Z"
44 },
45 {
46 "subscriptions": [],
47 "integration": 100032,
48 "domain": "test",
49 "name": "Monthly retainer",
50 "plan_code": "PLN_gx2wn530m0i3w3m",
51 "description": null,
52 "amount": 50000,
53 "interval": "monthly",
54 "send_invoices": true,
55 "send_sms": true,
56 "hosted_page": false,
57 "hosted_page_url": null,
58 "hosted_page_summary": null,
59 "currency": "NGN",
60 "id": 28,
61 "createdAt": "2016-03-29T22:42:50.000Z",
62 "updatedAt": "2016-03-29T22:42:50.000Z"
63 }
64 ],
65 "meta": {
66 "total": 2,
67 "skipped": 0,
68 "perPage": 50,
69 "page": 1,
70 "pageCount": 1
71 }
72}
Get details of a plan on your integration.
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Path Param
id_or_codeStringThe plan ID or code you want to fetch
GET/plan/:id_or_code
cURL
1curl https://api.paystack.co/plan/:id_or_code
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-X GET
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Plan retrieved",
4 "data": {
5 "subscriptions": [],
6 "integration": 100032,
7 "domain": "test",
8 "name": "Monthly retainer",
9 "plan_code": "PLN_gx2wn530m0i3w3m",
10 "description": null,
11 "amount": 50000,
12 "interval": "monthly",
13 "send_invoices": true,
14 "send_sms": true,
15 "hosted_page": false,
16 "hosted_page_url": null,
17 "hosted_page_summary": null,
18 "currency": "NGN",
19 "id": 28,
20 "createdAt": "2016-03-29T22:42:50.000Z",
21 "updatedAt": "2016-03-29T22:42:50.000Z"
22 }
23}
Update a plan details on your integration
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Content-TypeStringSet value to application/json
Path param
id_or_codeStringPlan's ID or code
Body Param
nameStringName of plan
amountIntegerAmount should be in kobo if currency is NGN and pesewas for GHS
intervalStringInterval in words. Valid intervals are hourly, daily, weekly, monthly,biannually, annually.
description
String
A description for this plan
send_invoices
Boolean
Set to false if you don't want invoices to be sent to your customers
send_sms
String
Set to false if you don't want text messages to be sent to your customers
currency
String
Currency in which amount is set
invoice_limit
Integer
Number of invoices to raise during subscription to this plan. Can be overridden by specifying an invoice_limit while subscribing.
Show optional parameters
PUT/plan/:id_or_code
cURL
1curl https://api.paystack.co/plan/:id_or_code
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ name: "Monthly retainer (renamed)" }'
5-X PUT
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Plan updated. 1 subscription(s) affected"
4}

Subscriptions

The Subscriptions API allows you create and manage recurring payment on your integration

Create a subscription on your integration
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Content-TypeStringSet value to application/json
Body Param
customerStringCustomer's email address or customer code
planStringPlan code
authorizationStringIf customer has multiple authorizations, you can set the desired authorization you wish to use for this subscription here. If this is not supplied, the customer's most recent authorization would be used
start_date
String
Set the date for the first debit. (ISO 8601 format) e.g. 2017-05-16T00:30:13+01:00
Show optional parameters
Email Token
We create an email token on each subscription to allow customers cancel their subscriptions from within the invoices sent to their mailboxes. Since they are not authorized, the email tokens are what we use to authenticate the requests over the API.
POST/subscription
cURL
1curl https://api.paystack.co/subscription
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "customer": "CUS_xnxdt6s1zg1f4nx", "plan": "PLN_gx2wn530m0i3w3m" }'
5-X POST
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Subscription successfully created",
4 "data": {
5 "customer": 1173,
6 "plan": 28,
7 "integration": 100032,
8 "domain": "test",
9 "start": 1459296064,
10 "status": "active",
11 "quantity": 1,
12 "amount": 50000,
13 "authorization": 79,
14 "subscription_code": "SUB_vsyqdmlzble3uii",
15 "email_token": "d7gofp6yppn3qz7",
16 "id": 9,
17 "createdAt": "2016-03-30T00:01:04.687Z",
18 "updatedAt": "2016-03-30T00:01:04.687Z"
19 }
20}
List subscriptions available on your integration.
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Query Param
perPageIntegerSpecify how many records you want to retrieve per page. If not specify we use a default value of 50.
pageIntegerSpecify exactly what page you want to retrieve. If not specify we use a default value of 1.
customer
Integer
Filter by Customer ID
plan
Integer
Filter by Plan ID
Show optional parameters
GET/subscription
cURL
1curl https://api.paystack.co/subscription
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-X GET
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Subscriptions retrieved",
4 "data": [
5 {
6 "customer": {
7 "first_name": "BoJack",
8 "last_name": "Horseman",
9 "email": "[email protected]",
10 "phone": "",
11 "metadata": null,
12 "domain": "test",
13 "customer_code": "CUS_hdhye17yj8qd2tx",
14 "risk_action": "default",
15 "id": 84312,
16 "integration": 100073,
17 "createdAt": "2016-10-01T10:59:52.000Z",
18 "updatedAt": "2016-10-01T10:59:52.000Z"
19 },
20 "plan": {
21 "domain": "test",
22 "name": "Weekly small chops",
23 "plan_code": "PLN_0as2m9n02cl0kp6",
24 "description": "Small chops delivered every week",
25 "amount": 27000,
26 "interval": "weekly",
27 "send_invoices": true,
28 "send_sms": true,
29 "hosted_page": false,
30 "hosted_page_url": null,
31 "hosted_page_summary": null,
32 "currency": "NGN",
33 "migrate": null,
34 "id": 1716,
35 "integration": 100073,
36 "createdAt": "2016-10-01T10:59:11.000Z",
37 "updatedAt": "2016-10-01T10:59:11.000Z"
38 },
39 "integration": 123456,
40 "authorization": 161811,
41 "domain": "test",
42 "start": 1475319599,
43 "status": "active",
44 "quantity": 1,
45 "amount": 27000,
46 "subscription_code": "SUB_6phdx225bavuwtb",
47 "email_token": "ore84lyuwcv2esu",
48 "easy_cron_id": "275226",
49 "cron_expression": "0 0 * * 6",
50 "next_payment_date": "2016-10-15T00:00:00.000Z",
51 "open_invoice": "INV_qc875pkxpxuyodf",
52 "id": 4192,
53 "createdAt": "2016-10-01T10:59:59.000Z",
54 "updatedAt": "2016-10-12T07:45:14.000Z"
55 }
56 ],
57 "meta": {
58 "total": 1,
59 "skipped": 0,
60 "perPage": 50,
61 "page": 1,
62 "pageCount": 1
63 }
64}
Get details of a subscription on your integration.
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Path Param
id_or_codeStringThe subscription ID or code you want to fetch
GET/subscription/:id_or_code
cURL
1curl https://api.paystack.co/subscription/:id_or_code
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-X GET
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Subscription retrieved successfully",
4 "data": {
5 "invoices": [],
6 "customer": {
7 "first_name": "BoJack",
8 "last_name": "Horseman",
9 "email": "[email protected]",
10 "phone": null,
11 "metadata": {
12 "photos": [
13 {
14 "type": "twitter",
15 "typeId": "twitter",
16 "typeName": "Twitter",
17 "url": "https://d2ojpxxtu63wzl.cloudfront.net/static/61b1a0a1d4dda2c9fe9e165fed07f812_a722ae7148870cc2e33465d1807dfdc6efca33ad2c4e1f8943a79eead3c21311",
18 "isPrimary": false
19 }
20 ]
21 },
22 "domain": "test",
23 "customer_code": "CUS_xnxdt6s1zg1f4nx",
24 "id": 1173,
25 "integration": 100032,
26 "createdAt": "2016-03-29T20:03:09.000Z",
27 "updatedAt": "2016-03-29T20:53:05.000Z"
28 },
29 "plan": {
30 "domain": "test",
31 "name": "Monthly retainer (renamed)",
32 "plan_code": "PLN_gx2wn530m0i3w3m",
33 "description": null,
34 "amount": 50000,
35 "interval": "monthly",
36 "send_invoices": true,
37 "send_sms": true,
38 "hosted_page": false,
39 "hosted_page_url": null,
40 "hosted_page_summary": null,
41 "currency": "NGN",
42 "id": 28,
43 "integration": 100032,
44 "createdAt": "2016-03-29T22:42:50.000Z",
45 "updatedAt": "2016-03-29T23:51:41.000Z"
46 },
47 "integration": 100032,
48 "authorization": {
49 "domain": "test",
50 "authorization_code": "AUTH_5u1q4898",
51 "bin": null,
52 "brand": null,
53 "card_type": "Visa",
54 "last4": "1381",
55 "bank": null,
56 "country_code": null,
57 "country_name": null,
58 "description": "Visa ending with 1381",
59 "mobile": false,
60 "id": 79,
61 "integration": 100032,
62 "customer": 1173,
63 "card": 392,
64 "createdAt": "2016-01-13T01:15:52.000Z",
65 "updatedAt": "2016-01-13T01:15:52.000Z"
66 },
67 "domain": "test",
68 "start": 1459296064,
69 "status": "active",
70 "quantity": 1,
71 "amount": 50000,
72 "subscription_code": "SUB_vsyqdmlzble3uii",
73 "email_token": "d7gofp6yppn3qz7",
74 "easy_cron_id": null,
75 "cron_expression": "0 0 28 * *",
76 "next_payment_date": "2016-04-28T07:00:00.000Z",
77 "open_invoice": null,
78 "id": 9,
79 "createdAt": "2016-03-30T00:01:04.000Z",
80 "updatedAt": "2016-03-30T00:22:58.000Z"
81 }
82}
Enable a subscription on your integration
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Content-TypeStringSet value to application/json
Body Param
codeStringSubscription code
tokenStringEmail token
POST/subscription/enable
cURL
1curl https://api.paystack.co/subscription/enable
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "code": "SUB_vsyqdmlzble3uii", "token": "d7gofp6yppn3qz7" }'
5-X POST
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Subscription enabled successfully"
4}
Disable a subscription on your integration
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Content-TypeStringSet value to application/json
Body Param
codeStringSubscription code
tokenStringEmail token
POST/subscription/disable
cURL
1curl https://api.paystack.co/subscription/disable
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "code": "SUB_vsyqdmlzble3uii", "token": "d7gofp6yppn3qz7" }'
5-X POST
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Subscription disabled successfully"
4}

Products

The Products API allows you create and manage inventories on your integration

Create a product on your integration
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Content-TypeStringSet value to application/json
Body Param
nameStringName of product
descriptionStringA description for this product
priceIntegerPrice should be in kobo if currency is NGN and pesewas for GHS
currencyStringCurrency in which price is set
limited
Boolean
Set to true if the product has limited stock. Leave as false if the product has unlimited stock
quantity
Integer
Number of products in stock. Use if limited is true
Show optional parameters
POST/product
cURL
1curl https://api.paystack.co/product
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "description": "Product Six Description", "name": "Product Six",
5 "price": 500000, "currency": "USD", "limited": false,
6 "quantity": 100
7 }'
8-X POST
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Product successfully created",
4 "data": {
5 "name": "Product One",
6 "description": "Product One Description",
7 "currency": "NGN",
8 "price": 500000,
9 "unlimited": true,
10 "domain": "test",
11 "integration": 343288,
12 "product_code": "PROD_f58aly7bvn32uiz",
13 "quantity": 0,
14 "type": "good",
15 "is_shippable": false,
16 "active": true,
17 "in_stock": true,
18 "id": 524,
19 "createdAt": "2019-06-29T14:10:29.742Z",
20 "updatedAt": "2019-06-29T14:10:29.742Z"
21 }
22}
List products available on your integration.
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Query Param
perPageIntegerSpecify how many records you want to retrieve per page. If not specify we use a default value of 50.
pageIntegerSpecify exactly what page you want to retrieve. If not specify we use a default value of 1.
from
Datetime
A timestamp from which to start listing product e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
to
Datetime
A timestamp at which to stop listing product e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
Show optional parameters
GET/product
cURL
1curl https://api.paystack.co/product
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-X GET
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Products retrieved",
4 "data": [
5 {
6 "integration": 343288,
7 "name": "Product Four",
8 "description": "Product Four Description",
9 "product_code": "PROD_l9p81u9pkjqjunb",
10 "price": 500000,
11 "currency": "NGN",
12 "quantity": 0,
13 "quantity_sold": null,
14 "type": "good",
15 "image_path": "",
16 "file_path": "",
17 "is_shippable": false,
18 "unlimited": true,
19 "domain": "test",
20 "active": true,
21 "features": null,
22 "in_stock": true,
23 "metadata": null,
24 "id": 523,
25 "createdAt": "2019-06-29T14:06:01.000Z",
26 "updatedAt": "2019-06-29T14:06:01.000Z"
27 },
28 {
29 "integration": 343288,
30 "name": "Product Five",
31 "description": "Product Five Description",
32 "product_code": "PROD_8ne9cxutagmtsyz",
33 "price": 500000,
34 "currency": "NGN",
35 "quantity": 0,
36 "quantity_sold": null,
37 "type": "good",
38 "image_path": "",
39 "file_path": "",
40 "is_shippable": false,
41 "unlimited": false,
42 "domain": "test",
43 "active": true,
44 "features": null,
45 "in_stock": false,
46 "metadata": null,
47 "id": 522,
48 "createdAt": "2019-06-29T14:04:50.000Z",
49 "updatedAt": "2019-06-29T14:04:50.000Z"
50 },
51 {
52 "integration": 343288,
53 "name": "Product Three",
54 "description": "Product Three Description",
55 "product_code": "PROD_numva2ypta07syb",
56 "price": 500000,
57 "currency": "NGN",
58 "quantity": 0,
59 "quantity_sold": null,
60 "type": "good",
61 "image_path": "",
62 "file_path": "",
63 "is_shippable": false,
64 "unlimited": false,
65 "domain": "test",
66 "active": true,
67 "features": null,
68 "in_stock": false,
69 "metadata": null,
70 "id": 521,
71 "createdAt": "2019-06-29T14:01:43.000Z",
72 "updatedAt": "2019-06-29T14:01:43.000Z"
73 },
74 {
75 "integration": 343288,
76 "name": "Product Two",
77 "description": "Product Two Description",
78 "product_code": "PROD_byz1ess2lpep67b",
79 "price": 500000,
80 "currency": "NGN",
81 "quantity": 0,
82 "quantity_sold": null,
83 "type": "good",
84 "image_path": "",
85 "file_path": "",
86 "is_shippable": false,
87 "unlimited": true,
88 "domain": "test",
89 "active": true,
90 "features": null,
91 "in_stock": false,
92 "metadata": null,
93 "id": 520,
94 "createdAt": "2019-06-29T14:01:18.000Z",
95 "updatedAt": "2019-06-29T14:01:18.000Z"
96 },
97 {
98 "integration": 343288,
99 "name": "Product One",
100 "description": "Product One Description",
101 "product_code": "PROD_qcie3smv3zxf4vz",
102 "price": 500000,
103 "currency": "NGN",
104 "quantity": 10,
105 "quantity_sold": null,
106 "type": "good",
107 "image_path": "",
108 "file_path": "",
109 "is_shippable": false,
110 "unlimited": false,
111 "domain": "test",
112 "active": true,
113 "features": null,
114 "in_stock": true,
115 "metadata": null,
116 "id": 519,
117 "createdAt": "2019-06-29T13:52:42.000Z",
118 "updatedAt": "2019-06-29T13:52:42.000Z"
119 }
120 ],
121 "meta": {
122 "total": 5,
123 "skipped": 0,
124 "perPage": 50,
125 "page": 1,
126 "pageCount": 1
127 }
128}
Get details of a product on your integration.
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Path Param
idStringThe product ID you want to fetch
GET/product/:id
cURL
1curl https://api.paystack.co/product/:id
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-X GET
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Product retrieved",
4 "data": {
5 "integration": 343288,
6 "name": "Prod 1",
7 "description": "Prod 1",
8 "product_code": "PROD_ohc0xq1ajpt2271",
9 "price": 20000,
10 "currency": "NGN",
11 "quantity": 5,
12 "quantity_sold": null,
13 "type": "good",
14 "image_path": "",
15 "file_path": "",
16 "is_shippable": false,
17 "unlimited": false,
18 "domain": "test",
19 "active": true,
20 "features": null,
21 "in_stock": true,
22 "metadata": null,
23 "id": 526,
24 "createdAt": "2019-06-29T14:46:52.000Z",
25 "updatedAt": "2019-06-29T14:46:52.000Z"
26 }
27}
Update a product details on your integration
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Content-TypeStringSet value to application/json
Query Param
idStringProduct ID
Body Param
nameStringName of product
descriptionStringA description for this product
priceIntegerPrice should be in kobo if currency is NGN and pesewas for GHS
currencyStringCurrency in which price is set
limited
Boolean
Set to true if the product has limited stock. Leave as false if the product has unlimited stock
quantity
Integer
Number of products in stock. Use if limited is true
Show optional parameters
PUT/product/:id
cURL
1curl https://api.paystack.co/product/:id
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "description": "Product Six Description", "name": "Product Six",
5 "price": 500000, "currency": "USD", "limited": false,
6 "quantity": 100
7 }'
8-X PUT
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Product successfully updated",
4 "data": {
5 "name": "Prod One",
6 "description": "Prod 1",
7 "product_code": "PROD_ohc0xq1ajpt2271",
8 "price": 20000,
9 "currency": "NGN",
10 "quantity": 5,
11 "quantity_sold": null,
12 "type": "good",
13 "image_path": "",
14 "file_path": "",
15 "is_shippable": false,
16 "unlimited": false,
17 "domain": "test",
18 "active": true,
19 "features": null,
20 "in_stock": true,
21 "metadata": null,
22 "id": 526,
23 "integration": 343288,
24 "createdAt": "2019-06-29T14:46:52.000Z",
25 "updatedAt": "2019-06-29T15:29:21.000Z"
26 }
27}

Payment Pages

The Payment Pages API provides a quick and secure way to collect payment for products.

Create a payment page on your integration
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Content-TypeStringSet value to application/json
Body Param
nameStringName of page
description
String
A description for this page
amount
Integer
Amount should be in kobo if currency is NGN and pesewas for GHS
slug
String
URL slug you would like to be associated with this page. Page will be accessible at https://paystack.com/pay/[slug]
metadata
Object
Extra data to configure the payment page including subaccount, logo image, transaction charge
redirect_url
String
If you would like Paystack to redirect someplace upon successful payment, specify the URL here.
custom_fields
Array of Objects
If you would like to accept custom fields, specify them here. See sample code for details.
Show optional parameters
POST/page
cURL
1curl https://api.paystack.co/page
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "name": "Buttercup Brunch", "amount": 500000
5 "description": "Gather your friends for the ritual that is brunch",
6 }'
7-X POST
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Page created",
4 "data": {
5 "name": "Buttercup Brunch",
6 "description": "Gather your friends for the ritual that is brunch",
7 "integration": 100032,
8 "domain": "test",
9 "slug": "5nApBwZkvY",
10 "currency": "NGN",
11 "active": true,
12 "id": 18,
13 "createdAt": "2016-03-30T00:49:57.514Z",
14 "updatedAt": "2016-03-30T00:49:57.514Z"
15 }
16}
List payment pages available on your integration.
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Query Param
perPageIntegerSpecify how many records you want to retrieve per page. If not specify we use a default value of 50.
pageIntegerSpecify exactly what page you want to retrieve. If not specify we use a default value of 1.
from
Datetime
A timestamp from which to start listing page e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
to
Datetime
A timestamp at which to stop listing page e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
Show optional parameters
GET/page
cURL
1curl https://api.paystack.co/page
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-X GET
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Pages retrieved",
4 "data": [
5 {
6 "integration": 100073,
7 "plan": 1716,
8 "domain": "test",
9 "name": "Subscribe to plan: Weekly small chops",
10 "description": null,
11 "amount": null,
12 "currency": "NGN",
13 "slug": "sR7Ohx2iVd",
14 "custom_fields": null,
15 "redirect_url": null,
16 "active": true,
17 "migrate": null,
18 "id": 2223,
19 "createdAt": "2016-10-01T10:59:11.000Z",
20 "updatedAt": "2016-10-01T10:59:11.000Z"
21 },
22 {
23 "integration": 100073,
24 "plan": null,
25 "domain": "test",
26 "name": "Special",
27 "description": "Special page",
28 "amount": 10000,
29 "currency": "NGN",
30 "slug": "special-me",
31 "custom_fields": [
32 {
33 "display_name": "Speciality",
34 "variable_name": "speciality"
35 },
36 {
37 "display_name": "Age",
38 "variable_name": "age"
39 }
40 ],
41 "redirect_url": "http://special.url",
42 "active": true,
43 "migrate": null,
44 "id": 1807,
45 "createdAt": "2016-09-09T19:18:37.000Z",
46 "updatedAt": "2016-09-14T17:51:49.000Z"
47 }
48 ],
49 "meta": {
50 "total": 2,
51 "skipped": 0,
52 "perPage": "3",
53 "page": 1,
54 "pageCount": 1
55 }
56}
Get details of a payment page on your integration.
Headers
AuthorizationStringSet value to Bearer SECRET_KEY
Path Param
id_or_slugStringThe page ID or slug you want to fetch
GET/page/:id_or_slug
cURL
1curl https://api.paystack.co/page/:id_or_slug
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-X GET
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Page retrieved",
4 "data": {
5 "integration": 100032,
6 "domain": "test",
7 "name": "Offering collections",
8 "description": "Give unto the Lord, and it shall be multiplied ten-fold to you.",
9 "amount": null,
10 "currency": "NGN",
11 "slug": "5nApBwZkvY",
12 "active": true,
13 "id": 18,
14 "createdAt": "2016-03-30T00:49:57.000Z",
15 "updatedAt": "2016-03-30T00:49:57.000Z",
16 "products": [
17 {
18 "product_id": 523,
19 "name": "Product Four",
20 "description": "Product Four Description",
21 "product_code": "PROD_l9p81u9pkjqjunb",
22 "page": 18,
23 "price": 500000,
24 "currency": "NGN",
25 "quantity": 0,
26 "type": "good",
27 "features": null,
28 "is_shippable": 0,
29 "domain": "test",
30 "integration": 343288,
31 "active": 1,
32 "in_stock": 1
33 },
34 {
35 "product_id": 522,
36 "name": "Product Five",
37 "description": "Product Five Description",
38 "product_code": "PROD_8ne9cxutagmtsyz",
39 "page": 18,
40 "price": 500000,
41 "currency": "NGN",
42 "quantity": 0,
43 "type": "