Paystack

The Paystack Developer Documentation

Welcome to the Paystack Developer Documentation.

You'll find comprehensive guides and documentation to help you start working with Paystack as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussion
Suggest Edits

Paystack Inline

 

NOT RECOMMENDED IF THERE IS A RISK THAT UNSCRUPULOUS CUSTOMERS WILL TAMPER WITH INITIALIZATION INFORMATION

Paystack Inline offers a simple, secure and convenient payment flow for web and mobile. It can be integrated with a line of code thereby making it the easiest way to start accepting payments. It also makes it possible to start and end the payment flow on the same page, thus combating redirect fatigue.

Working with Paystack Inline

Here is a sample code that calls Paystack and also handles outcome.

Key

Please note that the key to use with inline is the public key and not the secret key

<form >
  <script src="https://js.paystack.co/v1/inline.js"></script>
  <button type="button" onclick="payWithPaystack()"> Pay </button> 
</form>
 
<script>
  function payWithPaystack(){
    var handler = PaystackPop.setup({
      key: 'pk_test_86d32aa1nV4l1da7120ce530f0b221c3cb97cbcc',
      email: 'customer@email.com',
      amount: 10000,
      ref: ''+Math.floor((Math.random() * 1000000000) + 1), // generates a pseudo-unique reference. Please replace with a reference you generated. Or remove the line entirely so our API will generate one for you
      firstname: 'Stephen',
      lastname: 'King',
      // label: "Optional string that replaces customer email"
      metadata: {
         custom_fields: [
            {
                display_name: "Mobile Number",
                variable_name: "mobile_number",
                value: "+2348012345678"
            }
         ]
      },
      callback: function(response){
          alert('success. transaction ref is ' + response.reference);
      },
      onClose: function(){
          alert('window closed');
      }
    });
    handler.openIframe();
  }
</script>
<form >
  <script src="https://js.paystack.co/v1/inline.js"></script>
  <button type="button" onclick="payWithPaystack()"> Pay </button> 
</form>
 
<script>
  function payWithPaystack(){
    var handler = PaystackPop.setup({
      key: 'pk_test_86d32aa1nV4l1da7120ce530f0b221c3cb97cbcc',
      email: 'customer@email.com',
      plan: "PLN_code",
      ref: "UNIQUE TRANSACTION REFERENCE HERE",
      metadata: {
         custom_fields: [
            {
                display_name: "Mobile Number",
                variable_name: "mobile_number",
                value: "+2348012345678"
            }
         ]
      },
      callback: function(response){
          alert('successfully subscribed. transaction ref is ' + response.reference);
      },
      onClose: function(){
          alert('window closed');
      }
    });
    handler.openIframe();
  }
</script>

A lazy way to load Paystack Inline is to pass the parameters as data attributes in a script tag as shown below:

<form action="/process" method="POST" >
  <script
    src="https://js.paystack.co/v1/inline.js" 
    data-key="pk_test_221221122121"
    data-email="customer@email.com"
    data-amount="10000"
    data-ref=<UNIQUE TRANSACTION REFERENCE>
  >
  </script>
</form>

When the user enters their card details, Paystack will validate the card, charge the card, and pass a response object (containing the status of the transaction including reference as reference) to your callback function. If no callback function is set, we will insert a hidden field named paystack-reference on the parent form and submit the form to whatever action you set.

Before you give value to the customer, please make a server-side call to our verification endpoint to confirm the status and properties of the transaction.

Configuration options

'*' indicates required parameters.

Options
Description

key*

Your Public Key from Paystack. Use test public key for test mode and live public key for live mode

ref

Case-sensitive unique transaction reference. Only -,., = and alphanumeric characters allowed.

email*

The customer's email address.

amount*

Amount in kobo. Ignored if creating a subscription.

callback

Javascript function that should be called if the payment is successful

onClose

Javascript function that should be called if the customer closes the payment window

currency

Currency charge should be performed in. Default is NGN

For Subscribing

plan

If transaction is to create a subscription to a predefined plan, provide plan code here.

invoice_limit

Number of invoices to raise during the subscription. Overrides invoice_limit set on plan.

quantity

Used to apply a multiple to the amount returned by the plan code above.

channels

Send us 'card' or 'bank' or 'card','bank' as an array to specify what options to show the user paying.

Lazy only

data-custom-button

ID of custom button if you do not want to use the default Paystack button. To be used only if you are using the latter (lazy) method of loading Paystack using script tags.

For Split Payments

subaccount

( string ) The code for the subaccount that owns the payment. e.g. ACCT_8f4s1eq7ml6rlzj

transaction_charge

( integer, optional ) A flat fee to charge the subaccount for this transaction, in kobo. 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, optional ) Who bears Paystack charges? account or subaccount. Defaults to account.

Suggest Edits

Paystack Standard

Do a redirect to the authorization URL received from calling this endpoint. This URL is valid for one time use, so ensure that you generate a new URL per transaction.

When the payment is successful, we will redirect to your callback URL (as setup in your dashboard) and return the reference sent in the first step as a query parameter.

If you use a test secret key, we will redirect to your test callback url, otherwise, we will redirect to your live callback url.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/transaction/initialize
<?php

$result = array();
//Set other parameters as keys in the $postdata array
$postdata =  array('email' => 'customer@email.com', 'amount' => 500000,"reference" => '7PVGX8MEk85tgeEpVDtD');
$url = "https://api.paystack.co/transaction/initialize";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,json_encode($postdata));  //Post Fields
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$headers = [
  'Authorization: Bearer SECRET_KEY',
  'Content-Type: application/json',

];
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$request = curl_exec ($ch);

curl_close ($ch);

if ($request) {
  $result = json_decode($request, true);
}
//Use the $result array to get redirect URL
curl https://api.paystack.co/transaction/initialize \
-H "Authorization: Bearer SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"reference": "7PVGX8MEk85tgeEpVDtD", "amount": 500000, "email": "customer@email.com"}' \
-X POST
<?php
// Initialize as required by your installation
// Download library from https://github.com/yabacon/paystack-php
$paystack = new Paystack('SECRET_KEY');
$responseObj = $paystack->transaction->initialize([
     "reference"=>"7PVGX8MEk85tgeEpVDtD",
     "amount"=>500000,
     "email"=>"customer@email.com",
]);
<?php
// Initialize as required by your installation
// Download library from https://github.com/yabacon/paystack-php
$paystack = new Paystack('SECRET_KEY');

// user will be subscribed to plan once payment succeeds on authorization_url
$responseObj = $paystack->transaction->initialize([
     "reference"=>"7PVGX8MEk85tgeEpVDtD",
     "plan"=>"PLN_code",
     "email"=>"customer@email.com",
]);
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Authorization URL created",
  "data": {
    "authorization_url": "https://standard.paystack.co/pay/0peioxfhpn",
    "access_code": "0peioxfhpn",
    "reference": "920iieuwq"
  }
}

Body Params

reference
string

Unique transaction reference. Only -,., = and alphanumeric characters allowed. Ensure that this is stored in your database and not a session so that you can use it to verify the transaction

callback_url
string

Fully qualified url, e.g. https://nut-ng.org/ . Use this to override the callback url provided on the dashboard for this transaction

amount
int32
required

Amount in kobo

email
string
required

Customer's email address

plan
string

If transaction is to create a subscription to a predefined plan, provide plan code here.

quantity
float

Used to apply a multiple to the amount returned by the plan code above.

invoice_limit
int32

Number of invoices to raise during the subscription. Overrides invoice_limit set on plan.

metadata
object
 
metadata.cancel_action
string

URL customer is redirected to if the cancel button is clicked. NB:This should be a key in the metadata object.

subaccount
string

The code for the subaccount that owns the payment. e.g. ACCT_8f4s1eq7ml6rlzj

transaction_charge
int32

A flat fee to charge the subaccount for this transaction, in kobo. 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.

channels
array of strings

Send us 'card' or 'bank' or 'card','bank' as an array to specify what options to show the user paying

 

Related: Events

Suggest Edits

Verifying Transactions

Before giving value to your customer, you should verify the status of the transaction by passing the reference to the API.

Save the authorization details

Save the details from the json object returned above so that the authorization code can be used for charging subsequent transactions.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/transaction/verify/reference
<?php

$result = array();
//The parameter after verify/ is the transaction reference to be verified
$url = 'https://api.paystack.co/transaction/verify/DG4uishudoq90LD';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt(
  $ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer SECRET_KEY']
);
$request = curl_exec($ch);
curl_close($ch);

if ($request) {
    $result = json_decode($request, true);
    // print_r($result);
    if($result){
      if($result['data']){
        //something came in
        if($result['data']['status'] == 'success'){
          // the transaction was successful, you can deliver value
          /* 
          @ also remember that if this was a card transaction, you can store the 
          @ card authorization to enable you charge the customer subsequently. 
          @ The card authorization is in: 
          @ $result['data']['authorization']['authorization_code'];
          @ PS: Store the authorization with this email address used for this transaction. 
          @ The authorization will only work with this particular email.
          @ If the user changes his email on your system, it will be unusable
          */
          echo "Transaction was successful";
        }else{
          // the transaction was not successful, do not deliver value'
          // print_r($result);  //uncomment this line to inspect the result, to check why it failed.
          echo "Transaction was not successful: Last gateway response was: ".$result['data']['gateway_response'];
        }
      }else{
        echo $result['message'];
      }

    }else{
      //print_r($result);
      die("Something went wrong while trying to convert the request variable to json. Uncomment the print_r command to see what is in the result variable.");
    }
  }else{
    //var_dump($request);
    die("Something went wrong while executing curl. Uncomment the var_dump line above this line to see what the issue is. Please check your CURL command to make sure everything is ok");
  }
curl https://api.paystack.co/transaction/verify/DG4uishudoq90LD \
-H "Authorization: Bearer SECRET_KEY"
<?php
// Initialize as required by your installation
// Download library from https://github.com/yabacon/paystack-php
$paystack = new Paystack('SECRET_KEY');
$responseObj = $paystack->transaction->verify(["reference"=>"7PVGX8MEk85tgeEpVDtD"]);
// Require the library

// Download library from https://github.com/kehers/paystack
var paystack = require('paystack')('SECRET_KEY');

paystack.transactions.verify('7PVGX8MEk85tgeEpVDtD', function(error, body) {
  console.log(error);
  console.log(body);
});
A binary file was returned

You couldn't be authenticated

{  
   "status":true,
   "message":"Verification successful",
   "data":{  
      "amount":27000,
      "currency":"NGN",
      "transaction_date":"2016-10-01T11:03:09.000Z",
      "status":"success",
      "reference":"DG4uishudoq90LD",
      "domain":"test",
      "metadata":0,
      "gateway_response":"Successful",
      "message":null,
      "channel":"card",
      "ip_address":"41.1.25.1",
      "log":{  
         "time_spent":9,
         "attempts":1,
         "authentication":null,
         "errors":0,
         "success":true,
         "mobile":false,
         "input":[ ],
         "channel":null,
         "history":[  
            {  
               "type":"input",
               "message":"Filled these fields: card number, card expiry, card cvv",
               "time":7
            },
            {  
               "type":"action",
               "message":"Attempted to pay",
               "time":7
            },
            {  
               "type":"success",
               "message":"Successfully paid",
               "time":8
            },
            {  
               "type":"close",
               "message":"Page closed",
               "time":9
            }
         ]
      },
      "fees":null,
      "authorization":{  
         "authorization_code":"AUTH_8dfhjjdt",
         "card_type":"visa",
         "last4":"1381",
         "exp_month":"08",
         "exp_year":"2018",
         "bin":"412345",
         "bank":"TEST BANK",
         "channel":"card",
         "reusable":true,
         "country_code":"NG"
      },
      "customer":{  
         "id":84312,
         "customer_code":"CUS_hdhye17yj8qd2tx",
         "first_name":"BoJack",
         "last_name":"Horseman",
         "email":"bojack@horseman.com"
      },
      "plan":"PLN_0as2m9n02cl0kp6"
   }
}
{  
   "status":true,
   "message":"Verification successful",
   "data":{  
      "amount":27000,
      "currency":"NGN",
      "transaction_date":"2016-10-01T11:03:09.000Z",
      "status":"failed",
      "reference":"DG4uishudoq90LD",
      "domain":"test",
      "metadata":0,
      "gateway_response":"Insufficient Funds",
      "message":null,
      "channel":"card",
      "ip_address":"41.1.25.1",
      "log":{  
         "time_spent":9,
         "attempts":1,
         "authentication":null,
         "errors":0,
         "success":true,
         "mobile":false,
         "input":[ ],
         "channel":null,
         "history":[  
            {  
               "type":"input",
               "message":"Filled these fields: card number, card expiry, card cvv",
               "time":7
            },
            {  
               "type":"action",
               "message":"Attempted to pay",
               "time":7
            },
            {  
               "type":"error",
               "message":"Insufficient Funds",
               "time":8
            },
            {  
               "type":"close",
               "message":"Page closed",
               "time":9
            }
         ]
      },
      "fees":null,
      "authorization":{  
         "authorization_code":"AUTH_8dfhjjdt",
         "card_type":"visa",
         "last4":"1381",
         "exp_month":"08",
         "exp_year":"2018",
         "bin":"412345",
         "bank":"TEST BANK",
         "channel":"card",
         "reusable":true,
         "country_code":"NG"
      },
      "customer":{  
         "id":84312,
         "customer_code":"CUS_hdhye17yj8qd2tx",
         "first_name":"BoJack",
         "last_name":"Horseman",
         "email":"bojack@horseman.com"
      },
      "plan":"PLN_0as2m9n02cl0kp6"
   }
}
{  
   "status":true,
   "message":"Verification successful",
   "data":{  
      "amount":27000,
      "currency":"NGN",
      "transaction_date":"2016-10-01T11:03:09.000Z",
      "status":"abandoned",
      "reference":"DG4uishudoq90LD",
      "domain":"test",
      "metadata":0,
      "gateway_response":"The transaction was not completed",
      "message":null,
      "channel":"card",
      "ip_address":"41.1.25.1",
      "log":{  
         "time_spent":9,
         "attempts":1,
         "authentication":null,
         "errors":0,
         "success":true,
         "mobile":false,
         "input":[ ],
         "channel":null,
         "history":[  
            {  
               "type":"close",
               "message":"Page closed",
               "time":9
            }
         ]
      },
      "fees":null,
      "authorization":{  
         "authorization_code":"AUTH_8dfhjjdt",
         "card_type":"visa",
         "last4":"1381",
         "exp_month":"08",
         "exp_year":"2018",
         "bin":"412345",
         "bank":"TEST BANK",
         "channel":"card",
         "reusable":true,
         "country_code":"NG"
      },
      "customer":{  
         "id":84312,
         "customer_code":"CUS_hdhye17yj8qd2tx",
         "first_name":"BoJack",
         "last_name":"Horseman",
         "email":"bojack@horseman.com"
      },
      "plan":"PLN_0as2m9n02cl0kp6"
   }
}
{  
   "status": false,
   "message": "Invalid key"
}

Path Params

reference
string
required
 
Suggest Edits

Charging returning customers

All authorizations marked as reusable can be charged with this endpoint whenever you need to receive payments.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/transaction/charge_authorization
<?php 

$result = array();
// Pass the customer's authorisation code, email and amount
$postdata =  array( 'authorization_code' => 'AUTH_72btv547','email' => 'customer@email.com', 'amount' => 500000,"reference" => '0bxco8lyc2aa0fq');

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,"https://api.paystack.co/transaction/charge_authorization");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,json_encode($postdata));  //Post Fields
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$headers = [
  'Authorization: Bearer SECRET_KEY',
  'Content-Type: application/json',
];

curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$request = curl_exec ($ch);

curl_close ($ch);
if ($request) {
  $result = json_decode($request, true);
}

