cnp-developer.addpay.cloud Open in urlscan Pro
54.237.181.152  Public Scan

Form analysis
0 forms found in the DOM

Text Content

Public


Documentation Settings

ENVIRONMENT
CNP UAT

LAYOUT
Double Column

LANGUAGE
cURL - cURL



CNP Web API
Introduction
Authentication
Requests
Responses
Pagination
Transactions
Customers
Bulk Transactions
Contracts
Mandates
Events
AVSR
Recon
Services
Settlements


CNP WEB API

The AddPay web API is organised around REST. Our API has predictable,
resource-oriented URLs, and uses HTTP response codes to indicate API errors. We
use built-in HTTP features, like HTTP authentication and HTTP verbs, which are
understood by off-the-shelf HTTP clients. We support cross-origin resource
sharing, allowing you to interact securely with our API from a client-side web
application.

To make the API as explorable as possible, accounts have test mode and live mode
API credentials. There is no "switch" for changing between modes, just use the
appropriate key to perform a live or test transaction on the live or test
endpoints. Requests made with test mode credentials never hit the banking
networks and incur no cost.

It's important that you understand the authentication, requests and responses
before getting started with the web API implementation as a missed header or
invalid parameter may render undesirable results in either request or response
data. Please carefully read through the Authentication, Requests, Response and
Pagination sections before heading to the rest of the API documentation.

If you believe a section of the API is incorrect or not working, please try it
out in the Postman collection to ensure your implementation of it isn't missing
any parameters that the functional Postman request contains. For any issues
encountered, please contact AddPay support.

Contact Support Email: support@addpay.co.za

AUTHORIZATIONBearer Token
Token

•••••••


AUTHENTICATION

API requests are authenticated via the Authorization HTTP header. The same way
standard HTTP Basic Auth is defined. The header information is constructed from
the client_id and client_secret which is generated from your business profile
when your account is created. Similarly to HTTP Basic Auth, the expected
authorization header is to be formatted as follows:

Authorization: Bearer $token

Where $token is a concatenation of the client_id and then the client_secret
separated by a colon (:) which once concatenated, are then base64 encoded. For
example, in pseudo code:

Authorization: Bearer base64encode(client_id:client_secret)

As real world output, your Authorization header would look something like this:

Authorization: Bearer Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=

During testing, you may want to use a tool to do your base64 encoding without
having to write any code, you can do so using: https://www.base64encode.org.

For more information on how the authorization header is formatted and why, see
references to the standardization of HTTP basic at the following URLs:

   
 * https://en.wikipedia.org/wiki/Basic_access_authentication
   
 * https://swagger.io/docs/specification/authentication/basic-authentication/
   

Note: We also allow using the technical word 'Token' instead of bearer in the
Authorization header. This is a deprecated method, but will remain as backward
compatible use. For example:

Authorization: Token Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=


REQUESTS

Every input and output of the API uses JSON as its format. While the API may
allow requests as form data and/or query parameters, it's strongly encouraged to
treat the API as a JSON API as it is documented to be used as such.

Whenever submitting a request to the web API endpoints, the relevant content
headers must be present, this is to ensure the API responds with the correct
formats and knows how to handle your input request format.

The Content-Type and Accept headers must be present in every request with a
header value of application/json. If these headers are not provided, you may
experience unexpected response formats in cases where you should receive JSON.

All headers with every request:

> Authorization: Bearer Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
> Accept: application/json
> Content-Type: application/json

   
 * AuthorizationAuthenticates your integration with the API.
   
 * AcceptTells the API you want JSON as a response.
   
 * Content-TypeTells the API you are submitting JSON in requests.
   


RESPONSES

Every JSON response received from the API will contain a meta block and a data
block. The meta attribute contains the HTTP exchange information about the
response that is structured as follows:

json


{
    "meta": {
        "request": "5040BA7037A0BAFDF0BAE6262DA32805",
        "status": "success",
        "message": "OK",
        "code": 200
    },
    "data": {
        // Relevant Data Here
    }
}

Meta Parameters

Parameter Description request Uniquely identifiable request index to help
identify potentially problematic HTTP requests. Sharing this identifier with
AddPay support will help them fasttrack any queries you may have for a
particular request. status "error" or "success" indicating the result of the
request. message A message describing potentially problematic inputs or when in
the success range, this will indicate the HTTP response code relevant status
message. code The code returned matches the actual HTTP status code. Anything
ins the 200 range is successul, 400 range is client request error related. See
all codes: https://en.wikipedia.org/wiki/List_of_HTTP_status_codes


PAGINATION

With every API response, a meta JSON block is returned. For larger sets of data,
typically lists, this meta block will contain a pagination attribute which
defines how many pages and records are available for viewing. See sample below.

View More
json


{
    "meta": {
        "request": "D8EC4ECB96E7D68645D39F74E903116B",
        "status": "success",
        "message": "OK",
        "code": 200,
        "pagination": {
            "records": 426,
            "page": 1,
            "pages": 43,
            "limit": 10
        }
    },
    "data": [
        {},
        {},        
        {},
    ]
}

In order to page through results, query parameters should be appended to the URL
(this applies to all paginatable APIs). See table for available fields.

Query Parameter Description page Integer defining the page. limit Integer
defining the number of items per page.

An example of using these query parameters:
HTTP GET /v2/transactions?page=2&limit=5

This will return a list of transaction at page 2 with 5 transactions per page.