Technical Documentation Page

Welcome

Welcome to this technical documentation page developed by Adedoyin Adebayo as a requirement for the freeCodeCamp Responsive Web Design certification course. The content of the page is taken from Paystack API - Developer Documentation

Introduction

The Paystack Developer Documentation is where you’ll learn how to build amazing payment experiences with the Paystack API.

API Basics

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

Before you do anything

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

Sample Requests

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

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

Requests and Response

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


            {
  "status": [boolean],  // Only true if the details provided could be processed and no error occured while processing 

  "message": [string], // Explains why status is false... Entirely informational. Please only log this but do not use for your checks 

  "data": [object]    // contains actionable result of processing if present
}

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

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

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

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


            "meta": {
  "total": 2,

  "skipped": 0,

  "perPage": 50,

  "page": 1,

  "pageCount": 1 

}

Authentication

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

Generally, we provide both public and secret keys. Public keys are meant to be used from your front-end when integrating using Paystack Inline and in our Mobile SDKs only.

VBy design, public keys cannot modify any part of your account besides initiating transactions to you. The secret keys however, are to be kept secret.

If for any reason you believe your secret key has been compromised or you wish to reset them, you can do so from the dashboard.

Secure your secret key

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

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

Sample Authorization Header

Authorization: Bearer sk_test_shdjkhdj827391nV4Lid

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

Secure your requests

Do not set

VERIFY_PEER

to

FALSE

. Ensure your server verifies the SSL connection to Paystack.

Errors

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

We discuss some common errors and their causes below

Authorization code does not exist or has been deactivated

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

Invalid Subaccount

All subaccounts codes on Paystack start with

ACCT_

and only exist on the integration that created them. And in the domain they were created. Common situations when you will get this message include:

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

Email does not match Authorization code. Please confirm

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

Invalid Split transaction values

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

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

Duplicate Transaction Reference

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

Invalid ****

All objects on Paystack are tied to a domain and integration. Getting an

Invalid X

message might mean the one specified does not exist in the space commanded by the key presented.

Error codes

Error 200, 201: Request was successful and intended action was carried out. Note that we will always send a 200 if a charge or verify request was made. Do check the data object to know how the charge went (i.e. successful or failed).
Error 400: A validation or client side error occurred and the request was not fulfilled.
Error 401: The request was not authorized. This can be triggered by passing an invalid secret key in the authorization header or the lack of one