curl https://api.paystack.co/transaction/charge_authorization \
-H "Authorization: Bearer SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"authorization_code": "AUTH_72btv547", "email": "customer@email.com", "amount": =}' \
-X POST
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "amount": 500000,
    "currency": "NGN",
    "transaction_date": "2016-10-01T14:29:53.000Z",
    "status": "success",
    "reference": "0bxco8lyc2aa0fq",
    "domain": "live",
    "metadata": {
      "custom_fields":[
        {
          "display_name":"Cart ID",
          "variable_name":"cart_id",
          "value":"8393"
        }
      ]
    },
    "gateway_response": "Successful",
    "message": null,
    "channel": "card",
    "ip_address": null,
    "log": null,
    "fees": null,
    "authorization": {
      "authorization_code": "AUTH_72btv547",
      "card_type": "mastercard",
      "last4": "1839",
      "exp_month": "01",
      "exp_year": "2020",
      "exp_year": "532345",
      "bank": "Guaranty Trust Bank",
      "channel": "card",
      "reusable": true,
      "country_code": "NG"
    },
    "customer": {
      "id": 90831,
      "customer_code": "CUS_fxg9930u8pqeiu",
      "first_name": "Customer",
      "last_name": "Daadaa ni",
      "email": "customer@email.com"
    },
    "plan": 0
  }
}
{  
   "status":true,
   "message":"Charge Attempted",
   "data":{  
      "amount":27000,
      "currency":"NGN",
      "transaction_date":"2016-10-01T11:03:09.000Z",
      "status":"failed",
      "reference":"DG4uishudoq90LD",
      "domain":"test",
      "metadata":0,
      "gateway_response":"Insufficient Funds",
      "message":null,
      "channel":"card",
      "ip_address":"41.1.25.1",
      "log":null,
      "fees":null,
      "authorization":{  
         "authorization_code":"AUTH_8dfhjjdt",
         "card_type":"visa",
         "last4":"1381",
         "exp_month":"08",
         "exp_year":"2018",
         "bin":"412345",
         "bank":"TEST BANK",
         "channel":"card",
         "reusable":true,
         "country_code":"NG"
      },
      "customer":{  
         "id":84312,
         "customer_code":"CUS_hdhye17yj8qd2tx",
         "first_name":"BoJack",
         "last_name":"Horseman",
         "email":"bojack@horseman.com"
      },
      "plan":"PLN_0as2m9n02cl0kp6"
   }
}
{  
   "status": false,
   "message": "Invalid key"
}

Body Params

reference
string

Unique transaction reference. Only -,., = and alphanumeric characters allowed. System will generate one if none is specified

authorization_code
string
required

Authorization code representing card you want charged

email
string
required

Customer's email address

amount
string
required

Amount in kobo

plan
string

If transaction is to create a subscription to a predefined plan, provide plan code here.

quantity
float

Used to apply a multiple to the amount returned by the plan code above.

invoice_limit
int32

Number of invoices to raise during the subscription. Overrides invoice_limit set on plan.

currency
string

Currency in which amount should be charged

metadata
object

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"}]}

 
subaccount
string

The code for the subaccount that owns the payment. e.g. ACCT_8f4s1eq7ml6rlzj

transaction_charge
int32

A flat fee to charge the subaccount for this transaction, in kobo. 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

 
Suggest Edits

Paystack Inline Embed

 

Paystack Inline Embed is the latest addition to the stack, it offers a stylish Inline that loads the credit card form in a set container like it sits in your page.

Working with Paystack Inline Embded

Here is a sample code that calls Paystack and also handles outcome.

Key

Please note that the key to use with inline is the public key and not the secret key

<script src="https://js.paystack.co/v1/inline.js"></script>
<div id="paystackEmbedContainer"></div>

<script>
  PaystackPop.setup({
   key: 'pk_test_221221122121',
   email: 'customer@email.com',
   amount: 10000,
   container: 'paystackEmbedContainer',
   callback: function(response){
        alert('successfully subscribed. transaction ref is ' + response.reference);
    },
  });
</script>

Things to note while using Inline Embed

  1. You need to specify a container div that will house the form. All classes and styles on this div will be reset.
  2. The embed will automatically load in the container. No need to call loadIframe() on the Paystack instance
  3. The payment form will be 100% of the width of wherever you put it.
  4. To maintain a uniform design, your page's background color should be white.

When the user enters their card details, Paystack will validate the card, charge the card, and pass a response object (containing the status of the transaction including reference as reference) to your callback function. If no callback function is set, we will insert a hidden field named paystack-reference on the parent form and submit the form to whatever action you set.

Before you give value to the customer, please make a server-side call to our verification endpoint to confirm the status and properties of the transaction.

Configuration options

'*' indicates required parameters.

Options
Description

key*

Your publishable Key from Paystack. Use test key for test mode and live key for live mode

reference*

Unique transaction reference

email*

The customer's email address.

amount*

Amount in kobo. Ignored if creating a subscription.

callback

Javascript function that should be called if the payment is successful

currency

Currency charge should be performed in. Default is NGN

For Subscribing

plan

If transaction is to create a subscription to a predefined plan, provide plan code here.

invoice_limit

Number of invoices to raise during the subscription. Overrides invoice_limit set on plan.

quantity

Used to apply a multiple to the amount returned by the plan code above.

For Split Payments

subaccount

( string ) The code for the subaccount that owns the payment. e.g. ACCT_8f4s1eq7ml6rlzj

transaction_charge

( integer, optional ) A flat fee to charge the subaccount for this transaction, in kobo. 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, optional ) Who bears Paystack charges? account or subaccount. Defaults to account.

Suggest Edits

Initialize Transaction

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/transaction/initialize
curl https://api.paystack.co/transaction/initialize \
-H "Authorization: Bearer SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"reference": "7PVGX8MEk85tgeEpVDtD", "amount": 500000, "email": "customer@email.com"}' \
-X POST
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Authorization URL created",
  "data": {
    "authorization_url": "https://checkout.paystack.com/0peioxfhpn",
    "access_code": "0peioxfhpn",
    "reference": "7PVGX8MEk85tgeEpVDtD"
  }
}

Body Params

callback_url
string

Fully qualified url, e.g. https://nut-ng.org/ . Use this to override the callback url provided on the dashboard for this transaction

reference
string

Unique transaction reference. Only -,., = and alphanumeric characters allowed.

amount
string
required

Amount in kobo

email
string
required

Customer's email address

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
int32

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"}]}

subaccount
string

The code for the subaccount that owns the payment. e.g. ACCT_8f4s1eq7ml6rlzj

transaction_charge
int32

A flat fee to charge the subaccount for this transaction, in kobo. 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).

channels
array of strings

Send us 'card' or 'bank' or 'card','bank' as an array to specify what options to show the user paying

 
Suggest Edits

Verify Transaction

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/transaction/verify/reference
curl https://api.paystack.co/transaction/verify/DG4uishudoq90LD \
-H "Authorization: Bearer SECRET_KEY"
A binary file was returned

You couldn't be authenticated

{  
   "status":true,
   "message":"Verification successful",
   "data":{  
      "amount":27000,
      "currency":"NGN",
      "transaction_date":"2016-10-01T11:03:09.000Z",
      "status":"success",
      "reference":"DG4uishudoq90LD",
      "domain":"test",
      "metadata":0,
      "gateway_response":"Successful",
      "message":null,
      "channel":"card",
      "ip_address":"41.1.25.1",
      "log":{  
         "time_spent":9,
         "attempts":1,
         "authentication":null,
         "errors":0,
         "success":true,
         "mobile":false,
         "input":[ ],
         "channel":null,
         "history":[  
            {  
               "type":"input",
               "message":"Filled these fields: card number, card expiry, card cvv",
               "time":7
            },
            {  
               "type":"action",
               "message":"Attempted to pay",
               "time":7
            },
            {  
               "type":"success",
               "message":"Successfully paid",
               "time":8
            },
            {  
               "type":"close",
               "message":"Page closed",
               "time":9
            }
         ]
      },
      "fees":null,
      "authorization":{  
         "authorization_code":"AUTH_8dfhjjdt",
         "card_type":"visa",
         "last4":"1381",
         "exp_month":"08",
         "exp_year":"2018",
         "bin":"412345",
         "bank":"TEST BANK",
         "channel":"card",
         "signature": "SIG_idyuhgd87dUYSHO92D",
         "reusable":true,
         "country_code":"NG"
      },
      "customer":{  
         "id":84312,
         "customer_code":"CUS_hdhye17yj8qd2tx",
         "first_name":"BoJack",
         "last_name":"Horseman",
         "email":"bojack@horseman.com"
      },
      "plan":"PLN_0as2m9n02cl0kp6"
   }
}
{  
   "status":true,
   "message":"Verification successful",
   "data":{  
      "amount":27000,
      "currency":"NGN",
      "transaction_date":"2016-10-01T11:03:09.000Z",
      "status":"failed",
      "reference":"djfoidjkdkj41",
      "domain":"test",
      "metadata":0,
      "gateway_response":"Insufficient Funds",
      "message":null,
      "channel":"card",
      "ip_address":"41.1.25.1",
      "log":{  
         "time_spent":9,
         "attempts":1,
         "authentication":null,
         "errors":0,
         "success":true,
         "mobile":false,
         "input":[ ],
         "channel":null,
         "history":[  
            {  
               "type":"input",
               "message":"Filled these fields: card number, card expiry, card cvv",
               "time":7
            },
            {  
               "type":"action",
               "message":"Attempted to pay",
               "time":7
            },
            {  
               "type":"close",
               "message":"Page closed",
               "time":9
            }
         ]
      },
      "fees":null,
      "authorization":{  
         "authorization_code":"AUTH_8dfhjjdt",
         "card_type":"visa",
         "last4":"1381",
         "exp_month":"08",
         "exp_year":"2018",
         "bin":"412345",
         "bank":"TEST BANK",
         "channel":"card",
         "signature": "SIG_idyuhgd87dUYSHO92D",
         "reusable":true,
         "country_code":"NG"
      },
      "customer":{  
         "id":84312,
         "customer_code":"CUS_hdhye17yj8qd2tx",
         "first_name":"BoJack",
         "last_name":"Horseman",
         "email":"bojack@horseman.com"
      },
      "plan":""
   }
}
{  
   "status":false,
   "message":"Invalid key"
}

Path Params

reference
string
required
 
Suggest Edits

List Transactions

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/transaction
curl "https://api.paystack.co/transaction" \
-H "Authorization: Bearer SECRET_KEY" 
-X GET
<?php
// Initialize as required by your installation

$paystack = new Paystack('SECRET_KEY');
$responseObj = $paystack->transactions(["perPage"=>1, "amount"=>10000, "status"=>"success"]);
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Transactions retrieved",
  "data": [
    {
      "id": 5833,
      "domain": "test",
      "status": "failed",
      "reference": "icy9ma6jd1",
      "amount": 100,
      "message": null,
      "gateway_response": "Declined",
      "paid_at": null,
      "created_at": "2016-09-29T00:00:05.000Z",
      "channel": "card",
      "currency": "NGN",
      "ip_address": null,
      "metadata": null,
      "timeline": null,
      "customer": {
        "first_name": "Ezra",
        "last_name": "Olubi",
        "email": "ezra@cfezra.com",
        "phone": "16504173147",
        "metadata": null,
        "customer_code": "CUS_1uld4hluw0g2gn0"
      },
      "authorization": {},
      "plan": {}
    }
  ],
  "meta": {
    "total": 1,
    "skipped": 0,
    "perPage": 50,
    "page": 1,
    "pageCount": 1
  }
}
{
  "status": true,
  "message": "Transactions retrieved",
  "data": [
    {
      "id": 298126,
      "domain": "live",
      "status": "failed",
      "reference": "z1gsnks86e6kfo8",
      "amount": 10000,
      "message": null,
      "gateway_response": "Declined",
      "paid_at": null,
      "created_at": "2016-09-29T00:03:22.000Z",
      "channel": "card",
      "currency": "NGN",
      "ip_address": null,
      "metadata": {
                "custom_fields": [
                    {
                        "display_name": "Mobile Number",
                        "variable_name": "mobile_number",
                        "value": "+2348012345678"
                    }
                ]
        },
      "log": null,
      "fees": null,
      "paidAt": "2016-09-29T00:03:25.000Z",
      "createdAt": "2016-09-29T00:03:22.000Z",
      "authorization": {
        "authorization_code": "AUTH_86gs11dr",
        "bin": "539983",
        "last4": "0061",
        "exp_month": "08",
        "exp_year": "2018",
        "card_type": "mastercard DEBIT",
        "bank": "Guaranty Trust Bank",
        "country_code": "NG",
        "brand": "mastercard"
      },
      "customer": {
        "id": 8279,
        "first_name": "Ezra",
        "last_name": "Olubi",
        "email": "ezra@cfezra.com",
        "phone": "16504173147",
        "customer_code": "CUS_1uld4hluw0g2gn0",
        "metadata":null,
        "risk_action": "default"
      }
    }
  ],
  "meta": {
    "total": 248,
    "total_volume": 1372244,
    "skipped": 0,
    "perPage": "1",
    "page": 1,
    "pageCount": 248
  }
}%                                                                              

Query Params

perPage
int32

Specify how many records you want to retrieve per page

page
int32

Specify exactly what page you want to retrieve

customer
int32

Specify an ID for the customer whose transactions you want to retrieve

status
string

Filter transactions by status ('failed', 'success', 'abandoned')

from
date-time

A timestamp from which to start listing transaction e.g. 2016-09-24T00:00:05.000Z, 2016-09-21

to
date-time

A timestamp at which to stop listing transaction e.g. 2016-09-24T00:00:05.000Z, 2016-09-21

amount
int32

Filter transactions by amount. Specify the amount in kobo.

 
Suggest Edits

Fetch Transaction

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/transaction/id
curl "https://api.paystack.co/transaction/2091" \
-H "Authorization: Bearer SECRET_KEY" 
-X GET
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Transaction retrieved",
  "data": {
    "id": 1009262,
    "domain": "live",
    "status": "success",
    "reference": "6qgnjzybsf18kd5",
    "amount": 5000,
    "message": null,
    "gateway_response": "Successful",
    "paid_at": "2017-03-27T13:15:14.000Z",
    "created_at": "2017-03-27T13:15:12.000Z",
    "channel": "card",
    "currency": "NGN",
    "ip_address": null,
    "metadata": "",
    "log": null,
    "fees": 75,
    "fees_split": null,
    "customer": {
      "id": 53890,
      "first_name": null,
      "last_name": null,
      "email": "blessyou@youaregood.com",
      "customer_code": "CUS_eleh5188vyqmzxx",
      "phone": null,
      "metadata": null,
      "risk_action": "default"
    },
    "authorization": {
      "authorization_code": "AUTH_wbd1hrxx",
      "bin": "539923",
      "last4": "0061",
      "exp_month": "08",
      "exp_year": "2020",
      "channel": "card",
      "card_type": "mastercard DEBIT",
      "bank": "First Bank",
      "country_code": "NG",
      "brand": "mastercard",
      "reusable": true,
      "signature": "SIG_7Ukx988euhd980dIDHB7AFj8Teqx"
    },
    "plan": {},
    "subaccount": {},
    "paidAt": "2017-03-27T13:15:14.000Z",
    "createdAt": "2017-03-27T13:15:12.000Z"
  }
}

Path Params

id
int32
required

An ID for the transaction to fetch

 
Suggest Edits

Charge Authorization

