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
Total
Number
This is the total number of transactions that were performed by the customer.
Skipped
Number
This is the number of records skipped before the first record in the array returned.
PerPage
Number
This is the maximum number of records that will be returned per request. This can be modified by passing a new value as a perPage query parameter. Default: 50
Page
Number
This is the current page being returned. This is dependent on what page was requested using the page query parameter. Default: 1
PageCount
Number
This 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, 201
Request 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).
400
A validation or client side error occurred and the request was not fulfilled.
401
The request was not authorized. This can be triggered by passing an invalid secret key in the authorization header or the lack of one
404
Request could not be fulfilled as the request resource does not exist.
500, 501, 502, 503, 504
Request 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
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Body Param
amount
String
Amount should be in kobo if currency is NGN, pesewas, if currency is GHS, and cents, if currency is ZAR
email
String
Customer's email address
currency
String
The transaction currency (NGN, GHS, ZAR 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 of custom data. Kindly check the Metadata page for more information.
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']
split_code
String
The split code of the transaction split. e.g. SPL_98WF13Eb3w
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 (). 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
authorization
String
Set value to Bearer SECRET_KEY
Path Param
reference
String
The 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 "account_name": "BoJack Horseman"
61 },
62 "customer": {
63 "id": 84312,
64 "customer_code": "CUS_hdhye17yj8qd2tx",
65 "first_name": "BoJack",
66 "last_name": "Horseman",
67 "email": "[email protected]"
68 },
69 "plan": "PLN_0as2m9n02cl0kp6",
70 "requested_amount": 1500000
71 }
72}
List transactions carried out on your integration.
Headers
authorization
String
Set value to Bearer SECRET_KEY
Query Param
perPage
Integer
Specify how many records you want to retrieve per page. If not specify we use a default value of 50.
page
Integer
Specify 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, pesewas, if currency is GHS, and cents, if currency is ZAR)
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 "account_name": "BoJack Horseman"
66 },
67 "customer": {
68 "id": 8279,
69 "first_name": "Ezra",
70 "last_name": "Olubi",
71 "email": "[email protected]",
72 "phone": "16504173147",
73 "customer_code": "CUS_1uld4hluw0g2gn0",
74 "metadata": null,
75 "risk_action": "default"
76 },
77 "requested_amount": 10000
78 }],
79 "meta": {
80 "total": 1,
81 "skipped": 0,
82 "perPage": 50,
83 "page": 1,
84 "pageCount": 1
85 }
86}
Get details of a transaction carried out on your integration.
Headers
authorization
String
Set value to Bearer SECRET_KEY
Path Param
id
Integer
An 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 "account_name": "BoJack Horseman"
64 },
65 "customer": {
66 "id": 1809887,
67 "first_name": null,
68 "last_name": null,
69 "email": "[email protected]",
70 "customer_code": "CUS_0c35ys9w8ma5tbr",
71 "phone": null,
72 "metadata": null,
73 "risk_action": "deny"
74 },
75 "plan": {},
76 "subaccount": {},
77 "order_id": null,
78 "paidAt": "2019-10-09T13:03:28.000Z",
79 "createdAt": "2019-10-09T13:00:16.000Z",
80 "requested_amount": 1500000
81 }
82}
All authorizations marked as reusable can be charged with this endpoint whenever you need to receive payments.
Headers
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Body Param
amount
String
Amount should be in kobo if currency is NGN, pesewas, if currency is GHS, and cents, if currency is ZAR
email
String
Customer's email address
authorization_code
String
Valid authorization code to charge
reference
String
Unique transaction reference. Only -, ., = and alphanumeric characters allowed.
currency
String
Currency in which amount should be charged. Allowed values are: NGN, GHS, ZAR or USD
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, pesewas, if currency is GHS, and cents, if currency is ZAR). 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": "mai[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
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Body Param
amount
String
Amount should be in kobo if currency is NGN, pesewas, if currency is GHS, and cents, if currency is ZAR
email
String
Customer's email address
authorization_code
String
Valid authorization code to charge
currency
String
Currency in which amount should be charged. Allowed values are: NGN, GHS, ZAR or USD
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
authorization
String
Set value to Bearer SECRET_KEY
Path Param
id_or_reference
String
The 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
authorization
String
Set value to Bearer SECRET_KEY
Path Param
perPage
Integer
Specify how many records you want to retrieve per page. If not specify we use a default value of 50.
page
Integer
Specify 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
authorization
String
Set value to Bearer SECRET_KEY
Query Param
perPage
Integer
Specify how many records you want to retrieve per page. If not specify we use a default value of 50.
page
Integer
Specify 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. Allowed values are: in kobo if currency is NGN, pesewas, if currency is GHS, and cents, if currency is ZAR
amount
Integer
Filter transactions by amount. Specify the amount, in kobo if currency is NGN, pesewas, if currency is GHS, and cents, if currency is ZAR
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
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Body Param
authorization_code
String
Authorization Code
currency
String
Specify the currency you want to debit. Allowed values are NGN, GHS, ZAR or USD.
amount
String
Amount should be in kobo if currency is NGN, pesewas, if currency is GHS, and cents, if currency is ZAR
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 '{
5 "authorization_code": "AUTH_72btv547",
6 "currency": "NGN",
7 "amount": "20000",
8 "email": "[email protected]"
9 }'
10-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_72btv547",
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 "account_name": "BoJack Horseman"
32 },
33 "customer": {
34 "id": 16702,
35 "first_name": "",
36 "last_name": "",
37 "email": "[email protected]",
38 "customer_code": "CUS_096t7vsogztygg4",
39 "phone": "",
40 "metadata": null,
41 "risk_action": "default"
42 },
43 "plan": 0,
44 "amount": 2000
45 }
46}

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
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Body Param
name
String
Name of the transaction split
type
String
The type of transaction split you want to create. You can use one of the following: percentage | flat
currency
String
Any of NGN, GHS, ZAR, or USD
subaccounts
Array
A list of object containing subaccount code and number of shares: [{subaccount_code: ‘ACT_xxxxxxxxxx’, share: xxx},{...}]
bearer_type
String
Any of subaccount | account | all-proportional | all
bearer_subaccount
String
Subaccount code
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 }'
18-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
authorization
String
Set value to Bearer SECRET_KEY
Query Param
name
String
The name of the split
active
Boolean
Any 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
authorization
String
Set value to Bearer SECRET_KEY
Path Param
id
String
The 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
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Path Param
id
String
Split ID
Body Param
name
String
Name of the transaction split
active
Boolean
True or False
bearer_type
String
Any of the following values: subaccount | account | all-proportional | all
subaccount
String
Subaccount code of a subaccount in the split group. This should be specified only if the bearer_type is subaccount
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
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Path Param
id
String
Split Id
Body Param
subaccount
String
This is the sub account code
share
Integer
This 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
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Path Param
id
String
Split Id
Body Param
subaccount
String
This 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
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Body Param
email
String
Customer's email address
first_name
String
Customer's first name
last_name
String
Customer'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 "identified": false,
11 "identifications":null,
12 "createdAt": "2016-03-29T20:03:09.584Z",
13 "updatedAt": "2016-03-29T20:03:09.584Z"
14 }
15}
List customers available on your integration.
Headers
authorization
String
Set value to Bearer SECRET_KEY
Query Param
perPage
Integer
Specify how many records you want to retrieve per page. If not specify we use a default value of 50.
page
Integer
Specify 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
authorization
String
Set value to Bearer SECRET_KEY
Path Param
email_or_code
String
An 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 "identified": true,
11 "identifications": [{
12 "country": "NG",
13 "type": "bvn",
14 "value": "200*****677"
15 }],
16 "metadata": {
17 "photos": [
18 {
19 "type": "twitter",
20 "typeId": "twitter",
21 "typeName": "Twitter",
22 "url": "https://d2ojpxxtu63wzl.cloudfront.net/static/61b1a0a1d4dda2c9fe9e165fed07f812_a722ae7148870cc2e33465d1807dfdc6efca33ad2c4e1f8943a79eead3c21311",
23 "isPrimary": true
24 }
25 ]
26 "domain": "test",
27 "customer_code": "CUS_xnxdt6s1zg1f4nx",
28 "id": 1173,
29 "transactions": [],
30 "subscriptions": [],
31 "authorizations": [],
32 "createdAt": "2016-03-29T20:03:09.000Z",
33 "updatedAt": "2016-03-29T20:03:10.000Z"
34 }
35}
Update a customer's details on your integration
Headers
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Query Param
code
String
Customer's code
Body Param
first_name
String
Customer's first name
last_name
String
Customer'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 "identified": false,
22 "identifications":null,
23 "domain": "test",
24 "customer_code": "CUS_xnxdt6s1zg1f4nx",
25 "id": 1173,
26 "transactions": [],
27 "subscriptions": [],
28 "authorizations": [],
29 "createdAt": "2016-03-29T20:03:09.000Z",
30 "updatedAt": "2016-03-29T20:03:10.000Z"
31 }
32}
Validate a customer's identity
Headers
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Body Param
first_name
String
Customer's first name
last_name
String
Customer's last name
type
String
Predefined types of identification. Valid values: bvn
value
String
Customer's identification number
country
String
2 letter country code of identification issuer
POST/customer/:code/identification
cURL
1curl https://api.paystack.co/customer/{customer_code}/identification
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{
5 "country": "NG",
6 "type": "bvn",
7 "value": "200123456677",
8 "first_name": "Asta",
9 "last_name": "Lavista"
10}'
11-X POST
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Customer Identification in progress"
4}
Whitelist or blacklist a customer on your integration
Headers
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Body Param
customer
String
Customer'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 "identified": false,
12 "identifications": null,
13 "customer_code": "CUS_xr58yrr2ujlft9k",
14 "risk_action": "allow",
15 "id": 2109,
16 "integration": 100032,
17 "createdAt": "2016-01-26T13:43:38.000Z",
18 "updatedAt": "2016-08-23T03:56:43.000Z"
19 }
20}
Deactivate an authorization when the card needs to be forgotten
Headers
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Body Param
authorization_code
String
Authorization 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 has been deactivated"
4}

