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

Paystack Js

Single payment integration

❗️

DEPRECATION NOTICE: Paystack JS is no longer supported.

We are no longer officially supporting this library, and so we ask that you use one of our other methods of integration for your site/app. We recognize that this change can be frustrating, especially if you've already integrated the library, and we apologize for the inconvenience this causes. We're working on bringing a bigger and better version of this to you, one that would allow you to completely control the look & feel of your checkout process, while leveraging all the best features Paystack has to offer. We ask that you bear with us until that becomes a reality.

As always, feel free to contact us if you have any questions. Thank you for choosing Paystack!

Paystack.js makes it easy to collect card details on your page without having the information touch your server. We’ll do the encryption and transmission of the sensitive information. We’ll also handle the complex payment flow and let you know when to send PINs, OTPs or even redirect to a 3D Secure link. If you need help after reading this, join our slack channel or send an email to [email protected]

Useful links

Test Cards
Sample Code

Dependencies

  • jQuery

Step 0. Load Paystack.js

Load jQuery and Paystack JS into your page

<script src="https://code.jquery.com/jquery-1.12.4.min.js"></script>
    <script src="https://js.paystack.co/v1/paystack.js"></script>

Step 1. Create the transaction

Before sending card details to paystack.js, we expect you to initialize the transaction on your backend. Pass the customer's email, amount and any other relevant data to us, and we will return an access_code. Here’s how to initialize a transaction via our API: Initialize Transaction.

Step 2. Build your payment form

Use the data-paystack attribute to identify the different fields.

<form id="paystack-card-form">
  <input type="text" data-paystack="number">
  <input type="text" data-paystack="cvv">            
  <input type="text" data-paystack="expiryMonth">
  <input type="text"  data-paystack="expiryYear">
  <button type="submit" data-paystack="submit">Submit</button>
</form>

Step 3. Initialize paystack.js

// Initialize paystack object
var paystack;
Paystack.init({
  form: "paystack-card-form", // Form ID
  access_code: 'd5gtr5gnex'   // You should programmatically pass the access
                              // code via Ajax or a server variable. Note that
                              // the access code can only be used once. 
}).then(function(returnedObj){
  paystack = returnedObj;
}).catch(function(error){
  console.log("There was an error loading Paystack", error);
});

If the paystack.js is initialized correctly, the response is an object that you can use to charge cards.

Step 4. Charging the card

paystack.card.charge
This method charges a card entered into the form you have specified and returns a promise.

Optional Parameters: pin

You can either pass the pin at once or wait for Paystack to prompt for a PIN. Currently, all Visa and international MasterCard do not require a pin. Sometimes, we prompt for a PIN for Nigerian-issued MasterCard and will always require a PIN for Verve cards.

$("#paystack-card-form").submit(function(e){
  e.preventDefault();
  // You are to programmatically pass the pin provided by your custoemr
  // to this function
  // It gets all the card fields from the data-paystack input fields
  paystack.card.charge({
    pin: readPin() // Called a function that returns the optional pin value
  }).then(function(response){
    console.log(response);
  }, function(error){
    console.log(error);
  });
});

Charge Responses and Flow

There are 5 kinds of responses that you can receive from paystack.js. We will discuss each one below.

👍

Sample code available!

You will not need to worry about this too much, just download our sample javascript from https://github.com/PaystackHQ/PaystackJS-Sample-code then design the html screens for each type.

  1. invalid - this is returned when incorrect card details are sent (e.g wrong expiry date, cvv too short, invalid card number…), most of these errors can be determined before the cards are sent to the server/issuer.
  2. failed - this is returned when the transaction is sent to the issuer but returns a message other than successful.
  3. timeout - this is returned when the transaction has exceeded the payment session timeout you have set on your integration. By default, transactions do not expire. More details here: Payment Session Timeouts
  4. auth - this is returned when additional authentication is required. At the moment, there are 4 cases:
  • pin - PIN required
  • otp - One-Time Password required
  • 3DS - 3D Secure required
  • phone - Phone number required
  1. success - this is returned when the transaction has succeeded.

Validation Errors

Validation errors will be sent in the format:

{
  status: "invalid",
  message: "Validation error occured",
  errors: [{
    field: 'number',
    message: 'Invalid card number'
  }]
}

The field can either be number ,expiry or cvv .

Failed

Charge errors will be sent in the format:

{
  status: "failed",
  message: "Failure reason"
}

Timeouts

Timeout errors will be sent in the format:

{
  status: "timeout",
  message: "Transaction timed out"
}

Success

The success response of the promise will be invoked for either a successful charge or one that requires authentication.

A successful charge will send a response that looks like this:

{
  status: "success",
  message: "Transaction successful",
  data: {
    reference: "shdh8shsb"
  }
}

If the charge requires authentication, the response will look like this:

{
  status: "auth",
  message: "Authentication required",
  data: {
    auth: "OTP"
  }
}

Auth can be either OTP , 3DS , or phone . The three different auth requirements are discussed below.

Validating a charge (OTP)

If the charge response contains auth: OTP , then it requires a validation. You will need to collect the token from the customer and validate the charge.

<form id="otp-form">
  <input type="text" data-paystack="token">
  <button type="submit" data-paystack="submit">Submit</button>
</form>
$("#otp-form").submit(function(e){
  e.preventDefault();
  paystack.card.validateToken({
    token: readToken()
  }).then(function(response){
    console.log(response);
  }, function(error){
    console.log(error);
  });
});

3DS Verification

If the charge response contains auth: 3DS , then it requires an external Mastercard/Visa Securecode verification. paystack.js provides a function for you to initialize this popup and it listens for the response. You should display a message to your users, and provide a button they can click to verify 3DS.

<form id="3ds-form">
  <p>You will be required to verify your card with securecode</p>
  <button type="submit" data-paystack="submit">Submit</button>
</form>
$("#3ds-form").submit(function(e){
  e.preventDefault();
  paystack.card.verify3DS()
    .then(function(response){
      console.log(response);
    }, function(error){
      console.log(error);
    });
})

Enrolling a card

If the charge response contains auth: phone , this means the card hasn’t been enrolled for online use. paystack.js provides a function to enroll this card using the phone number, and automatically retries the transaction.

<form id="phone-form">
  <input type="text" data-paystack="phone">
  <button type="submit" data-paystack="submit">Submit</button>
</form>
$("#phone-form").submit(function(e){
  e.preventDefault();
  paystack.card.validatePhone({
    phone: readPhone()
  }).then(function(response){
    console.log(response);
  }, function(error){
    console.log(error);
  })
})

For a verve card, this will be the typical journey:

  • Accept card details
  • Accept pin
  • Charge card (and pass pin)
  • (if card is not enrolled, enroll)
  • Enter OTP
  • Successful

Updated about a year ago

Paystack Js


Single payment integration

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.