All authorizations marked as reusable can be charged with this endpoint whenever you need to recieve payments.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/transaction/charge_authorization
curl https://api.paystack.co/transaction/charge_authorization \
-H "Authorization: Bearer SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"authorization_code": "AUTH_72btv547", "email": "bojack@horsinaround.com", "amount": 500000}' \
-X POST
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "amount": 500000,
    "currency": "NGN",
    "transaction_date": "2016-10-01T14:29:53.000Z",
    "status": "success",
    "reference": "0bxco8lyc2aa0fq",
    "domain": "live",
    "metadata": null,
    "gateway_response": "Successful",
    "message": null,
    "channel": "card",
    "ip_address": null,
    "log": null,
    "fees": null,
    "authorization": {
      "authorization_code": "AUTH_5z72ux0koz",
      "bin": "408408",
      "last4": "4081",
      "exp_month": "12",
      "exp_year": "2020",
      "channel": "card",
      "card_type": "visa DEBIT",
      "bank": "Test Bank",
      "country_code": "NG",
      "brand": "visa",
      "reusable": true,
      "signature": "SIG_ZdUx7Z5ujd75rt9OMTN4"
    },
    "customer": {
      "id": 90831,
      "customer_code": "CUS_fxg9930u8pqeiu",
      "first_name": "Bojack",
      "last_name": "Horseman",
      "email": "bojack@horsinaround.com"
    },
    "plan": 0
  }
}
{  
   "status":true,
   "message":"Charge Attempted",
   "data":{  
      "amount":27000,
      "currency":"NGN",
      "transaction_date":"2016-10-01T11:03:09.000Z",
      "status":"failed",
      "reference":"DG4uishudoq90LD",
      "domain":"test",
      "metadata":0,
      "gateway_response":"Insufficient Funds",
      "message":null,
      "channel":"card",
      "ip_address":"41.1.25.1",
      "log":null,
      "fees":null,
      "authorization":{  
          "authorization_code": "AUTH_5z72ux0koz",
          "bin": "408408",
          "last4": "4081",
          "exp_month": "12",
          "exp_year": "2020",
          "channel": "card",
          "card_type": "visa DEBIT",
          "bank": "Test Bank",
          "country_code": "NG",
          "brand": "visa",
          "reusable": true,
          "signature": "SIG_ZdUx7Z5ujd75rt9OMTN4"
      },
      "customer":{  
         "id":84312,
         "customer_code":"CUS_hdhye17yj8qd2tx",
         "first_name":"BoJack",
         "last_name":"Horseman",
         "email":"bojack@horseman.com"
      },
      "plan":"PLN_0as2m9n02cl0kp6"
   }
}
{  
   "status": false,
   "message": "Invalid key"
}

Body Params

reference
string

Unique transaction reference. Only -,., = and alphanumeric characters allowed. System will generate one if none is provided

authorization_code
string
required

Valid authorization code to charge

amount
int32
required

Amount in kobo

plan
string

If transaction is to create a subscription to a predefined plan, provide plan code here.

currency
string

Currency in which amount should be charged

email
string
required

Customer's email address

metadata
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"}]}

 
subaccount
string

The code for the subaccount that owns the payment. e.g. ACCT_8f4s1eq7ml6rlzj

transaction_charge
int32

A flat fee to charge the subaccount for this transaction, in kobo. 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

invoice_limit
int32

Number of invoices to raise during the subscription. Overrides invoice_limit set on plan.

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.

 

This will only work for authorizations with for which reusable is true.

Suggest Edits

View Transaction Timeline

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/transaction/timeline/id
curl https://api.paystack.co/transaction/timeline/12092 \
-H "Authorization: Bearer SECRET_KEY"
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Timeline retrieved",
  "data": {
    "time_spent": 9061,
    "attempts": 1,
    "authentication": null,
    "errors": 1,
    "success": false,
    "mobile": false,
    "input": [],
    "channel": "card",
    "history": [
      {
        "type": "open",
        "message": "Opened payment page",
        "time": 1
      },
      {
        "type": "input",
        "message": "Filled these fields: card number, card expiry, card cvc",
        "time": 39
      },
      {
        "type": "action",
        "message": "Attempted to pay",
        "time": 39
      },
      {
        "type": "error",
        "message": "Error: Declined",
        "time": 48
      },
      {
        "type": "input",
        "message": "Filled these fields: card expiry, card cvc",
        "time": 9061
      },
      {
        "type": "close",
        "message": "Page closed",
        "time": 9061
      }
    ]
  }
}
{
  "status": false,
  "message": "Transaction ID or reference is invalid"
}

Path Params

id
int32
required

Transaction ID

 
Suggest Edits

Transaction Totals

Total amount received on your account

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/transaction/totals
curl "https://api.paystack.co/transaction/totals" \
-H "Authorization: Bearer SECRET_KEY" 
-X GET
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Transaction totals",
  "data": {
    "total_transactions": 10,
    "unique_customers": 3,
    "total_volume": 14000,
    "total_volume_by_currency": [
      {
        "currency": "NGN",
        "amount": 14000
      }
    ],
    "pending_transfers": 24000,
    "pending_transfers_by_currency": [
      {
        "currency": "NGN",
        "amount": 24000
      }
    ]
  }
}

Query Params

from
date

Lower bound of date range. Leave undefined to show totals from day one.

to
date

Upper bound of date range. Leave undefined to show totals till date.

 
Suggest Edits

Export Transactions

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/transaction/export
curl "https://api.paystack.co/transaction/export" \
-H "Authorization: Bearer SECRET_KEY" 
-X GET
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Export successful",
  "data": {
    "path": "https://files.paystack.co/exports/100032/1460290758207.csv"
  }
}

Query Params

from
date

Lower bound of date range. Leave undefined to export transactions from day one.

to
date

Upper bound of date range. Leave undefined to export transactions till date.

settled
boolean

Set to true to export only settled transactions. false for pending transactions. Leave undefined to export all transactions

payment_page
int32

Specify a payment page's id to export only transactions conducted on said page

customer
int32
currency
string
settlement
int32

An ID for the settlement whose transactions we should export

amount
int32

Amount for transactions to export

status
string

Status for transactions to export

 

Note that all timestamps are in GMT.

Suggest Edits

Request Reauthorization

We do not activate authorizations for recurring billing until the first time we are able to bill that card successfully. Reauthorizing with the issuing bank may ensure a successful transaction.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/transaction/request_reauthorization
curl https://api.paystack.co/transaction/request_reauthorization \
-H "Authorization: Bearer SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"authorization_code": "AUTH_72btv547", "email": "bojack@horsinaround.com", "amount": 500000}' \
-X POST
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Reauthorization initiated",
  "data": {
    "reauthorization_url": "https://paystack.com/authorize/10001",
    "reference": "1nv4LiD"
  }
}

Body Params

reference
string

Unique transaction reference. Only -,., = and alphanumeric characters allowed. System will generate one if none is provided

authorization_code
string
required

Valid authorization code to charge

amount
int32
required

Amount in kobo

currency
string

Currency in which amount should be charged

email
string
required

Customer's email address

metadata
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"}]}

 
 

Do a redirect to the reauthorization URL received from calling this endpoint. This URL is valid for one time use and expires in 2 hours, so ensure that your customer is on standby to conclude the transaction.

When the payment is successful, we will send an event to your webhook url.

If you use a test secret key, we will call your test webhook url, otherwise, we'll call your live webhook url.

Suggest Edits

Check Authorization

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

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/transaction/check_authorization
curl https://api.paystack.co/transaction/check_authorization \
-H "Authorization: Bearer SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"authorization_code": "AUTH_72btv547", "email": "bojack@horsinaround.com", "amount": 500000}' \
-X POST
A binary file was returned

You couldn't be authenticated

{
    "status": true,
    "message": "Authorization is valid for this amount",
    "data": {
        "amount": "400",
        "currency": "NGN"
    }
}
{
    "status": false,
    "message": "Insufficient Funds"
}

Body Params

authorization_code
string
required

Authorization code for mastercard or VISA authorization belonging to email

amount
int32
required

Amount in kobo

email
string
required

Customer's email address

currency
string

A currency for the amount we want to check

 

In test mode, we will return insufficient funds for an amount greater than or equal 500,000 naira.

This endpoint will only work for authorizations with for which brand is mastercard or visa

Suggest Edits

Create Customer

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/customer
curl "https://api.paystack.co/customer" \
-H "Authorization: Bearer SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "bojack@horsinaround.com"}' \ 
-X POST
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Customer created",
  "data": {
    "email": "bojack@horsinaround.com",
    "integration": 100032,
    "domain": "test",
    "customer_code": "CUS_xnxdt6s1zg1f4nx",
    "id": 1173,
    "createdAt": "2016-03-29T20:03:09.584Z",
    "updatedAt": "2016-03-29T20:03:09.584Z"
  }
}

Body Params

email
string
required

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.

 
 
Suggest Edits

List Customers

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/customer
curl "https://api.paystack.co/customer" \
-H "Authorization: Bearer SECRET_KEY" 
-X GET
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Customers retrieved",
  "data": [
    {
      "integration": 100032,
      "first_name": "Bojack",
      "last_name": "Horseman",
      "email": "bojack@horsinaround.com",
      "phone": null,
      "metadata": {
        "photos": [
          {
            "type": "twitter",
            "typeId": "twitter",
            "typeName": "Twitter",
            "url": "https://d2ojpxxtu63wzl.cloudfront.net/static/61b1a0a1d4dda2c9fe9e165fed07f812_a722ae7148870cc2e33465d1807dfdc6efca33ad2c4e1f8943a79eead3c21311",
            "isPrimary": true
          }
        ]
      },
      "domain": "test",
      "customer_code": "CUS_xnxdt6s1zg1f4nx",
      "id": 1173,
      "createdAt": "2016-03-29T20:03:09.000Z",
      "updatedAt": "2016-03-29T20:03:10.000Z"
    },
    {
      "integration": 100032,
      "first_name": "Diane",
      "last_name": "Nguyen",
      "email": "diane@writersclub.com",
      "phone": "16504173147",
      "metadata": null,
      "domain": "test",
      "customer_code": "CUS_1uld4hluw0g2gn0",
      "id": 63,
      "createdAt": "2016-01-13T01:15:47.000Z",
      "updatedAt": "2016-02-24T16:56:48.000Z"
    },
    {
      "integration": 100032,
      "first_name": null,
      "last_name": null,
      "email": "todd@chavez.com",
      "phone": null,
      "metadata": null,
      "domain": "test",
      "customer_code": "CUS_soirsjdqkyjfwcr",
      "id": 65,
      "createdAt": "2016-01-13T01:15:47.000Z",
      "updatedAt": "2016-01-13T01:15:47.000Z"
    }
  ],
  "meta": {
    "total": 3,
    "skipped": 0,
    "perPage": 50,
    "page": 1,
    "pageCount": 1
  }
}

Query Params

perPage
int32

Specify how many records you want to retrieve per page

page
int32

Specify exactly what page you want to retrieve

 
Suggest Edits

Fetch Customer

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/customer/email_or_id_or_customer_code
curl "https://api.paystack.co/customer/bojack@horsinaround.com" \
-H "Authorization: Bearer SECRET_KEY" 
-X GET
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Customer retrieved",
  "data": {
    {
      "integration": 100032,
      "first_name": "Bojack",
      "last_name": "Horseman",
      "email": "bojack@horsinaround.com",
      "phone": null,
      "metadata": {
        "photos": [
          {
            "type": "twitter",
            "typeId": "twitter",
            "typeName": "Twitter",
            "url": "https://d2ojpxxtu63wzl.cloudfront.net/static/61b1a0a1d4dda2c9fe9e165fed07f812_a722ae7148870cc2e33465d1807dfdc6efca33ad2c4e1f8943a79eead3c21311",
            "isPrimary": true
          }
        ]
      },
      "domain": "test",
      "customer_code": "CUS_xnxdt6s1zg1f4nx",
      "id": 1173,
			"transactions": [],
      "subscriptions": [],
      "authorizations": [],
      "createdAt": "2016-03-29T20:03:09.000Z",
      "updatedAt": "2016-03-29T20:03:10.000Z"
    }
}
{
    "status": false,
    "message": "Invalid key"
}
{
    "status": false,
    "message": "Customer email is invalid for your live domain."
}

Path Params

email_or_id_or_customer_code
string
required

An email or ID or customer code for the customer you want to fetch

 
Suggest Edits

Update Customer

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.paystack.co/customer/:id_or_customer_code
curl "https://api.paystack.co/customer/CUS_xnxdt6s1zg1f4nx" \
-H "Authorization: Bearer SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"first_name": "BoJack"}' \ 
-X PUT
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Customer updated",
  "data": {
    {
      "integration": 100032,
      "first_name": "BoJack",
      "last_name": "Horseman",
      "email": "bojack@horsinaround.com",
      "phone": null,
      "metadata": {
        "photos": [
          {
            "type": "twitter",
            "typeId": "twitter",
            "typeName": "Twitter",
            "url": "https://d2ojpxxtu63wzl.cloudfront.net/static/61b1a0a1d4dda2c9fe9e165fed07f812_a722ae7148870cc2e33465d1807dfdc6efca33ad2c4e1f8943a79eead3c21311",
            "isPrimary": true
          }
        ]
      },
      "domain": "test",
      "customer_code": "CUS_xnxdt6s1zg1f4nx",
      "id": 1173,
			"transactions": [],
      "subscriptions": [],
      "authorizations": [],
      "createdAt": "2016-03-29T20:03:09.000Z",
      "updatedAt": "2016-03-29T20:03:10.000Z"
    }
}

Body Params

first_name
string

Customer's first name

last_name
string

Customer's last name

phone
string

Customer's phone number

metada
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.

 
 
Suggest Edits

White/blacklist Customer

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/customer/set_risk_action
curl https://api.paystack.co/customer/set_risk_action \
-H "Authorization: Bearer SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"customer": "CUS_xr58yrr2ujlft9k", "risk_action": "allow"}' \
-X POST
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Customer updated",
  "data": {
    "first_name": "Peter",
    "last_name": "Griffin",
    "email": "peter@familyguy.com",
    "phone": null,
    "metadata": {},
    "domain": "test",
    "customer_code": "CUS_xr58yrr2ujlft9k",
    "risk_action": "allow",
    "id": 2109,
    "integration": 100032,
    "createdAt": "2016-01-26T13:43:38.000Z",
    "updatedAt": "2016-08-23T03:56:43.000Z"
  }
}
{
  "status": false,
  "message": "You cannot modify risk level of customers on this integration"
}

Body Params

customer
string
required

Customer's ID, code, or email address

risk_action
string

One of the possible risk actions. allow to whitelist. deny to blacklist.

 
Suggest Edits

Deactivate Authorization

For when the card needs to be forgotten...

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/customer/deactivate_authorization
curl -X POST -H "Authorization: Bearer SECRET_KEY" -H "Content-Type: application/json" -d '{"authorization_code": "AUTH_au6hc0de"}' "https://api.paystack.co/customer/deactivate_authorization"
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Authorization has been deactivated"
}

Query Params

authorization_code
string
required

Authorization code to be deactivated

 
Suggest Edits

Create Subaccount

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/subaccount
curl https://api.paystack.co/subaccount \
-H "Authorization: Bearer SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"business_name": "Sunshine Studios", "settlement_bank": "Access Bank", "account_number": "0193274682", "percentage_charge": 18.2}' \
-X POST
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Subaccount created",
  "data": {
    "integration": 100973,
    "domain": "test",
    "subaccount_code": "ACCT_4hl4xenwpjy5wb",
    "business_name": "Sunshine Studios",
    "description": null,
    "primary_contact_name": null,
    "primary_contact_email": null,
    "primary_contact_phone": null,
    "metadata": null,
    "percentage_charge": 18.2,
    "is_verified": false,
    "settlement_bank": "Access Bank",
    "account_number": "0193274682",
    "settlement_schedule": "AUTO",
    "active": true,
    "migrate": false,
    "id": 55,
    "createdAt": "2016-10-05T13:22:04.000Z",
    "updatedAt": "2016-10-21T02:19:47.000Z"
  }
}

Body Params

business_name
string
required

Name of business for subaccount

settlement_bank
string
required