Dedicated NUBAN

The Dedicated NUBAN API enables Nigerian merchants manage unique payment accounts of their cuctomers.

Feature Availability
This feature is only available to businesses in Nigeria.
Create a Dedicated NUBAN and assign to a customer
Bank Availability
We currently support Access Bank and Wema Bank.
Headers
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Body Param
customer
String
Customer ID or code
preferred_bank
String
The bank slug for preferred bank. To get a list of available banks, use the List Providers endpoint
subaccount
String
Subaccount code of the account you want to split the transaction with
split_code
String
Split code consisting of the lists of accounts you want to split the transaction with
Show optional parameters
POST/dedicated_account
cURL
1curl https://api.paystack.co/dedicated_account
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "customer":481193,"preferred_bank":"wema-bank" }'
5-X POST
Sample Response
200 OK
1{
2 "status": true,
3 "message": "NUBAN successfully created",
4 "data": {
5 "bank": {
6 "name": "Wema Bank",
7 "id": 20,
8 "slug": "wema-bank"
9 },
10 "account_name": "KAROKART / RHODA CHURCH",
11 "account_number": "9930000737",
12 "assigned": true,
13 "currency": "NGN",
14 "metadata": null,
15 "active": true,
16 "id": 253,
17 "created_at": "2019-12-12T12:39:04.000Z",
18 "updated_at": "2020-01-06T15:51:24.000Z",
19 "assignment": {
20 "integration": 100043,
21 "assignee_id": 7454289,
22 "assignee_type": "Customer",
23 "expired": false,
24 "account_type": "PAY-WITH-TRANSFER-RECURRING",
25 "assigned_at": "2020-01-06T15:51:24.764Z"
26 },
27 "customer": {
28 "id": 7454289,
29 "first_name": "RHODA",
30 "last_name": "CHURCH",
31 "email": "[email protected]",
32 "customer_code": "CUS_kpb3qj71u1m0rw8",
33 "phone": "+2349053267565",
34 "risk_action": "default"
35 }
36 }
37}
List dedicated accounts available on your integration.
Headers
authorization
String
Set value to Bearer SECRET_KEY
Query Param
active
Boolean
Status of the dedicated account
currency
String
Dedicated amount currency
provider_slug
String
The bank's slug in lowercase, without spaces e.g. wema-bank
bank_id
String
The bank's ID e.g. 035
customer
String
The customer's ID
Show optional parameters
GET/dedicated_account
cURL
1curl https://api.paystack.co/dedicated_account
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-X GET
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Managed accounts successfully retrieved",
4 "data": [{
5 "customer": {
6 "id": 1530104,
7 "first_name": "yinka",
8 "last_name": "Ojo",
9 "email": "[email protected]",
10 "customer_code": "CUS_dy1r7ts03zixbq5",
11 "phone": "08154239386",
12 "risk_action": "default",
13 "international_format_phone": null
14 },
15 "bank": {
16 "name": "Wema Bank",
17 "id": 20,
18 "slug": "wema-bank"
19 },
20 "id": 173,
21 "account_name": "KAROKART/A YINKA",
22 "account_number": "9930020212",
23 "created_at": "2019-12-09T13:31:38.000Z",
24 "updated_at": "2020-06-11T14:04:28.000Z",
25 "currency": "NGN",
26 "split_config": {
27 "subaccount": "ACCT_xdrne0tcvr5jkei"
28 },
29 "active": true,
30 "assigned": true
31 }],
32 "meta": {
33 "total": 1,
34 "skipped": 0,
35 "perPage": 50,
36 "page": 1,
37 "pageCount": 1
38 }
39}
Get details of a dedicated account on your integration.
Headers
authorization
String
Set value to Bearer SECRET_KEY
Path Param
dedicated_account_id
Integer
ID of dedicated account
GET/dedicated_account/:dedicated_account_id
cURL
1curl https://api.paystack.co/dedicated_account/:dedicated_account_id
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 "transactions": [],
6 "subscriptions": [],
7 "authorizations": [],
8 "first_name": null,
9 "last_name": null,
10 "email": "[email protected]",
11 "phone": null,
12 "metadata": null,
13 "domain": "live",
14 "customer_code": "CUS_h00a7ngn0xbzf2g",
15 "risk_action": "default",
16 "id": 17593,
17 "integration": 190972,
18 "createdAt": "2019-10-25T15:05:23.000Z",
19 "updatedAt": "2019-10-25T15:05:23.000Z",
20 "created_at": "2019-10-25T15:05:23.000Z",
21 "updated_at": "2019-10-25T15:05:23.000Z",
22 "total_transactions": 0,
23 "total_transaction_value": [],
24 "dedicated_account": {
25 "id": 59,
26 "account_name": "KAROKART/RHODA CHURCH",
27 "account_number": "9807062474",
28 "created_at": "2019-09-10T11:10:12.000Z",
29 "updated_at": "2019-10-25T15:05:24.000Z",
30 "currency": "NGN",
31 "active": true,
32 "assigned": true,
33 "provider": {
34 "id": 1,
35 "provider_slug": "wema-bank",
36 "bank_id": 20,
37 "bank_name": "Wema Bank"
38 },
39 "assignment": {
40 "assignee_id": 17593,
41 "assignee_type": "Customer",
42 "account_type": "PAY-WITH-TRANSFER-RECURRING",
43 "integration": 190972
44 }
45 }
46 }
47}
Deactivate a dedicated account on your integration.
Headers
authorization
String
Set value to Bearer SECRET_KEY
Path Param
dedicated_account_id
Integer
ID of dedicated account
DEL/dedicated_account/:dedicated_account_id
cURL
1curl https://api.paystack.co/dedicated_account/:dedicated_account_id
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-X DELETE
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Managed Account Successfully Unassigned",
4 "data": {
5 "bank": {
6 "name": "Wema Bank",
7 "id": 20,
8 "slug": "wema-bank"
9 },
10 "account_name": "KAROKART/A YINKA",
11 "account_number": "9930020212",
12 "assigned": false,
13 "currency": "NGN",
14 "metadata": null,
15 "active": true,
16 "id": 173,
17 "created_at": "2019-12-09T13:31:38.000Z",
18 "updated_at": "2020-08-28T10:04:25.000Z",
19 "assignment": {
20 "assignee_id": 1530104,
21 "assignee_type": "Integration",
22 "assigned_at": "2019-12-09T13:40:21.000Z",
23 "integration": 100043,
24 "account_type": "PAY-WITH-TRANSFER-RECURRING"
25 }
26 }
27}
Split a dedicated account transaction with one or more accounts
Headers
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Body Param
customer
String
Customer ID or code
subaccount
String
Subaccount code of the account you want to split the transaction with
split_code
String
Split code consisting of the lists of accounts you want to split the transaction with
preferred_bank
String
The bank slug for preferred bank. To get a list of available banks, use the List Providers endpoint
Show optional parameters
POST/dedicated_account/split
cURL
1curl https://api.paystack.co/dedicated_account
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "customer": 481193, "preferred_bank":"wema-bank",
5 "split_code": "SPL_e7jnRLtzla"
6 }'
7-X POST
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Assigned Managed Account Successfully Created",
4 "data": {
5 "bank": {
6 "name": "Wema Bank",
7 "id": 20,
8 "slug": "wema-bank"
9 },
10 "account_name": "KAROKART/YINKA ADE",
11 "account_number": "6731105168",
12 "assigned": true,
13 "currency": "NGN",
14 "metadata": null,
15 "active": true,
16 "id": 97,
17 "created_at": "2019-11-13T13:52:39.000Z",
18 "updated_at": "2020-03-17T07:52:23.000Z",
19 "assignment": {
20 "integration": 100043,
21 "assignee_id": 17328,
22 "assignee_type": "Customer",
23 "expired": false,
24 "account_type": "PAY-WITH-TRANSFER-RECURRING",
25 "assigned_at": "2020-03-17T07:52:23.023Z",
26 "expired_at": null
27 },
28 "split_config": {"split_code":"SPL_e7jnRLtzla"},
29 "customer": {
30 "id": 17328,
31 "first_name": "YINKA",
32 "last_name": "ADE",
33 "email": "[email protected]",
34 "customer_code": "CUS_xxxxxxxx",
35 "phone": null,
36 "metadata": null,
37 "risk_action": "default"
38 }
39 }
40}
If you've previously set up split payment for transactions on a dedicated account, you can remove it with this endpoint
Headers
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Body Param
account_number
String
Dedicated Account Number
DEL/dedicated_account/split
cURL
1curl https://api.paystack.co/dedicated_account/split
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "account_number": "0033322211" }'
5-X DELETE
Sample Response
200 OK
1{
2 "status": "success",
3 "message": "Subaccount unassigned",
4 "data": {
5 "id": 22173,
6 "split_config": NULL,
7 "account_name": "KAROKART/YINKA ADE",
8 "account_number": "0033322211",
9 "currency": "NGN",
10 "assigned": true,
11 "active": true,
12 "createdAt": "2020-03-11T15:14:00.707Z",
13 "updatedAt": "2020-03-11T15:14:00.707Z",
14 }
15}
Get available bank providers for Dedicated NUBAN
Headers
authorization
String
Set value to Bearer SECRET_KEY
GET/dedicated_account/available_providers
cURL
1curl https://api.paystack.co/dedicated_account/available_providers
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-X GET
Sample Response
200 OK
1{
2 "status": true,
3 "message": "Dedicated account providers retrieved",
4 "data": [
5 {
6 "provider_slug": "access-bank",
7 "bank_id": 1,
8 "bank_name": "Access Bank",
9 "id": 6
10 },
11 {
12 "provider_slug": "wema-bank",
13 "bank_id": 20,
14 "bank_name": "Wema Bank",
15 "id": 5
16 }
17
18 ]
19}

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
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Body Param
business_name
String
Name of business for subaccount
settlement_bank
String
Bank Code for the bank. You can get the list of Bank Codes by calling the List Banks endpoint.
account_number
String
Bank Account Number
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
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
authorization
String
Set value to Bearer SECRET_KEY
Query Param
perPage
Integer
Specify how many records you want to retrieve per page. If not specify we use a default value of 50.
page
Integer
Specify 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
authorization
String
Set value to Bearer SECRET_KEY
Path Param
id_or_code
String
The 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
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Headers
id_or_code
String
Subaccount's ID or code
Body Param
business_name
String
Name of business for subaccount
settlement_bank
String
Bank Code for the bank. You can get the list of Bank Codes by calling the List Banks endpoint.
account_number
String
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
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Body Param
name
String
Name of plan
amount
Integer
Amount should be in kobo if currency is NGN, pesewas, if currency is GHS, and cents, if currency is ZAR
interval
String
Interval in words. Valid intervals are: 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. Allowed values are NGN, GHS, ZAR or USD
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
authorization
String
Set value to Bearer SECRET_KEY
Query Param
perPage
Integer
Specify how many records you want to retrieve per page. If not specify we use a default value of 50.
page
Integer
Specify 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, pesewas, if currency is GHS, and cents, if currency is ZAR)
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": {
19 "authorization_code": "AUTH_6tmt288t0o",
20 "bin": "408408",
21 "last4": "4081",
22 "exp_month": "12",
23 "exp_year": "2020",
24 "channel": "card",
25 "card_type": "visa visa",
26 "bank": "TEST BANK",
27 "country_code": "NG",
28 "brand": "visa",
29 "reusable": true,
30 "signature": "SIG_uSYN4fv1adlAuoij8QXh",
31 "account_name": "BoJack Horseman"
32 },
33 "easy_cron_id": null,
34 "cron_expression": "0 0 * * 0",
35 "next_payment_date": "2016-03-27T07:00:00.000Z",
36 "open_invoice": null,
37 "id": 8,
38 "createdAt": "2016-03-20T20:29:08.000Z",
39 "updatedAt": "2016-03-22T16:23:52.000Z"
40 }
41 ],
42 "integration": 100032,
43 "domain": "test",
44 "name": "Satin Flower",
45 "plan_code": "PLN_lkozbpsoyd4je9t",
46 "description": null,
47 "amount": 100000,
48 "interval": "weekly",
49 "send_invoices": true,
50 "send_sms": true,
51 "hosted_page": false,
52 "hosted_page_url": null,
53 "hosted_page_summary": null,
54 "currency": "NGN",
55 "id": 27,
56 "createdAt": "2016-03-21T02:44:14.000Z",
57 "updatedAt": "2016-03-21T02:44:14.000Z"
58 },
59 {
60 "subscriptions": [],
61 "integration": 100032,
62 "domain": "test",
63 "name": "Monthly retainer",
64 "plan_code": "PLN_gx2wn530m0i3w3m",
65 "description": null,
66 "amount": 50000,
67 "interval": "monthly",
68 "send_invoices": true,
69 "send_sms": true,
70 "hosted_page": false,
71 "hosted_page_url": null,
72 "hosted_page_summary": null,
73 "currency": "NGN",
74 "id": 28,
75 "createdAt": "2016-03-29T22:42:50.000Z",
76 "updatedAt": "2016-03-29T22:42:50.000Z"
77 }
78 ],
79 "meta": {
80 "total": 2,
81 "skipped": 0,
82 "perPage": 50,
83 "page": 1,
84 "pageCount": 1
85 }
86}
Get details of a plan on your integration.
Headers
authorization
String
Set value to Bearer SECRET_KEY
Path Param
id_or_code
String
The 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
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Path param
id_or_code
String
Plan's ID or code
Body Param
name
String
Name of plan
amount
Integer
Amount should be in kobo if currency is NGN and pesewas for GHS
interval
String
Interval 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. Any of NGN, GHS, ZAR or USD
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
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Body Param
customer
String
Customer's email address or customer code
plan
String
Plan code
authorization
String
If 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": {
14 "authorization_code": "AUTH_6tmt288t0o",
15 "bin": "408408",
16 "last4": "4081",
17 "exp_month": "12",
18 "exp_year": "2020",
19 "channel": "card",
20 "card_type": "visa visa",
21 "bank": "TEST BANK",
22 "country_code": "NG",
23 "brand": "visa",
24 "reusable": true,
25 "signature": "SIG_uSYN4fv1adlAuoij8QXh",
26 "account_name": "BoJack Horseman"
27 },
28 "subscription_code": "SUB_vsyqdmlzble3uii",
29 "email_token": "d7gofp6yppn3qz7",
30 "id": 9,
31 "createdAt": "2016-03-30T00:01:04.687Z",
32 "updatedAt": "2016-03-30T00:01:04.687Z"
33 }
34}
List subscriptions available on your integration.
Headers
authorization
String
Set value to Bearer SECRET_KEY
Query Param
perPage
Integer
Specify how many records you want to retrieve per page. If not specify we use a default value of 50.
page
Integer
Specify 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": {
41 "authorization_code": "AUTH_6tmt288t0o",
42 "bin": "408408",
43 "last4": "4081",
44 "exp_month": "12",
45 "exp_year": "2020",
46 "channel": "card",
47 "card_type": "visa visa",
48 "bank": "TEST BANK",
49 "country_code": "NG",
50 "brand": "visa",
51 "reusable": true,
52 "signature": "SIG_uSYN4fv1adlAuoij8QXh",
53 "account_name": "BoJack Horseman"
54 },
55 "domain": "test",
56 "start": 1475319599,
57 "status": "active",
58 "quantity": 1,
59 "amount": 27000,
60 "subscription_code": "SUB_6phdx225bavuwtb",
61 "email_token": "ore84lyuwcv2esu",
62 "easy_cron_id": "275226",
63 "cron_expression": "0 0 * * 6",
64 "next_payment_date": "2016-10-15T00:00:00.000Z",
65 "open_invoice": "INV_qc875pkxpxuyodf",
66 "id": 4192,
67 "createdAt": "2016-10-01T10:59:59.000Z",
68 "updatedAt": "2016-10-12T07:45:14.000Z"
69 }
70 ],
71 "meta": {
72 "total": 1,
73 "skipped": 0,
74 "perPage": 50,
75 "page": 1,
76 "pageCount": 1
77 }
78}
Get details of a subscription on your integration.
Headers
authorization
String
Set value to Bearer SECRET_KEY
Path Param
id_or_code
String
The 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 "authorization_code": "AUTH_6tmt288t0o",
50 "bin": "408408",
51 "last4": "4081",
52 "exp_month": "12",
53 "exp_year": "2020",
54 "channel": "card",
55 "card_type": "visa visa",
56 "bank": "TEST BANK",
57 "country_code": "NG",
58 "brand": "visa",
59 "reusable": true,
60 "signature": "SIG_uSYN4fv1adlAuoij8QXh",
61 "account_name": "BoJack Horseman"
62 },
63 "domain": "test",
64 "start": 1459296064,
65 "status": "active",
66 "quantity": 1,
67 "amount": 50000,
68 "subscription_code": "SUB_vsyqdmlzble3uii",
69 "email_token": "d7gofp6yppn3qz7",
70 "easy_cron_id": null,
71 "cron_expression": "0 0 28 * *",
72 "next_payment_date": "2016-04-28T07:00:00.000Z",
73 "open_invoice": null,
74 "id"