Introduction

Welcome to the ClickPayAfrica API! You can use our API to access payment system API endpoints, which can get allows you to query and validate transactions sent to your system using our collection IPN.

The API is RESTful and uses json for all responses. The implemented authentication is oAuth2.

Authentication

ClickpayAfrica uses API keys to allow access to the API. You can register a new ClickpayAfrica API key at our portal.

ClickpayAfrica expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: cpaaggrekey

Instant Payment Notification

Instant Payment Notification (IPN) is a message service that automatically notifies merchants of events related to Mobile money transactions. Merchants can use it to automate their systems, including automatically fulfilling orders and providing customers with order status.

The following json content is sent as a push notification to the registered url.

IPN Request String:

{
  "url":"http://0.0.0.0:8080/receive/",
  "accountID":"1",
  "transactionid":"12",
  "amount":34,
  "msisdn":"255713XXXXXX",
  "verifysign":"eyJpdiI6Ik9hYkRUb1EzQVltUXhBbnVSZ08wWXc9PSIsInZhbHVlIjoiakhUcHVDQWJnbDNJMmVlUkt4N3NsM1wvdlljbTRqN084WFwvdnlUYUtHb0tnRFJkbDhoSGF6WStQNStOeTVpd0ZhN0x2em1WWlBnUTBUeGxNQSsydEZHQT09IiwibWFjIjoiMjhiMDkwYTY2Yzc0NThlZTI5ZmQ5YjUzYWJkNTQzNDFjYWI2ODg5MjJlOTcyZjM4MzMwZjViOTM0ZWUzNTFlNyJ9"
  }

Response from IPN Listener:

  Fail/Success

The verisign is a signature generated by encrypting the combination of (url+accountID+amount+msisdn) using AES-128-CBC. The pre-shared key will be generated and shared with the thirdparty.

How it works

Merchants create an IPN listener page on their website and then specify the URL of the listener page in their ClickpayAfrica portal. ClickpayAfrica then sends notifications of all transaction-related events to that URL.

When customers pay for goods or services, ClickpayAfrica sends a secure json containing payment information (IPN messages) to the URL. The IPN listener detects and processes IPN messages using the merchant backend processes. The IPN listener page contains a custom script or program that waits for the messages, validates them with ClickpayAfrica, and then passes them to various backend applications for processing.

Using IPN in your checkout flow

Although ClickpayAfrica usually processes IPN messages immediately, IPN is not synchronized with actions on your website. Internet connectivity is not always 100% reliable and IPN messages can be lost or delayed. The IPN service automatically resends messages until the listener acknowledges them. The service resends messages for up to 4 days.

Because IPN is not a real-time service, your checkout flow should not wait for the IPN message before it is allowed to complete. If the checkout flow is dependent on receiving an IPN message, processing can be delayed by system load or other reasons. You should configure your checkout flow to handle a possible delay.

Transaction Query

The transaction query allows authenticated thirdparty systems to perform query for specific transactions that belongs to their organization

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "http://localhost:8000/api/transactions/1"

    req, _ := http.NewRequest("GET", url, nil)

    req.Header.Add("cache-control", "no-cache")
    req.Header.Add("postman-token", "f6c79787-5e15-acf2-6c61-086d7ef9c1a9")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

<?php

$request = new HttpRequest();
$request->setUrl('http://localhost:8000/api/transactions/1');
$request->setMethod(HTTP_METH_GET);

$request->setHeaders(array(
  'postman-token' => 'c4d67fc7-1750-716b-1dc5-ff20056d9d03',
  'cache-control' => 'no-cache'
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

import http.client

conn = http.client.HTTPConnection("localhost:8000")

headers = {
    'cache-control': "no-cache",
    'postman-token': "f6837696-c5fa-cf63-3899-b2a85e44e950"
    }

conn.request("GET", "/api/transactions/1", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://localhost:8000/api/transactions/1",
  "method": "GET",
  "headers": {
    "cache-control": "no-cache",
    "postman-token": "00d794f9-e65a-eac1-e59c-d853519700f6"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Card Payment Processing

The following parameters are required for you to generate a payment url. Note that the development and production url will be supplied upon satisfaction of necessary KYC requirements

{ "account_id":"1",
"amount":"2",
"order_info":"Bookingid23",
"currency":"USD" }

After generating the payment url, you will be required to invoke a redirect to the url to complete payments

To receive payment information on completion, you will have to specify a callback url in the notification tabs within clickpayafrica system.

Clickpayafrica system will make a GET request to your system with the following parameters:
Successful Payment
type=cardpayment
status=success
message="Transaction successful"
order_info="order info submitted to api"
transaction_id="id generated on clickpay system"

Unsuccessful Payment
type=cardpayment
status=success
message="Transaction successful"
order_info="order info submitted to api"


Errors

The Clickpay API uses the following error codes:

Error Code	Meaning
400	Bad Request – Your request does not satisfy the defined rules
401	Unauthorized – Your API key is wrong
403	Forbidden – The payment requested is hidden for administrators only
404	Not Found – The specified payment could not be found
405	Method Not Allowed – You tried to access a payment with an invalid method
406	Not Acceptable – You requested a format that isn’t json
410	Gone – The payment requested has been removed from our servers
429	Too Many Requests – You’re requesting too many payment!
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarily offline for maintenance. Please try again later.