Name of Bank (see list of accepted names by calling List Banks

account_number
string
required

NUBAN Bank Account Number

percentage_charge
float
required

What is the default percentage charged when receiving on behalf of 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. Sample: {"custom_fields":[{"display_name":"Cart ID","variable_name":"cart_id","value":"8393"}]}

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.

 

Receive payments for the created subaccount by providing their code when doing a transaction. More details here: Split Payments Overview

Suggest Edits

List Subaccounts

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/subaccount
curl "https://api.paystack.co/subaccount" \
-H "Authorization: Bearer SECRET_KEY" 
-X GET
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Subaccounts retrieved",
  "data": [
    {
      "integration": 129938,
      "domain": "test",
      "subaccount_code": "ACCT_cljt3j4cp0kb2gq",
      "business_name": "Business 2",
      "description": null,
      "primary_contact_name": null,
      "primary_contact_email": null,
      "primary_contact_phone": null,
      "metadata": null,
      "percentage_charge": 20,
      "is_verified": false,
      "settlement_bank": "Zenith Bank",
      "account_number": "0193274382",
      "active": true,
      "migrate": false,
      "id": 53,
      "createdAt": "2016-10-05T12:55:47.000Z",
      "updatedAt": "2016-10-05T12:55:47.000Z"
    },
    {
      "integration": 129938,
      "domain": "test",
      "subaccount_code": "ACCT_vwy3d1gck2c9gxi",
      "business_name": "Sunshine Studios",
      "description": null,
      "primary_contact_name": null,
      "primary_contact_email": null,
      "primary_contact_phone": null,
      "metadata": null,
      "percentage_charge": 20,
      "is_verified": false,
      "settlement_bank": "Access Bank",
      "account_number": "0128633833",
      "active": true,
      "migrate": false,
      "id": 35,
      "createdAt": "2016-10-04T09:06:00.000Z",
      "updatedAt": "2016-10-04T09:06:00.000Z"
    },
    {
      "integration": 129938,
      "domain": "test",
      "subaccount_code": "ACCT_5mikcokeaknxk1f",
      "business_name": "Business 2",
      "description": null,
      "primary_contact_name": null,
      "primary_contact_email": null,
      "primary_contact_phone": null,
      "percentage_charge": 20,
      "is_verified": false,
      "settlement_bank": "Access Bank",
      "account_number": "0000000000",
      "active": true,
      "migrate": false,
      "id": 34,
      "createdAt": "2016-10-04T08:46:18.000Z",
      "updatedAt": "2016-10-04T08:46:18.000Z"
    }
  ],
  "meta": {
    "total": 20,
    "skipped": 0,
    "perPage": "3",
    "page": 1,
    "pageCount": 7
  }
}

Query Params

perPage
int32

Specify how many records you want to retrieve per page

page
int32

Specify exactly what page you want to retrieve

 
Suggest Edits

Fetch Subaccount

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/subaccount/:id_or_slug
curl "https://api.paystack.co/subaccount/ACCT_4hl4xenwpjy5wb" \
-H "Authorization: Bearer SECRET_KEY" 
-X GET
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Subaccount retrieved",
  "data": {
    "integration": 100973,
    "domain": "test",
    "subaccount_code": "ACCT_4hl4xenwpjy5wb",
    "business_name": "Sunshine Studios",
    "description": null,
    "primary_contact_name": null,
    "primary_contact_email": "dafe@aba.com",
    "primary_contact_phone": null,
    "metadata": null,
    "percentage_charge": 18.9,
    "is_verified": false,
    "settlement_bank": "Access Bank",
    "account_number": "0193274682",
    "settlement_schedule": "AUTO",
    "active": true,
    "migrate": false,
    "id": 55,
    "createdAt": "2016-10-05T13:22:04.000Z",
    "updatedAt": "2016-10-21T02:19:47.000Z"
  }
}
 
Suggest Edits

Update Subaccount

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.paystack.co/subaccount/:id_or_slug
curl "https://api.paystack.co/subaccount/ACCT_4hl4xenwpjy5wb" \
-H "Authorization: Bearer SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"primary_contact_email": "dafe@aba.com", "percentage_charge": 18.9}' \ 
-X PUT
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Subaccount updated",
  "data": {
    "integration": 100973,
    "domain": "test",
    "subaccount_code": "ACCT_4hl4xenwpjy5wb",
    "business_name": "Sunshine Studios",
    "description": null,
    "primary_contact_name": null,
    "primary_contact_email": "dafe@aba.com",
    "primary_contact_phone": null,
    "metadata": null,
    "percentage_charge": 18.9,
    "is_verified": false,
    "settlement_bank": "Access Bank",
    "account_number": "0193274682",
    "settlement_schedule": "AUTO",
    "active": true,
    "migrate": false,
    "id": 55,
    "createdAt": "2016-10-05T13:22:04.000Z",
    "updatedAt": "2016-10-21T02:19:47.000Z"
  }
}

Body Params

business_name
string

A name for the business that owns this subaccount

settlement_bank
string

The bank at which the account is domiciled. Check List Banks for a list of accepted values.

account_number
string

10 digit NUBAN account number

percentage_charge
float

Percentage the subaccount will be charged when they receive a payment.

description
string

A description for this subaccount

primary_contact_name
string

A contact name for the subaccount

primary_contact_email
string

A contact email for the subaccount

primary_contact_phone
string

A contact phone for the subaccount

metadata
string

Stringified JSON object. Sample: {"custom_fields":[{"display_name":"Cart ID","variable_name":"cart_id","value":"8393"}]}

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.

 
Suggest Edits

Create Plan

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/plan
curl https://api.paystack.co/plan \
-H "Authorization: Bearer SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Monthly retainer", "interval": "monthly", "amount": 500000}' \
-X POST
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Plan created",
  "data": {
    "name": "Monthly retainer",
    "amount": 500000,
    "interval": "monthly",
    "integration": 100032,
    "domain": "test",
    "plan_code": "PLN_gx2wn530m0i3w3m",
    "send_invoices": true,
    "send_sms": true,
    "hosted_page": false,
    "currency": "NGN",
    "id": 28,
    "createdAt": "2016-03-29T22:42:50.811Z",
    "updatedAt": "2016-03-29T22:42:50.811Z"
  }
}

Body Params

name
string
required

Name of plan

description
string

Short description of plan

amount
int32
required

Amount to be charged in kobo

interval
string
required

Interval in words. Valid intervals are hourly, daily, weekly, monthly, annually.

send_invoices
boolean

Set to false if you don't want invoices to be sent to your customers

send_sms
boolean

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
int32

Number of invoices to raise during subscription to this plan. Can be overridden by specifying an invoice_limit while subscribing.

 
Suggest Edits

List Plans

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/plan
curl "https://api.paystack.co/plan" \
-H "Authorization: Bearer SECRET_KEY" 
-X GET
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Plans retrieved",
  "data": [
    {
      "subscriptions": [
        {
          "customer": 63,
          "plan": 27,
          "integration": 100032,
          "domain": "test",
          "start": 1458505748,
          "status": "complete",
          "quantity": 1,
          "amount": 100000,
          "subscription_code": "SUB_birvokwpp0sftun",
          "email_token": "9y62mxp4uh25das",
          "authorization": 79,
          "easy_cron_id": null,
          "cron_expression": "0 0 * * 0",
          "next_payment_date": "2016-03-27T07:00:00.000Z",
          "open_invoice": null,
          "id": 8,
          "createdAt": "2016-03-20T20:29:08.000Z",
          "updatedAt": "2016-03-22T16:23:52.000Z"
        }
      ],
      "integration": 100032,
      "domain": "test",
      "name": "Satin Flower",
      "plan_code": "PLN_lkozbpsoyd4je9t",
      "description": null,
      "amount": 100000,
      "interval": "weekly",
      "send_invoices": true,
      "send_sms": true,
      "hosted_page": false,
      "hosted_page_url": null,
      "hosted_page_summary": null,
      "currency": "NGN",
      "id": 27,
      "createdAt": "2016-03-21T02:44:14.000Z",
      "updatedAt": "2016-03-21T02:44:14.000Z"
    },
    {
      "subscriptions": [],
      "integration": 100032,
      "domain": "test",
      "name": "Monthly retainer",
      "plan_code": "PLN_gx2wn530m0i3w3m",
      "description": null,
      "amount": 50000,
      "interval": "monthly",
      "send_invoices": true,
      "send_sms": true,
      "hosted_page": false,
      "hosted_page_url": null,
      "hosted_page_summary": null,
      "currency": "NGN",
      "id": 28,
      "createdAt": "2016-03-29T22:42:50.000Z",
      "updatedAt": "2016-03-29T22:42:50.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "skipped": 0,
    "perPage": 50,
    "page": 1,
    "pageCount": 1
  }
}

Query Params

perPage
string

Specify how many records you want to retrieve per page

page
string

Specify exactly what page you want to retrieve

interval
string

Filter list by plans with specified interval

amount
string

Filter list by plans with specified amount (in kobo)

 
Suggest Edits

Fetch Plan

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/plan/id_or_plan_code
curl "https://api.paystack.co/plan/PLN_gx2wn530m0i3w3m" \
-H "Authorization: Bearer SECRET_KEY" 
-X GET
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Plan retrieved",
  "data": {
    "subscriptions": [],
    "integration": 100032,
    "domain": "test",
    "name": "Monthly retainer",
    "plan_code": "PLN_gx2wn530m0i3w3m",
    "description": null,
    "amount": 50000,
    "interval": "monthly",
    "send_invoices": true,
    "send_sms": true,
    "hosted_page": false,
    "hosted_page_url": null,
    "hosted_page_summary": null,
    "currency": "NGN",
    "id": 28,
    "createdAt": "2016-03-29T22:42:50.000Z",
    "updatedAt": "2016-03-29T22:42:50.000Z"
  }
}
 
Suggest Edits

Update Plan

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.paystack.co/plan/:id_or_plan_code
curl "https://api.paystack.co/plan/PLN_gx2wn530m0i3w3m" \
-H "Authorization: Bearer SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Monthly retainer (renamed)"}' \ 
-X PUT
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Plan updated. 1 subscription(s) affected"
}

Body Params

name
string

Name of plan

description
string

Short description of plan

amount
int32

Amount to be charged in kobo. Will override the amount for existing subscriptions.

interval
string

Interval in words. Valid intervals are hourly, daily, weekly, monthly, annually.

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
int32

Number of invoices to raise during subscription to this plan. Will not override invoice_limit set on active subscriptions.

 
Suggest Edits

Create Subscription

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/subscription
curl https://api.paystack.co/subscription \
-H "Authorization: Bearer SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"customer": "CUS_xnxdt6s1zg1f4nx", "plan": "PLN_gx2wn530m0i3w3m"}' \
-X POST
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Subscription successfully created",
  "data": {
    "customer": 1173,
    "plan": 28,
    "integration": 100032,
    "domain": "test",
    "start": 1459296064,
    "status": "active",
    "quantity": 1,
    "amount": 50000,
    "authorization": 79,
    "subscription_code": "SUB_vsyqdmlzble3uii",
    "email_token": "d7gofp6yppn3qz7",
    "id": 9,
    "createdAt": "2016-03-30T00:01:04.687Z",
    "updatedAt": "2016-03-30T00:01:04.687Z"
  }
}
{
  "status": false,
  "message": "The customer specified has no saved authorizations"
}

Body Params

customer
string
required

Customer's email address or customer code

plan
string
required

Plan code

authorization
string
required

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)

 

Note the email_token attribute for the subscription object. We create one on each subscription so customers can 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.

Suggest Edits

List Subscriptions

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/subscription
curl "https://api.paystack.co/subscription" \
-H "Authorization: Bearer SECRET_KEY" 
-X GET
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Subscriptions retrieved",
  "data": [
    {
      "customer": {
        "first_name": "BoJack",
        "last_name": "Horseman",
        "email": "bojack@horseman.com",
        "phone": "",
        "metadata": null,
        "domain": "test",
        "customer_code": "CUS_hdhye17yj8qd2tx",
        "risk_action": "default",
        "id": 84312,
        "integration": 100073,
        "createdAt": "2016-10-01T10:59:52.000Z",
        "updatedAt": "2016-10-01T10:59:52.000Z"
      },
      "plan": {
        "domain": "test",
        "name": "Weekly small chops",
        "plan_code": "PLN_0as2m9n02cl0kp6",
        "description": "Small chops delivered every week",
        "amount": 27000,
        "interval": "weekly",
        "send_invoices": true,
        "send_sms": true,
        "hosted_page": false,
        "hosted_page_url": null,
        "hosted_page_summary": null,
        "currency": "NGN",
        "migrate": null,
        "id": 1716,
        "integration": 100073,
        "createdAt": "2016-10-01T10:59:11.000Z",
        "updatedAt": "2016-10-01T10:59:11.000Z"
      },
      "integration": 123456,
      "authorization": 161811,
      "domain": "test",
      "start": 1475319599,
      "status": "active",
      "quantity": 1,
      "amount": 27000,
      "subscription_code": "SUB_6phdx225bavuwtb",
      "email_token": "ore84lyuwcv2esu",
      "easy_cron_id": "275226",
      "cron_expression": "0 0 * * 6",
      "next_payment_date": "2016-10-15T00:00:00.000Z",
      "open_invoice": "INV_qc875pkxpxuyodf",
      "id": 4192,
      "createdAt": "2016-10-01T10:59:59.000Z",
      "updatedAt": "2016-10-12T07:45:14.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "skipped": 0,
    "perPage": 50,
    "page": 1,
    "pageCount": 1
  }
}

Query Params

perPage
int32

Specify how many records you want to retrieve per page

page
int32

Specify exactly what page you want to retrieve

customer
int32

Filter by Customer ID

plan
int32

Filter by Plan ID

 
Suggest Edits

Disable Subscription

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/subscription/disable
curl https://api.paystack.co/subscription/disable \
-H "Authorization: Bearer SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"code": "SUB_vsyqdmlzble3uii", "token": "d7gofp6yppn3qz7"}' \
-X POST
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Subscription disabled successfully"
}

Body Params

code
string
required

Subscription code

token
string
required

Email token

 
Suggest Edits

Enable Subscription

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/subscription/enable
curl https://api.paystack.co/subscription/enable \
-H "Authorization: Bearer SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"code": "SUB_vsyqdmlzble3uii", "token": "d7gofp6yppn3qz7"}' \
-X POST
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Subscription enabled successfully"
}

Body Params

code
string
required

Subscription code

token
string
required

Email token

 
Suggest Edits

Fetch Subscription

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/subscription/id_or_subscription_code
curl "https://api.paystack.co/subscription/SUB_vsyqdmlzble3uii" \
-H "Authorization: Bearer SECRET_KEY" 
-X GET
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Subscription retrieved successfully",
  "data": {
    "invoices": [],
    "customer": {
      "first_name": "BoJack",
      "last_name": "Horseman",
      "email": "bojack@horsinaround.com",
      "phone": null,
      "metadata": {
        "photos": [
          {
            "type": "twitter",
            "typeId": "twitter",
            "typeName": "Twitter",
            "url": "https://d2ojpxxtu63wzl.cloudfront.net/static/61b1a0a1d4dda2c9fe9e165fed07f812_a722ae7148870cc2e33465d1807dfdc6efca33ad2c4e1f8943a79eead3c21311",
            "isPrimary": false
          }
        ]
      },
      "domain": "test",
      "customer_code": "CUS_xnxdt6s1zg1f4nx",
      "id": 1173,
      "integration": 100032,
      "createdAt": "2016-03-29T20:03:09.000Z",
      "updatedAt": "2016-03-29T20:53:05.000Z"
    },
    "plan": {
      "domain": "test",
      "name": "Monthly retainer (renamed)",
      "plan_code": "PLN_gx2wn530m0i3w3m",
      "description": null,
      "amount": 50000,
      "interval": "monthly",
      "send_invoices": true,
      "send_sms": true,
      "hosted_page": false,
      "hosted_page_url": null,
      "hosted_page_summary": null,
      "currency": "NGN",
      "id": 28,
      "integration": 100032,
      "createdAt": "2016-03-29T22:42:50.000Z",
      "updatedAt": "2016-03-29T23:51:41.000Z"
    },
    "integration": 100032,
    "authorization": {
      "domain": "test",
      "authorization_code": "AUTH_5u1q4898",
      "bin": null,
      "brand": null,
      "card_type": "Visa",
      "last4": "1381",
      "bank": null,
      "country_code": null,
      "country_name": null,
      "description": "Visa ending with 1381",
      "mobile": false,
      "id": 79,
      "integration": 100032,
      "customer": 1173,
      "card": 392,
      "createdAt": "2016-01-13T01:15:52.000Z",
      "updatedAt": "2016-01-13T01:15:52.000Z"
    },
    "domain": "test",
    "start": 1459296064,
    "status": "active",
    "quantity": 1,
    "amount": 50000,
    "subscription_code": "SUB_vsyqdmlzble3uii",
    "email_token": "d7gofp6yppn3qz7",
    "easy_cron_id": null,
    "cron_expression": "0 0 28 * *",
    "next_payment_date": "2016-04-28T07:00:00.000Z",
    "open_invoice": null,
    "id": 9,
    "createdAt": "2016-03-30T00:01:04.000Z",
    "updatedAt": "2016-03-30T00:22:58.000Z"
  }
}

Path Params

id_or_subscription_code
string
required
 
Suggest Edits

Create Page

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/page
curl https://api.paystack.co/page \
-H "Authorization: Bearer SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Offering collections", "description": "Give unto the Lord, and it shall be multiplied ten-fold to you."}' \
-X POST
curl https://api.paystack.co/page \
-H "Authorization: Bearer SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
      "name": "Offering collections", 
      "description": "Give unto the Lord, and it shall be multiplied ten-fold to you.", 
      "custom_fields": [
        {
          "display_name": "Church branch",
          "variable_name": "church_branch"
        }
      ]
    }' \
-X POST
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Page created",
  "data": {
    "name": "Offering collections",
    "description": "Give unto the Lord, and it shall be multiplied ten-fold to you.",
    "integration": 100032,
    "domain": "test",
    "slug": "5nApBwZkvY",
    "currency": "NGN",
    "active": true,
    "id": 18,
    "createdAt": "2016-03-30T00:49:57.514Z",
    "updatedAt": "2016-03-30T00:49:57.514Z"
  }
}

Body Params

name
string
required

Name of page

description
string

Short description of page

amount
int32

Default amount you want to accept using this page. If none is set, customer is free to provide any amount of their choice. The latter scenario is useful for accepting donations

slug
string

URL slug you would like to be associated with this page. Page will be accessible at https://paystack.com/pay/[slug]

redirect_url
string

If you would like Paystack to redirect someplace upon successful payment, specify the URL here.

custom_fields
array

If you would like to accept custom fields, specify them here. See sample code for details.

 

Send pages created to your customers by giving out a link in this format https://paystack.com/pay/:slug. For instance, a valid link for the page above would be https://paystack.com/pay/5nApBwZkvY

Suggest Edits

List Pages

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/page
curl "https://api.paystack.co/page" \
-H "Authorization: Bearer SECRET_KEY" 
-X GET
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Pages retrieved",
  "data": [
    {
      "integration": 100073,
      "plan": 1716,
      "domain": "test",
      "name": "Subscribe to plan: Weekly small chops",
      "description": null,
      "amount": null,
      "currency": "NGN",
      "slug": "sR7Ohx2iVd",
      "custom_fields": null,
      "redirect_url": null,
      "active": true,
      "migrate": null,
      "id": 2223,
      "createdAt": "2016-10-01T10:59:11.000Z",
      "updatedAt": "2016-10-01T10:59:11.000Z"
    },
    {
      "integration": 100073,
      "plan": null,
      "domain": "test",
      "name": "Special",
      "description": "Special page",
      "amount": 10000,
      "currency": "NGN",
      "slug": "special-me",
      "custom_fields": [
        {
          "display_name": "Speciality",
          "variable_name": "speciality"
        },
        {
          "display_name": "Age",
          "variable_name": "age"
        }
      ],
      "redirect_url": "http://special.url",
      "active": true,
      "migrate": null,
      "id": 1807,
      "createdAt": "2016-09-09T19:18:37.000Z",
      "updatedAt": "2016-09-14T17:51:49.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "skipped": 0,
    "perPage": "3",
    "page": 1,
    "pageCount": 1
  }
}

Query Params

perPage
int32

Specify how many records you want to retrieve per page

page
int32

Specify exactly what page you want to retrieve

 
Suggest Edits

Fetch Page

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/page/id_or_slug
curl "https://api.paystack.co/page/5nApBwZkvY" \
-H "Authorization: Bearer SECRET_KEY" 
-X GET
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Page retrieved",
  "data": {
    "integration": 100032,
    "domain": "test",
    "name": "Offering collections",
    "description": "Give unto the Lord, and it shall be multiplied ten-fold to you.",
    "amount": null,
    "currency": "NGN",
    "slug": "5nApBwZkvY",
    "active": true,
    "id": 18,
    "createdAt": "2016-03-30T00:49:57.000Z",
    "updatedAt": "2016-03-30T00:49:57.000Z"
  }
}

Path Params

id_or_slug
string
required
 
Suggest Edits

Update Page

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.paystack.co/page/:id_or_slug
curl "https://api.paystack.co/page/5nApBwZkvY" \
-H "Authorization: Bearer SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"description": "Give unto the Lord, and it shall be multiplied 10-fold to you."}' \ 
-X PUT
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Page updated",
  "data": {
    "domain": "test",
    "name": "Offering collections",
    "description": "Give unto the Lord, and it shall be multiplied 10-fold to you.",
    "amount": null,
    "currency": "NGN",
    "slug": "5nApBwZkvY",
    "active": true,
    "id": 18,
    "integration": 100032,
    "createdAt": "2016-03-30T00:49:57.000Z",
    "updatedAt": "2016-03-30T04:44:35.000Z"
  }
}

Body Params

name
string

Name of page

description
string

Short description of page

amount
string

Default amount you want to accept using this page. If none is set, customer is free to provide any amount of their choice. The latter scenario is useful for accepting donations

active
boolean

Set to false to deactivate page url

 
Suggest Edits

Check Slug Availability

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/page/check_slug_availability/slug
curl "https://api.paystack.co/page/check_slug_availability/fol-offerings" \
-H "Authorization: Bearer SECRET_KEY" 
-X GET
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Slug is available"
}

Path Params

slug
string
required

URL slug to be confirmed

 
Suggest Edits

Create Invoice

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/paymentrequest
curl --request POST \
  --url https://api.paystack.co/paymentrequest \
  --header 'authorization: Bearer SECRET_KEY' \
  --header 'content-type: application/json' \
  --data '{
	"description": "a test invoice",
	"line_items": [
		{"name": "item 1", "amount": 20000},
		{"name": "item 2", "amount": 20000}
	],
	"tax": [
		{"name": "VAT", "amount": 2000}
	],
	"customer": "CUS_je02lbimlqixzax",
	"due_date": "2017-05-08"
}'
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.paystack.co/paymentrequest",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n\t\"description\": \"a test invoice\",\n\t\"line_items\": [\n\t\t{\"name\": \"item 1\", \"amount\": 20000},\n\t\t{\"name\": \"item 2\", \"amount\": 20000}\n\t],\n\t\"tax\": [\n\t\t{\"name\": \"VAT\", \"amount\": 2000}\n\t],\n\t\"customer\": \"CUS_je02lbimlqixzax\",\n\t\"due_date\": \"2017-05-08\"\n}",
  CURLOPT_HTTPHEADER => array(
    "authorization: Bearer SECRET_KEY",
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
A binary file was returned

You couldn't be authenticated

{
    "status": true,
    "message": "Payment request created",
    "data": {
        "id": 23902,
        "domain": "test",
        "amount": 42000,
        "currency": "NGN",
        "due_date": "2017-05-08T00:00:00.000Z",
        "has_invoice": true,
        "invoice_number": 6,
        "description": "a test invoice",
        "line_items": [
            {
                "name": "item 1",
                "amount": 20000
            },
            {
                "name": "item 2",
                "amount": 20000
            }
        ],
        "tax": [
            {
                "name": "VAT",
                "amount": 2000
            }
        ],
        "request_code": "PRQ_3z3cfcsee63r16w",
        "status": "pending",
        "paid": false,
        "metadata": null,
        "notifications": [],
        "offline_reference": "119333023902",
        "customer": 2396797,
        "created_at": "2018-06-21T09:08:43.745Z"
    }
}

Body Params

description
string
line_items
array of strings

array of line items int the format [{"name":"item 1", "amount":2000}]

customer
string
required

customer id or code

tax
array of strings

array of taxes to be charged in the format [{"name":"VAT", "amount":2000}]

amount
int32
required

payment request amount. only useful if line items and tax values are ignored. endpoint will throw a friendly warning if neither is available.

currency
string

self explanatory. defaults to NGN

due_date
string
required

ISO 8601 representation of request due date

metadata
object
 
send_notification
boolean

Indicates whether Paystack sends an email notification to customer. Defaults to true

draft
boolean

Indicate if request should be saved as draft. Defaults to false and overrides send_notification

has_invoice
boolean

Set to true to create a draft invoice (adds an auto incrementing invoice number if none is provided) even if there are no line_items or tax passed

invoice_number
int32

Numeric value of invoice. Invoice will start from 1 and auto increment from there. This field is to help override whatever value Paystack decides. Auto increment for subsequent invoices continue from this point.

 
Suggest Edits

List Invoices

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/paymentrequest
curl --request GET \
  --url https://api.paystack.co/paymentrequest
var request = require("request");

var options = { method: 'GET', url: 'https://api.paystack.co/paymentrequest' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.paystack.co/paymentrequest")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.paystack.co/paymentrequest");

xhr.send(data);
import requests

url = "https://api.paystack.co/paymentrequest"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Query Params

customer
string

Filter by customer ID

status
string

Filter by invoice status

currency
string

Filter by currency

paid
string
include_archive
string

Show archived invoices

 
Suggest Edits

View Invoice

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/paymentrequest/invoice_id_or_code
curl --request GET \
  --url https://api.paystack.co/paymentrequest/invoice_id_or_code
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.paystack.co/paymentrequest/invoice_id_or_code' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.paystack.co/paymentrequest/invoice_id_or_code")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.paystack.co/paymentrequest/invoice_id_or_code");

xhr.send(data);
import requests

url = "https://api.paystack.co/paymentrequest/invoice_id_or_code"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

invoice_id_or_code
string
required
 
Suggest Edits

Verify Invoice

(no authorization required)

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/paymentrequest/verify/invoice_code
curl --request GET \
  --url https://api.paystack.co/paymentrequest/verify/invoice_code
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.paystack.co/paymentrequest/verify/invoice_code' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.paystack.co/paymentrequest/verify/invoice_code")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.paystack.co/paymentrequest/verify/invoice_code");

xhr.send(data);
import requests

url = "https://api.paystack.co/paymentrequest/verify/invoice_code"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Payment request retrieved",
  "data": {
    "transactions": [],
    "domain": "test",
    "invoice_code": "PRQ_0s8rciopfbjc74o",
    "description": "a test invoice",
    "line_items": [
      {
        "name": "item 1",
        "amount": 20000
      },
      {
        "name": "item 2",
        "amount": 20000
      }
    ],
    "tax": [
      {
        "name": "VAT",
        "amount": 2000
      }
    ],
    "amount": 42000,
    "currency": "NGN",
    "due_date": "2017-05-08T00:00:00.000Z",
    "status": "pending",
    "paid": false,
    "paid_at": null,
    "metadata": null,
    "notifications": [
      {
        "sent_at": "2017-05-07T19:48:25.456Z"
      },
      {
        "sent_at": "2017-05-07T20:20:22.684Z"
      }
    ],
    "id": 12,
    "integration": {
      "key": "pk_test_7977b9e4334501a8722cc9750870870d0519af03",
      "name": "Alexandar Haring",
      "logo": "https://s3-eu-west-1.amazonaws.com/pstk-integration-logos/ah.png",
      "allowed_currencies": [
        "NGN",
        "USD"
      ]
          },
    "customer": {
      "transactions": [],
      "subscriptions": [],
      "authorizations": [],
      "first_name": null,
      "last_name": null,
      "email": "me@ezra.wtf",
      "phone": null,
      "metadata": null,
      "domain": "test",
      "customer_code": "CUS_je02lbimlqixzax",
      "risk_action": "default",
      "id": 14257,
      "integration": 100032,
      "createdAt": "2016-04-13T09:42:15.000Z",
      "updatedAt": "2016-04-13T09:42:15.000Z"
    },
    "createdAt": "2017-05-07T19:48:24.000Z",
    "updatedAt": "2017-05-07T20:20:22.000Z",
    "pending_amount": 42000
  }
}

Path Params

invoice_code
string
required
 

Note that a key is added called pending_amount when you fetch an invoice. This is because when paying for an invoice, you can choose to pay part but not all. Whenever a successful transaction is made, the key updates to reveal what’s left of the invoice to pay. As a rule, the UI (frontend, or POS) should not allow payment of an amount greater than the pending amount.

Suggest Edits

Send Notification

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/paymentrequest/notify/:id_or_code
curl --request POST \
  --url https://api.paystack.co/paymentrequest/notify/:id_or_code
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.paystack.co/paymentrequest/notify/:id_or_code' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.paystack.co/paymentrequest/notify/:id_or_code")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.paystack.co/paymentrequest/notify/:id_or_code");

xhr.send(data);
import requests

url = "https://api.paystack.co/paymentrequest/notify/:id_or_code"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results
 
Suggest Edits

Get Invoice metrics for dashboard

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/paymentrequest/totals
curl --request GET \
  --url https://api.paystack.co/paymentrequest/totals
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.paystack.co/paymentrequest/totals' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.paystack.co/paymentrequest/totals")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.paystack.co/paymentrequest/totals");

xhr.send(data);
import requests

url = "https://api.paystack.co/paymentrequest/totals"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results
 
Suggest Edits

Finalize a Draft Invoice

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/paymentrequest/finalize/:id_or_code
curl --request POST \
  --url https://api.paystack.co/paymentrequest/finalize/:id_or_code
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.paystack.co/paymentrequest/finalize/:id_or_code' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.paystack.co/paymentrequest/finalize/:id_or_code")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.paystack.co/paymentrequest/finalize/:id_or_code");

xhr.send(data);
import requests

url = "https://api.paystack.co/paymentrequest/finalize/:id_or_code"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

send_notification
boolean

Indicates whether Paystack sends an email notification to customer. Defaults to true

 
Suggest Edits

Update Invoice

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.paystack.co/paymentrequest/:id_or_code
curl --request PUT \
  --url https://api.paystack.co/paymentrequest/:id_or_code
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.paystack.co/paymentrequest/:id_or_code' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.paystack.co/paymentrequest/:id_or_code")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.paystack.co/paymentrequest/:id_or_code");

xhr.send(data);
import requests

url = "https://api.paystack.co/paymentrequest/:id_or_code"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

description
string
amount
int32
line_items
string
tax
string
due_date
string
metadata
object
 
send_notification
boolean
currency
int32
customer
string

customer id

 
Suggest Edits

Archive Invoice

Used to archive an invoice. Invoice will no longer be fetched on list or returned on verify.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/invoice/archive/:id_or_code
curl --request POST \
  --url https://api.paystack.co/invoice/archive/:id_or_code
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.paystack.co/invoice/archive/:id_or_code' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.paystack.co/invoice/archive/:id_or_code")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.paystack.co/invoice/archive/:id_or_code");

xhr.send(data);
import requests

url = "https://api.paystack.co/invoice/archive/:id_or_code"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results
 
Suggest Edits

Fetch Settlements

Settlements made to your bank accounts and the bank accounts for your subaccounts

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/settlement
curl "https://api.paystack.co/settlement" \
-H "Authorization: Bearer SECRET_KEY" 
-X GET
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Settlements retrieved",
  "data": [
    {
      "integration": 199999,
      "settled_by": null,
      "settlement_date": "2016-11-04T00:00:00.000Z",
      "domain": "live",
      "total_amount": 28350,
      "status": "pending",
      "id": 8597,
      "createdAt": "2016-11-04T00:00:00.000Z",
      "updatedAt": null
    },
    {
      "integration": 199999,
      "subaccount": {
        "domain": "live",
        "subaccount_code": "ACCT_83uhio98ueej",
        "business_name": "Someone, Somewhere",
        "description": null,
        "primary_contact_name": null,
        "primary_contact_email": null,
        "primary_contact_phone": null,
        "metadata": null,
        "percentage_charge": 1,
        "is_verified": false,
        "settlement_bank": "Guaranty Trust Bank",
        "account_number": "0909090909",
        "settlement_schedule": "WEEKLY",
        "active": true,
        "migrate": null,
        "id": 23,
        "integration": 199999,
        "createdAt": "2016-10-03T13:14:36.000Z",
        "updatedAt": "2016-11-03T14:21:52.000Z"
      },
      "settled_by": null,
      "settlement_date": "2016-11-04T00:00:00.000Z",
      "domain": "live",
      "total_amount": 80000,
      "status": "pending",
      "id": 8598,
      "createdAt": "2016-11-04T00:00:00.000Z",
      "updatedAt": null
    },
    {
      "integration": 199999,
      "settled_by": null,
      "settlement_date": "2016-09-12T00:00:00.000Z",
      "domain": null,
      "total_amount": 9850,
      "status": "success",
      "id": 5625,
      "createdAt": "2016-09-12T00:00:00.000Z",
      "updatedAt": null
    }
  ],
  "meta": {
    "total": 4,
    "skipped": 0,
    "perPage": 50,
    "page": 1,
    "pageCount": 1
  }
}

Query Params

from
date

Lower bound of date range. Leave undefined to export settlement from day one.

to
date

Upper bound of date range. Leave undefined to export settlements till date.

subaccount
string

Provide a subaccount code to export only settlements for that subaccount. Set to none to export only transactions for the account.

 
Suggest Edits

Create Transfer Recipient

Creates a new recipient. A duplicate account number will lead to the retrieval of the existing record.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/transferrecipient
curl -X POST -H "Authorization: Bearer SECRET_KEY" -H "Content-Type: application/json" -d '{ 
   "type": "nuban",
   "name": "Zombie",
   "description": "Zombier",
   "account_number": "01000000010",
   "bank_code": "044",
   "currency": "NGN",
   "metadata": {
      "job": "Flesh Eater"
    }
 }' "https://api.paystack.co/transferrecipient"
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Recipient created",
  "data": {
    "type": "nuban",
    "name": "Zombie",
    "description": "Zombier",
    "metadata": {
      "job": "Flesh Eater"
    },
    "domain": "test",
    "details": {
      "account_number": "0100000010",
      "account_name": null,
      "bank_code": "044",
      "bank_name": "Access Bank"
    },
    "currency": "NGN",
    "recipient_code": "RCP_1i2k27vk4suemug",
    "active": true,
    "id": 27,
    "createdAt": "2017-02-02T19:35:33.686Z",
    "updatedAt": "2017-02-02T19:35:33.686Z"
  }
}

Body Params

type
string
required

nuban / authorization

name
string
required

A name for the recipient

metadata
object

Store additional information about your recipient in a structured format. JSON

 
account_number
string

Required if type is nuban

bank_code
string

Required if type is nuban. You can get the list of Bank Codes by calling the List Banks endpoint.

currency
string

Currency for the account receiving the transfer.

description
string
authorization_code
string

An authorization code from a previous transaction

 

Creates a new recipient. An duplicate account number will lead to the retrieval of the existing record.

Suggest Edits

List Transfer Recipients

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/transferrecipient
curl "https://api.paystack.co/transferrecipient" \
-H "Authorization: Bearer SECRET_KEY" 
-X GET
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Recipients retrieved",
  "data": [
    {
      "domain": "test",
      "type": "nuban",
      "currency": "NGN",
      "name": "Flesh",
      "details": {
        "account_number": "01000000000",
        "account_name": null,
        "bank_code": "044",
        "bank_name": "Access Bank"
      },
      "metadata": {
        "job": "Eater"
      },
      "recipient_code": "RCP_2x5j67tnnw1t98k",
      "active": true,
      "id": 28,
      "createdAt": "2017-02-02T19:39:04.000Z",
      "updatedAt": "2017-02-02T19:39:04.000Z"
    },
    {
      "integration": 100073,
      "domain": "test",
      "type": "nuban",
      "currency": "NGN",
      "name": "Flesh",
      "details": {
        "account_number": "0100000010",
        "account_name": null,
        "bank_code": "044",
        "bank_name": "Access Bank"
      },
      "metadata": {},
      "recipient_code": "RCP_1i2k27vk4suemug",
      "active": true,
      "id": 27,
      "createdAt": "2017-02-02T19:35:33.000Z",
      "updatedAt": "2017-02-02T19:35:33.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "skipped": 0,
    "perPage": 50,
    "page": 1,
    "pageCount": 1
  }
}

Query Params

perPage
int32

Specify how many records you want to retrieve per page

page
int32

Specify exactly what page you want to retrieve

 
Suggest Edits

Initiate Transfer

Status of transfer object returned will be ‘pending’ if OTP is disabled. In the event that an OTP is required, status will read ‘otp’.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/transfer
curl https://api.paystack.co/transfer \
-H "Authorization: Bearer SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"source": "balance", "reason": "Calm down", "amount":3794800, "recipient": "RCP_gx2wn530m0i3w3m"}' \
-X POST
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Transfer requires OTP to continue",
  "data": {
    "integration": 100073,
    "domain": "test",
    "amount": 3794800,
    "currency": "NGN",
    "source": "balance",
    "reason": "Calm down",
    "recipient": 28,
    "status": "otp",
    "transfer_code": "TRF_1ptvuv321ahaa7q",
    "id": 14,
    "createdAt": "2017-02-03T17:21:54.508Z",
    "updatedAt": "2017-02-03T17:21:54.508Z"
  }
}
{
  "status": false,
  "message": "The customer specified has no saved authorizations"
}

Body Params

source
string
required

Where should we transfer from? Only balance for now

amount
int32
required

Amount to transfer in kobo

currency
string
reason
string
recipient
string
required

Code for transfer recipient

reference
string

If specified, the field should be a unique identifier (in lowercase) for the object. Only -,_ and alphanumeric characters allowed.

 

Status of transfer object returned will be ‘pending’ if OTP is disabled. In the event that an OTP is required, status will read ‘otp’.

Suggest Edits

List Transfers

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/transfer
curl -X GET -H "Authorization: Bearer SECRET_KEY" "https://api.paystack.co/transfer"
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Transfers retrieved",
  "data": [
    {
      "integration": 100073,
      "recipient": {
        "domain": "test",
        "type": "nuban",
        "currency": "NGN",
        "name": "Flesh",
        "details": {
          "account_number": "olounje",
          "account_name": null,
          "bank_code": "044",
          "bank_name": "Access Bank"
        },
        "description": "Eater",
        "metadata": null,
        "recipient_code": "RCP_2x5j67tnnw1t98k",
        "active": true,
        "id": 28,
        "integration": 100073,
        "createdAt": "2017-02-02T19:39:04.000Z",
        "updatedAt": "2017-02-02T19:39:04.000Z"
      },
      "domain": "test",
      "amount": 4400,
      "currency": "NGN",
      "source": "balance",
      "source_details": null,
      "reason": "Eater",
      "status": "otp",
      "failures": null,
      "transfer_code": "TRF_1ptvuv321ahaa7q",
      "id": 14,
      "createdAt": "2017-02-03T17:21:54.000Z",
      "updatedAt": "2017-02-03T17:21:54.000Z"
    },
    {
      "integration": 100073,
      "recipient": {
        "domain": "test",
        "type": "nuban",
        "currency": "USD",
        "name": "FleshUSD",
        "details": {
          "account_number": "1111111111",
          "account_name": null,
          "bank_code": "044",
          "bank_name": "Access Bank"
        },
        "description": "EaterUSD",
        "metadata": null,
        "recipient_code": "RCP_bi84k5gguakuqmg",
        "active": true,
        "id": 22,
        "integration": 100073,
        "createdAt": "2017-01-23T16:52:48.000Z",
        "updatedAt": "2017-01-23T16:52:48.000Z"
      },
      "domain": "test",
      "amount": 3300,
      "currency": "NGN",
      "source": "balance",
      "source_details": null,
      "reason": "I love you",
      "status": "otp",
      "failures": null,
      "transfer_code": "TRF_5pr8ypzb0htx0cn",
      "id": 13,
      "createdAt": "2017-01-23T16:55:59.000Z",
      "updatedAt": "2017-01-23T16:55:59.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "skipped": 0,
    "perPage": 50,
    "page": 1,
    "pageCount": 1
  }
}

Query Params

perPage
int32
page
int32
 
Suggest Edits

Fetch Transfer

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/transfer/id_or_code
curl "https://api.paystack.co/transfer/TRF_2x5j67tnnw1t98k" \
-H "Authorization: Bearer SECRET_KEY" 
-X GET
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Transfer retrieved",
  "data": {
    "recipient": {
      "domain": "test",
      "type": "nuban",
      "currency": "NGN",
      "name": "Flesh",
      "details": {
        "account_number": "olounje",
        "account_name": null,
        "bank_code": "044",
        "bank_name": "Access Bank"
      },
      "metadata": null,
      "recipient_code": "RCP_2x5j67tnnw1t98k",
      "active": true,
      "id": 28,
      "integration": 100073,
      "createdAt": "2017-02-02T19:39:04.000Z",
      "updatedAt": "2017-02-02T19:39:04.000Z"
    },
    "domain": "test",
    "amount": 4400,
    "currency": "NGN",
    "source": "balance",
    "source_details": null,
    "reason": "Redemption",
    "status": "pending",
    "failures": null,
    "transfer_code": "TRF_2x5j67tnnw1t98k",
    "id": 14938,
    "createdAt": "2017-02-03T17:21:54.000Z",
    "updatedAt": "2017-02-03T17:21:54.000Z"
  }
}

Path Params

id_or_code
string
required

An ID or code for the transfer whose details you want to retrieve.

 
Suggest Edits

Finalize Transfer

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/transfer/finalize_transfer
curl https://api.paystack.co/transfer/finalize_transfer \
-H "Authorization: Bearer SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"transfer_code": "TRF_vsyqdmlzble3uii", "otp": "928783"}' \
-X POST
A binary file was returned

You couldn't be authenticated

Body Params

transfer_code
string
required

Transfer code

otp
string
required

OTP sent to business phone to verify transfer

 

This step is not required if OTP is disabled.

Suggest Edits

Initiate Bulk Transfer

You need to disable the Transfers OTP requirement to use this endpoint.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/transfer/bulk
curl https://api.paystack.co/transfer \
-H "Authorization: Bearer SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
	"currency": "NGN",
	"source": "balance",
	"transfers": [
	{
	"amount": 50000,
	"recipient": "RCP_db342dvqvz9qcrn"
	},
	{
	"amount": 50000,
	"recipient": "RCP_db342dvqvz9qcrn"
	}
	]
}' \
-X POST
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "2 transfers queued."
}
{
  "status": false,
  "message": "The customer specified has no saved authorizations"
}

Body Params

(no name)
array
 

Status of transfer object returned will be ‘pending’ if OTP is disabled. In the event that an OTP is required, status will read ‘otp’.

Suggest Edits

Check Balance

You can only transfer from what you have

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/balance
curl -X GET -H "Authorization: Bearer SECRET_KEY" "https://api.paystack.co/balance"
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Balances retrieved",
  "data": [
    {
      "currency": "NGN",
      "balance": 1700000
    }
  ]
}
 
Suggest Edits

Resend OTP for Transfer

Generates a new OTP and sends to customer in the event they are having trouble receiving one.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/transfer/resend_otp
curl https://api.paystack.co/transfer/resend_otp \
-H "Authorization: Bearer SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"transfer_code": "TRF_vsyqdmlzble3uii"}' \
-X POST
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "OTP has been resent"
}

Body Params

transfer_code
string
required

Transfer code

reason
string
required

either resend_otp or transfer

 
Suggest Edits

Disable OTP requirement for Transfers

In the event that you want to be able to complete transfers programmatically without use of OTPs, this endpoint helps disable that….with an OTP. No arguments required. You will get an OTP.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/transfer/disable_otp
curl https://api.paystack.co/transfer/disable_otp \
-H "Authorization: Bearer SECRET_KEY" \
-X POST
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "OTP has been sent to mobile number ending with 4321"
}
 

In the event that you want to be able to complete transfers programmatically without use of OTPs, this endpoint helps disable that….with an OTP. No arguments required. An OTP is sent to you on your business phone.

Suggest Edits

Finalize Disabling of OTP requirement for Transfers

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/transfer/disable_otp_finalize
curl https://api.paystack.co/transfer/disable_otp_finalize \
-H "Authorization: Bearer SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"otp": "928783"}' \
-X POST
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "OTP requirement for transfers has been disabled"
}

Body Params

otp
string
required

OTP sent to business phone to verify disabling OTP requirement

 
Suggest Edits

Enable OTP requirement for Transfers

In the event that a customer wants to stop being able to complete transfers programmatically, this endpoint helps turn OTP requirement back on. No arguments required.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/transfer/enable_otp
curl https://api.paystack.co/transfer/enable_otp \
-H "Authorization: Bearer SECRET_KEY" \
-X POST
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "OTP requirement for transfers has been enabled"
}
 
Suggest Edits

Initiate Bulk Charge

Send an array of objects with authorization codes and amount in kobo so we can process transactions as a batch.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/bulkcharge
curl -X POST
-H "Authorization: Bearer SECRET_KEY"
-H "Content-Type: application/json" 
-d '[{"authorization": "AUTH_n95vpedf", "amount": 2500}, {"authorization": "AUTH_ljdt4e4j", "amount": 1500}]' "https://api.paystack.co/bulkcharge"
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Charges have been queued",
  "data": {
    "domain": "test",
    "batch_code": "BCH_180tl7oq7cayggh",
    "status": "active",
    "id": 17,
    "integration": 100073,
    "createdAt": "2017-02-04T05:44:19.000Z",
    "updatedAt": "2017-02-04T05:44:19.000Z"
  }
}

Body Params

(no name)
array
 
Suggest Edits

List Bulk Charge Batches

This lists all bulk charge batches created by the integration. Statuses can be active, paused, or complete.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/bulkcharge
curl -X GET 
-H "Authorization: Bearer SECRET_KEY"
"https://api.paystack.co/bulkcharge"
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Bulk charges retrieved",
  "data": [
    {
      "domain": "test",
      "batch_code": "BCH_1nV4L1D7cayggh",
      "status": "complete",
      "id": 1733,
      "createdAt": "2017-02-04T05:44:19.000Z",
      "updatedAt": "2017-02-04T05:45:02.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "skipped": 0,
    "perPage": 50,
    "page": 1,
    "pageCount": 1
  }
}

Query Params

perPage
int32
page
int32
 
Suggest Edits

Fetch Bulk Charge Batch

This endpoint retrieves a specific batch code. It also returns useful information on its progress by way of the total_charges and pending_charges attributes.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/bulkcharge/id_or_code
curl "https://api.paystack.co/bulkcharge/BCH_180tl7oq7cayggh" \
-H "Authorization: Bearer SECRET_KEY" 
-X GET
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Bulk charge retrieved",
  "data": {
    "domain": "test",
    "batch_code": "BCH_180tl7oq7cayggh",
    "status": "complete",
    "id": 17,
    "total_charges": 0,
    "pending_charges": 0,
    "createdAt": "2017-02-04T05:44:19.000Z",
    "updatedAt": "2017-02-04T05:45:02.000Z"
  }
}

Path Params

id_or_code
string
required

An ID or code for the transfer whose details you want to retrieve.

 
Suggest Edits

Fetch Charges in a Batch

This endpoint retrieves the charges associated with a specified batch code. Pagination parameters are available. You can also filter by status. Charge statuses can be pending, success or failed.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/bulkcharge/id_or_code/charges
curl "https://api.paystack.co/bulkcharge/BCH_180tl7oq7cayggh/charges" \
-H "Authorization: Bearer SECRET_KEY" 
-X GET
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Bulk charge items retrieved",
  "data": [
    {
      "integration": 100073,
      "bulkcharge": 18,
      "customer": {
        "id": 181336,
        "first_name": null,
        "last_name": null,
        "email": "support@paystack.com",
        "customer_code": "CUS_dw5posshfd1i5uj",
        "phone": null,
        "metadata": null,
        "risk_action": "default"
      },
      "authorization": {
        "authorization_code": "AUTH_jh3cfpca",
        "bin": "412345",
        "last4": "1381",
        "exp_month": "08",
        "exp_year": "2088",
        "channel": "card",
        "card_type": "visa visa",
        "bank": "TEST BANK",
        "country_code": "NG",
        "brand": "visa",
        "reusable": true
      },
      "transaction": {
        "id": 718835,
        "domain": "test",
        "status": "success",
        "reference": "2mr588n0ik9enja",
        "amount": 20500,
        "message": null,
        "gateway_response": "Successful",
        "paid_at": "2017-02-04T06:05:02.000Z",
        "created_at": "2017-02-04T06:05:02.000Z",
        "channel": "card",
        "currency": "NGN",
        "ip_address": null,
        "metadata": "",
        "log": null,
        "fees": null,
        "fees_split": null,
        "customer": {},
        "authorization": {},
        "plan": {},
        "subaccount": {},
        "paidAt": "2017-02-04T06:05:02.000Z",
        "createdAt": "2017-02-04T06:05:02.000Z"
      },
      "domain": "test",
      "amount": 20500,
      "currency": "NGN",
      "status": "success",
      "id": 15,
      "createdAt": "2017-02-04T06:04:26.000Z",
      "updatedAt": "2017-02-04T06:05:03.000Z"
    },
    {
      "integration": 100073,
      "bulkcharge": 18,
      "customer": {
        "id": 181336,
        "first_name": null,
        "last_name": null,
        "email": "support@paystack.com",
        "customer_code": "CUS_dw5posshfd1i5uj",
        "phone": null,
        "metadata": null,
        "risk_action": "default"
      },
      "authorization": {
        "authorization_code": "AUTH_qdyfjbl3",
        "bin": "412345",
        "last4": "1381",
        "exp_month": "08",
        "exp_year": "2018",
        "channel": "card",
        "card_type": "visa visa",
        "bank": "TEST BANK",
        "country_code": "NG",
        "brand": "visa",
        "reusable": true
      },
      "transaction": {
        "id": 718836,
        "domain": "test",
        "status": "success",
        "reference": "5xkmvfe2h4065zl",
        "amount": 11500,
        "message": null,
        "gateway_response": "Successful",
        "paid_at": "2017-02-04T06:05:02.000Z",
        "created_at": "2017-02-04T06:05:02.000Z",
        "channel": "card",
        "currency": "NGN",
        "ip_address": null,
        "metadata": "",
        "log": null,
        "fees": null,
        "fees_split": null,
        "customer": {},
        "authorization": {},
        "plan": {},
        "subaccount": {},
        "paidAt": "2017-02-04T06:05:02.000Z",
        "createdAt": "2017-02-04T06:05:02.000Z"
      },
      "domain": "test",
      "amount": 11500,
      "currency": "NGN",
      "status": "success",
      "id": 16,
      "createdAt": "2017-02-04T06:04:26.000Z",
      "updatedAt": "2017-02-04T06:05:03.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "skipped": 0,
    "perPage": 50,
    "page": 1,
    "pageCount": 1
  }
}

Path Params

id_or_code
string
required

An ID or code for the batch whose charges you want to retrieve.

Query Params

status
string

pending, success or failed

perPage
int32
page
int32
 
Suggest Edits

Pause Bulk Charge Batch

Use this endpoint to pause processing a batch

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/bulkcharge/pause/batch_code
curl https://api.paystack.co/bulkcharge/pause/BCH_1nv4lld3j1gdhqz \
-H "Authorization: Bearer SECRET_KEY" \
-X GET
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Bulk charge batch has been paused"
}

Path Params

batch_code
string
required
 
Suggest Edits

Resume Bulk Charge Batch

Use this endpoint to pause processing a batch

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/bulkcharge/resume/batch_code
curl https://api.paystack.co/bulkcharge/resume/BCH_1nv4lld3j1gdhqz \
-H "Authorization: Bearer SECRET_KEY" \
-X GET
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Bulk charge batch has been resumed"
}

Path Params

batch_code
string
required
 
Suggest Edits

Fetch Payment Session Timeout

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/integration/payment_session_timeout
curl --request GET \
  --url https://api.paystack.co/integration/payment_session_timeout
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.paystack.co/integration/payment_session_timeout' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.paystack.co/integration/payment_session_timeout")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.paystack.co/integration/payment_session_timeout");

xhr.send(data);
import requests

url = "https://api.paystack.co/integration/payment_session_timeout"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Payment session timeout retrieved",
  "data": {
    "payment_session_timeout": 30
  }
}
 
Suggest Edits

Update Payment Session Timeout

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.paystack.co/integration/payment_session_timeout
curl --request PUT \
  --url https://api.paystack.co/integration/payment_session_timeout
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.paystack.co/integration/payment_session_timeout' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.paystack.co/integration/payment_session_timeout")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.paystack.co/integration/payment_session_timeout");

xhr.send(data);
import requests

url = "https://api.paystack.co/integration/payment_session_timeout"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Payment session timeout updated",
  "data": {
    "payment_session_timeout": 30
  }
}

Body Params

timeout
int32

Time before stopping session (in seconds). Set to 0 to cancel session timeouts

 
Suggest Edits

Charge

Send card details or bank details or authorization code to start a charge.
Simple guide to charging cards directly https://developers.paystack.co/docs/charging-from-your-backend

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/charge
{
  email:"some@body.nice",
  amount:"10000",
  metadata:{
    custom_fields:[
      {
        value:"makurdi",
        display_name: "Donation for",
        variable_name: "donation_for"
      }
    ]
  },
  bank:{
      code:"057",
      account_number:"0000000000"
  },
  birthday:"1995-12-23"
}
{
  email:"some@body.nice",
  amount:"10000",
  metadata:{
    custom_fields:[
      {
        value:"makurdi",
        display_name: "Donation for",
        variable_name: "donation_for"
      }
    ]
  },
  card:{
    cvv:"408",
    number:"4084084084084081",
    expiry_month:"01",
    expiry_year:"99"
  }
}
{
  email:"some@body.nice",
  amount:"10000",
  metadata:{
    custom_fields:[
      {
        value:"makurdi",
        display_name: "Donation for",
        variable_name: "donation_for"
      }
    ]
  },
  authorization_code:"AUTH_ahs12opq9",
  pin:"0000"
}
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "0t4gwo2ft6q0n9h",
    "status": "send_otp",
    "display_text": "Please send OTP"
  }
}
{
  "status": false,
  "message": "Email address is required for association with card"
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "5bwib5v6anhe9xa",
    "status": "pending"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "apg8mnjf5yg7zp8",
    "status": "send_pin"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "bc9w93gh629a4d7",
    "status": "failed",
    "message": "Transaction declined. Please use the test card."
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "amount": 200,
    "currency": "NGN",
    "transaction_date": "2017-05-24T05:56:12.000Z",
    "status": "success",
    "reference": "zuvbpizfcf2fs7y",
    "domain": "test",
    "metadata": {
   	"custom_fields":[
   		{
   			"display_name":"Merchant name",
   			"variable_name":"merchant_name",
   			"value":"Van Damme"
		},
		{
   			"display_name":"Paid Via",
   			"variable_name":"paid_via",
   			"value":"API call"
		}
   	]
   },
    "gateway_response": "Successful",
    "message": null,
    "channel": "card",
    "ip_address": "54.154.89.28, 162.158.38.82, 172.31.38.35",
    "log": null,
    "fees": 3,
    "authorization": {
      "authorization_code": "AUTH_6tmt288t0o",
      "bin": "408408",
      "last4": "4081",
      "exp_month": "12",
      "exp_year": "2020",
      "channel": "card",
      "card_type": "visa visa",
      "bank": "TEST BANK",
      "country_code": "NG",
      "brand": "visa",
      "reusable": true,
      "signature": "SIG_uSYN4fv1adlAuoij8QXh"
    },
    "customer": {
      "id": 14571,
      "first_name": null,
      "last_name": null,
      "email": "ibrahim@paystack.co",
      "customer_code": "CUS_hns72vhhtos0f0k",
      "phone": null,
      "metadata": null,
      "risk_action": "default"
    },
    "plan": null
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "apg8mnjf5yg7zp8",
    "url":"https://standard.paystack.co/close",
    "status": "open_url"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "0t4gwo2ft6q0n9h",
    "status": "send_phone",
    "display_text": "Please send phone"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "0t4gwo2ft6q0n9h",
    "status": "send_birthday",
    "display_text": "Please send your birthday"
  }
}

Body Params

email
string
required

Customer's email address

amount
int32
required

Amount in kobo

card
object

Card to be charged (don't send if charging an authorization code or bank account)

 
card.number
string
required

Card Number

card.cvv
string
required

Card security code

card.expiry_month
string
required

Expiry month of card

card.expiry_year
string
required

Expiry year of card

bank
object

Bank account to charge (don't send if charging an authorization code or card)

 
bank.code
string
required

A code for the bank (check banks for the banks supported. Only the ones for which paywithbank is true will work.

bank.account_number
string
required

10 digit nuban for the account to charge

authorization_code
string

An authorization code to charge (don't send if charging a card or bank account)

pin
string

4-digit PIN (send with a non-reusable authorization code)

metadata
object

A JSON object

 
reference
string

Unique transaction reference. Only -,., = and alphanumeric characters allowed.

 

Not suited for background processing

This endpoint returns statuses that may require user input.

Suggest Edits

Submit PIN

Submit PIN to continue a charge

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/charge/submit_pin
curl --request POST \
  --url https://api.paystack.co/charge/submit_pin
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.paystack.co/charge/submit_pin' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.paystack.co/charge/submit_pin")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.paystack.co/charge/submit_pin");

xhr.send(data);
import requests

url = "https://api.paystack.co/charge/submit_pin"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "5bwib5v6anhe9xa",
    "status": "pending"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "bc9w93gh629a4d7",
    "status": "failed",
    "message": "Transaction declined. Please use the test card."
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "amount": 200,
    "currency": "NGN",
    "transaction_date": "2017-05-24T05:56:12.000Z",
    "status": "success",
    "reference": "zuvbpizfcf2fs7y",
    "domain": "test",
    "metadata": {
   	"custom_fields":[
   		{
   			"display_name":"Merchant name",
   			"variable_name":"merchant_name",
   			"value":"Van Damme"
		},
		{
   			"display_name":"Paid Via",
   			"variable_name":"paid_via",
   			"value":"API call"
		}
   	]
   },
    "gateway_response": "Successful",
    "message": null,
    "channel": "card",
    "ip_address": "54.154.89.28, 162.158.38.82, 172.31.38.35",
    "log": null,
    "fees": 3,
    "authorization": {
      "authorization_code": "AUTH_6tmt288t0o",
      "bin": "408408",
      "last4": "4081",
      "exp_month": "12",
      "exp_year": "2000",
      "channel": "card",
      "card_type": "visa visa",
      "bank": "TEST BANK",
      "country_code": "NG",
      "brand": "visa",
      "reusable": true,
      "signature": "SIG_uSYN4fv1adlAuoij8QXh"
    },
    "customer": {
      "id": 14571,
      "first_name": null,
      "last_name": null,
      "email": "ibrahim@paytsack.co",
      "customer_code": "CUS_hns72vhhtos0f0k",
      "phone": null,
      "metadata": null,
      "risk_action": "default"
    },
    "plan": null
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "0t4gwo2ft6q0n9h",
    "status": "send_otp",
    "display_text": "Please send OTP"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "0t4gwo2ft6q0n9h",
    "status": "send_phone",
    "display_text": "Please send your phone number"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "apg8mnjf5yg7zp8",
    "url":"https://standard.paystack.co/close",
    "status": "open_url"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "apg8mnjf5yg7zp8",
    "status": "send_pin",
    "diaplay_text": "The PIN must be exactly 4 digits"
  }
}
{
  "status": false,
  "message": "Transaction reference is invalid"
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "0t4gwo2ft6q0n9h",
    "status": "send_birthday",
    "display_text": "Please send your birthday"
  }
}

Body Params

pin
string
required

PIN submitted by user

reference
string
required

reference for transaction that requested pin

 
Suggest Edits

Submit OTP

Submit OTP to complete a charge

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/charge/submit_otp
curl --request POST \
  --url https://api.paystack.co/charge/submit_otp
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.paystack.co/charge/submit_otp' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.paystack.co/charge/submit_otp")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.paystack.co/charge/submit_otp");

xhr.send(data);
import requests

url = "https://api.paystack.co/charge/submit_otp"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "5bwib5v6anhe9xa",
    "status": "pending"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "bc9w93gh629a4d7",
    "status": "failed",
    "message": "Transaction declined. Please use the test card."
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "amount": 200,
    "currency": "NGN",
    "transaction_date": "2017-05-24T05:56:12.000Z",
    "status": "success",
    "reference": "zuvbpizfcf2fs7y",
    "domain": "test",
    "metadata": {
   	"custom_fields":[
   		{
   			"display_name":"Merchant name",
   			"variable_name":"merchant_name",
   			"value":"Van Damme"
		},
		{
   			"display_name":"Paid Via",
   			"variable_name":"paid_via",
   			"value":"API call"
		}
   	]
   },
    "gateway_response": "Successful",
    "message": null,
    "channel": "card",
    "ip_address": "54.154.89.28, 162.158.38.82, 172.31.38.35",
    "log": null,
    "fees": 3,
    "authorization": {
      "authorization_code": "AUTH_6tmt288t0o",
      "bin": "408408",
      "last4": "4081",
      "exp_month": "12",
      "exp_year": "2000",
      "channel": "card",
      "card_type": "visa visa",
      "bank": "TEST BANK",
      "country_code": "NG",
      "brand": "visa",
      "reusable": true,
      "signature": "SIG_uSYN4fv1adlAuoij8QXh"
    },
    "customer": {
      "id": 14571,
      "first_name": null,
      "last_name": null,
      "email": "ibrahim@paytsack.co",
      "customer_code": "CUS_hns72vhhtos0f0k",
      "phone": null,
      "metadata": null,
      "risk_action": "default"
    },
    "plan": null
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "0t4gwo2ft6q0n9h",
    "status": "send_otp",
    "display_text": "OTP must have at least one character"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "0t4gwo2ft6q0n9h",
    "status": "send_phone",
    "display_text": "Please send your phone number"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "apg8mnjf5yg7zp8",
    "url":"https://standard.paystack.co/close",
    "status": "open_url"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "apg8mnjf5yg7zp8",
    "status": "send_pin",
    "diaplay_text": "The PIN must be exactly 4 digits"
  }
}
{
  "status": false,
  "message": "Transaction reference is invalid"
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "0t4gwo2ft6q0n9h",
    "status": "send_birthday",
    "display_text": "Please send your birthday"
  }
}

Body Params

otp
string

OTP submitted by user

reference
string

reference for ongoing transaction

 
Suggest Edits

Submit Phone

Submit Phone when requested

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/charge/submit_phone
curl --request POST \
  --url https://api.paystack.co/charge/submit_phone
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.paystack.co/charge/submit_phone' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.paystack.co/charge/submit_phone")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.paystack.co/charge/submit_phone");

xhr.send(data);
import requests

url = "https://api.paystack.co/charge/submit_phone"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "5bwib5v6anhe9xa",
    "status": "pending"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "bc9w93gh629a4d7",
    "status": "failed",
    "message": "Error occured while enrolling you for OTP!"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "ojk8k0bimgftf0x",
    "status": "send_otp",
    "display_text": "Please send OTP (none will be sent to your phone)"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "apg8mnjf5yg7zp8",
    "url":"https://standard.paystack.co/close",
    "status": "open_url"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "apg8mnjf5yg7zp8",
    "status": "send_pin"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "0t4gwo2ft6q0n9h",
    "status": "send_phone",
    "display_text": "The phone number must have at least one character"
  }
}
{
  "status": false,
  "message": "Transaction reference is invalid"
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "amount": 200,
    "currency": "NGN",
    "transaction_date": "2017-05-24T05:56:12.000Z",
    "status": "success",
    "reference": "zuvbpizfcf2fs7y",
    "domain": "test",
    "metadata": {
   	"custom_fields":[
   		{
   			"display_name":"Merchant name",
   			"variable_name":"merchant_name",
   			"value":"Van Damme"
		},
		{
   			"display_name":"Paid Via",
   			"variable_name":"paid_via",
   			"value":"API call"
		}
   	]
   },
    "gateway_response": "Successful",
    "message": null,
    "channel": "card",
    "ip_address": "54.154.89.28, 162.158.38.82, 172.31.38.35",
    "log": null,
    "fees": 3,
    "authorization": {
      "authorization_code": "AUTH_6tmt288t0o",
      "bin": "408408",
      "last4": "4081",
      "exp_month": "12",
      "exp_year": "2000",
      "channel": "card",
      "card_type": "visa visa",
      "bank": "TEST BANK",
      "country_code": "NG",
      "brand": "visa",
      "reusable": true,
      "signature": "SIG_uSYN4fv1adlAuoij8QXh"
    },
    "customer": {
      "id": 14571,
      "first_name": null,
      "last_name": null,
      "email": "ibrahim@paytsack.co",
      "customer_code": "CUS_hns72vhhtos0f0k",
      "phone": null,
      "metadata": null,
      "risk_action": "default"
    },
    "plan": null
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "0t4gwo2ft6q0n9h",
    "status": "send_birthday",
    "display_text": "Please send your birthday"
  }
}

Body Params

phone
string

Phone submitted by user

reference
string

reference for ongoing transaction

 
Suggest Edits

Submit Birthday

Submit Birthday when requested

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/charge/submit_birthday
curl --request POST \
  --url https://api.paystack.co/charge/submit_birthday
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.paystack.co/charge/submit_birthday' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.paystack.co/charge/submit_birthday")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.paystack.co/charge/submit_birthday");

xhr.send(data);
import requests

url = "https://api.paystack.co/charge/submit_birthday"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "5bwib5v6anhe9xa",
    "status": "pending"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "bc9w93gh629a4d7",
    "status": "failed",
    "message": "Error occured while enrolling you for OTP!"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "ojk8k0bimgftf0x",
    "status": "send_otp",
    "display_text": "Please send OTP (none will be sent to your phone)"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "0t4gwo2ft6q0n9h",
    "status": "send_phone",
    "display_text": "Please send your phone number"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "apg8mnjf5yg7zp8",
    "url":"https://standard.paystack.co/close",
    "status": "open_url"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "apg8mnjf5yg7zp8",
    "status": "send_pin",
    "diaplay_text": "The PIN must be exactly 4 digits"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "amount": 200,
    "currency": "NGN",
    "transaction_date": "2017-05-24T05:56:12.000Z",
    "status": "success",
    "reference": "zuvbpizfcf2fs7y",
    "domain": "test",
    "metadata": {
   	"custom_fields":[
   		{
   			"display_name":"Merchant name",
   			"variable_name":"merchant_name",
   			"value":"Van Damme"
		},
		{
   			"display_name":"Paid Via",
   			"variable_name":"paid_via",
   			"value":"API call"
		}
   	]
   },
    "gateway_response": "Successful",
    "message": null,
    "channel": "card",
    "ip_address": "54.154.89.28, 162.158.38.82, 172.31.38.35",
    "log": null,
    "fees": 3,
    "authorization": {
      "authorization_code": "AUTH_6tmt288t0o",
      "bin": "408408",
      "last4": "4081",
      "exp_month": "12",
      "exp_year": "2000",
      "channel": "card",
      "card_type": "visa visa",
      "bank": "TEST BANK",
      "country_code": "NG",
      "brand": "visa",
      "reusable": true,
      "signature": "SIG_uSYN4fv1adlAuoij8QXh"
    },
    "customer": {
      "id": 14571,
      "first_name": null,
      "last_name": null,
      "email": "ibrahim@paytsack.co",
      "customer_code": "CUS_hns72vhhtos0f0k",
      "phone": null,
      "metadata": null,
      "risk_action": "default"
    },
    "plan": null
  }
}
{
  "status": false,
  "message": "Transaction reference is invalid"
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "0t4gwo2ft6q0n9h",
    "status": "send_birthday",
    "display_text": "Please send your birthday"
  }
}

Body Params

birthday
date

Birthday submitted by user

reference
string

reference for ongoing transaction

 
Suggest Edits

Check pending charge

When you get "pending" as a charge status or if there was an exception when calling any of the /charge endpoints, wait 10 seconds or more, then make a check to see if its status has changed. Don't call too early as you may get a lot more pending than you should.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/charge/reference
curl --request GET \
  --url https://api.paystack.co/charge/reference
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.paystack.co/charge/reference' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.paystack.co/charge/reference")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.paystack.co/charge/reference");

xhr.send(data);
import requests

url = "https://api.paystack.co/charge/reference"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Reference check successful",
  "data": {
    "reference": "5bwib5v6anhe9xa",
    "status": "pending"
  }
}
{
  "status": true,
  "message": "Reference check successful",
  "data": {
    "reference": "ojk8k0bimgftf0x",
    "status": "failed",
    "message": "Insufficient funds"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "0t4gwo2ft6q0n9h",
    "status": "send_otp",
    "display_text": "Please send OTP (none will be sent to your phone)"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "apg8mnjf5yg7zp8",
    "status": "send_pin"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "apg8mnjf5yg7zp8",
    "url":"https://standard.paystack.co/close",
    "status": "open_url"
  }
}
{
    "status": false,
    "message": "Transaction reference is invalid"
}
{
    "status": true,
    "message": "Charge attempted",
    "data": {
        "amount": 200,
        "currency": "NGN",
        "transaction_date": "2017-05-24T05:56:12.000Z",
        "status": "success",
        "reference": "zuvbpizfcf2fs7y",
        "domain": "test",
        "metadata": {
            "custom_fields": [
                {
                    "display_name": "Merchant name",
                    "variable_name": "merchant_name",
                    "value": "Van Damme"
                },
                {
                    "display_name": "Paid Via",
                    "variable_name": "paid_via",
                    "value": "API call"
                }
            ]
        },
        "gateway_response": "Successful",
        "message": null,
        "channel": "card",
        "ip_address": "54.154.89.28, 162.158.38.82, 172.31.38.35",
        "log": null,
        "fees": 3,
        "authorization": {
            "authorization_code": "AUTH_6tmt288t0o",
            "bin": "408408",
            "last4": "4081",
            "exp_month": "12",
            "exp_year": "2020",
            "channel": "card",
            "card_type": "visa visa",
            "bank": "TEST BANK",
            "country_code": "NG",
            "brand": "visa",
            "reusable": true,
            "signature": "SIG_uSYN4fv1adlAuoij8QXh"
        },
        "customer": {
            "id": 14571,
            "first_name": null,
            "last_name": null,
            "email": "ibrahim@paystack.co",
            "customer_code": "CUS_hns72vhhtos0f0k",
            "phone": null,
            "metadata": null,
            "risk_action": "default"
        },
        "plan": null
    }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "0t4gwo2ft6q0n9h",
    "status": "send_phone",
    "display_text": "Please send your phone number"
  }
}
{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "reference": "0t4gwo2ft6q0n9h",
    "status": "send_birthday",
    "display_text": "Please send your birthday"
  }
}

Path Params

reference
string
required

The reference to check

 
Suggest Edits

Create Refund

This creates a refund which is then processed by the Paystack team

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/refund
curl --request POST \
  --url https://api.paystack.co/refund
var request = require("request");

var options = { method: 'POST', url: 'https://api.paystack.co/refund' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.paystack.co/refund")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.paystack.co/refund");

xhr.send(data);
import requests

url = "https://api.paystack.co/refund"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "status": true,
    "message": "Refund created",
    "data": {
        "dispute": 14030,
        "transaction": {
            "id": 36357029,
            "domain": "live",
            "status": "reversed",
            "reference": "x7g15k5iye",
            "amount": 2500,
            "message": null,
            "gateway_response": "Approved",
            "paid_at": "2018-06-27T09:50:55.000Z",
            "created_at": "2018-06-27T09:50:00.000Z",
            "channel": "card",
            "currency": "NGN",
            "ip_address": "54.162.150.5, 172.68.65.71, 172.31.7.148",
            "metadata": {
                "custom_fields": [
                    {
                        "display_name": "Started From",
                        "variable_name": "started_from",
                        "value": "sample charge card backend"
                    },
                    {
                        "display_name": "Requested by",
                        "variable_name": "requested_by",
                        "value": "Mr. Akinlade"
                    },
                    {
                        "display_name": "Server",
                        "variable_name": "server",
                        "value": "infinite-peak-60063.herokuapp.com"
                    }
                ]
            },
            "log": null,
            "fees": 38,
            "fees_split": null,
            "authorization": 7430322,
            "customer": 22421,
            "plan": {},
            "subaccount": {},
            "paidAt": "2018-06-27T09:50:55.000Z",
            "createdAt": "2018-06-27T09:50:00.000Z"
        },
        "currency": "NGN",
        "amount": 2500,
        "channel": null,
        "customer_note": "I love people",
        "merchant_note": "People are awesome",
        "integration": 100073,
        "domain": "live",
        "status": "pending",
        "refunded_by": "refunds@paystack.co",
        "refunded_at": "2018-07-05T12:03:26.269Z",
        "expected_at": "2018-07-12T12:03:26.000Z",
        "fully_deducted": false,
        "id": 5679,
        "createdAt": "2018-07-05T12:03:26.269Z",
        "updatedAt": "2018-07-05T12:03:26.269Z"
    }
}

Body Params

transaction
string
required

Transaction reference or id

amount
int32

How much in kobo to be refunded to the customer. Amount is optional(defaults to original transaction amount) and cannot be more than the original transaction amount.

currency
string

Three-letter ISO currency

customer_note
string

Customer reason

merchant_note
string

Merchant reason

 
Suggest Edits

List Refunds

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/refund
curl --request GET \
  --url https://api.paystack.co/refund \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.paystack.co/refund',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.paystack.co/refund")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.paystack.co/refund");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.paystack.co/refund"

headers = {'authorization': 'Authorization'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Refunds retrieved",
  "data": [
    {
      "id": 1,
      "integration": 100982,
      "domain": "live",
      "transaction": 1641,
      "dispute": 20,
      "amount": 500000,
      "deducted_amount": 500000,
      "currency": "NGN",
      "channel": "migs",
      "fully_deducted": 1,
      "refunded_by": "customer@gmail.com",
      "refunded_at": "2018-01-12T10:54:47.000Z",
      "expected_at": "2017-10-01T21:10:59.000Z",
      "settlement": null,
      "customer_note": "xxx",
      "merchant_note": "xxx",
      "created_at": "2017-09-24T21:10:59.000Z",
      "updated_at": "2018-01-18T11:59:56.000Z",
      "status": "processed"
    },
    {
      "id": 2,
      "integration": 100982,
      "domain": "test",
      "transaction": 323896,
      "dispute": 45,
      "amount": 500000,
      "deducted_amount": null,
      "currency": "NGN",
      "channel": "migs",
      "fully_deducted": null,
      "refunded_by": "customer@gmail.com",
      "refunded_at": "2017-09-24T21:11:53.000Z",
      "expected_at": "2017-10-01T21:11:53.000Z",
      "settlement": null,
      "customer_note": "xxx",
      "merchant_note": "xxx",
      "created_at": "2017-09-24T21:11:53.000Z",
      "updated_at": "2017-09-24T21:11:53.000Z",
      "status": "pending"
    }
  ]
}

Query Params

reference
string

Identifier for transaction to be refunded

currency
string

Headers

Authorization
string
required

Bearer SECRET KEY

 
Suggest Edits

Fetch Refund

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/refund/TRANS_ID
curl --request GET \
  --url https://api.paystack.co/refund/TRANS_ID \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.paystack.co/refund/TRANS_ID',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.paystack.co/refund/TRANS_ID")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.paystack.co/refund/TRANS_ID");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.paystack.co/refund/TRANS_ID"

headers = {'authorization': 'Authorization'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Refund retrieved",
  "data": {
    "integration": 100982,
    "transaction": 1641,
    "dispute": null,
    "settlement": null,
    "domain": "live",
    "amount": 500000,
    "deducted_amount": 500000,
    "fully_deducted": true,
    "currency": "NGN",
    "channel": "migs",
    "status": "processed",
    "refunded_by": "eseyinwale@gmail.com",
    "refunded_at": "2018-01-12T10:54:47.000Z",
    "expected_at": "2017-10-01T21:10:59.000Z",
    "customer_note": "xxx",
    "merchant_note": "xxx",
    "id": 1,
    "createdAt": "2017-09-24T21:10:59.000Z",
    "updatedAt": "2018-01-18T11:59:56.000Z"
  }
}

Path Params

reference
string
required

Identifier for transaction to be refunded

Headers

Authorization
string
required

Bearer SECRET KEY

 
Suggest Edits

Resolve BVN

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/bank/resolve_bvn/bvn
curl "https://api.paystack.co/bank/resolve_bvn/21212917741" \
-H "Authorization: Bearer SECRET_KEY" 
-X GET
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "BVN resolved",
  "data": {
    "first_name": "WES",
    "last_name": "GIBSONS",
    "dob": "14-OCT-96",
    "mobile": "09022092102",
    "bvn": "21212917741"
  },
  "meta": {
    "calls_this_month": 1,
    "free_calls_left": 9
  }
}

Path Params

bvn
string
required

11 digits BVN

 
Suggest Edits

Resolve Account Number

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.paystack.co/bank/resolve
curl "https://api.paystack.co/bank/resolve?account_number=0022728151&bank_code=063" \
-H "Authorization: Bearer SECRET_KEY" \
-X GET
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Account number resolved",
  "data": {
    "account_number": "0022728151",
    "account_name": "WES GIBBONS"
  }
}

Query Params

account_number
string

Account Number

bank_code
string

Bank Code

Headers

Authorization
string
 
Suggest Edits

Resolve Card BIN

 
gethttps://api.paystack.co/decision/bin/bin
curl "https://api.paystack.co/decision/bin/539983" \
-X GET
A binary file was returned

You couldn't be authenticated

{
  "status": true,
  "message": "Bin resolved",
  "data": {
    "bin": "539983",
    "brand": "Mastercard",
    "sub_brand": "",
    "country_code": "NG",
    "country_name": "Nigeria",
    "card_type": "DEBIT",
    "bank": "Guaranty Trust Bank",
    "linked_bank_id": 9
  }
}

Path Params

bin
string
required

First 6 characters of card

 
Suggest Edits

Resolve Phone Number

Using the Truecaller API you can verify the authenticity of a customer. It returns the customer's name, phone number, email, social media handles and organization as available on their Truecaller profile.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.paystack.co/verifications
curl --request POST \
  --url https://api.paystack.co/verifications \
  --header 'authorization: : Bearer SECRET_KEY'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.paystack.co/verifications',
  headers: 
   { authorization: ': Bearer SECRET_KEY' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.paystack.co/verifications")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = ': Bearer SECRET_KEY'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.paystack.co/verifications");
xhr.setRequestHeader("authorization", ": Bearer SECRET_KEY");

xhr.send(data