Api Documentation

Generate Signature

Why signature?

To ensure the security of your transactions or requests, we have implemented security controls that we ensure that transactions can only be initiated by you and no one else. To achieve this, we use message signatures..

To generate the signature, you will need create a key pair of private key and public key. You will share the public key with us and use the private key to generate the signature.

Creating private & public keys

Use following command in command prompt to generate a keypair with a self-signed certificate.

In this command, we are using the openssl. You can use other tools e.g. keytool (ships with JDK - Java Developement Kit), keystore explorer e.t.c

GENERATE YOUR KEY PAIR

openssl genrsa -out privatekey.pem 2048 -nodes

Once you are successful with the above command a file (privatekey.pem) will be created on your present directory, proceed to export the public key from the keypair generated. The command below shows how to do it.

NOW EXPORT YOUR PUBLIC KEY

openssl rsa -in privatekey.pem -outform PEM -pubout -out publickey.pem

If the above command is successful, a new file (publickey.pem) will be created on your present directory. Copy the contents of this file and add it on our business portal. Make sure to copy only the contents of the key block and paste as is.

The Generated Key Files

The privatekey.pem file looks something like this:

The public.pem file looks something like this:

Generating the signature

The first step to generating the signature is to prepare the data to be signed. This is done by concatenating (joining) particular values within the API request payload. Different APIs will have different formulae for concatenation and this is detailed in each API's documentation.

To illustrate this, we use the Check Account Details API.

The request payload looks like this:


{
   "customer_code": "129392",
   "account": "2018709"
}

The instructions further say:

A SHA-256 signature to proof that this request is coming from the business. Build a String of concatenated values of the request fields with the following order: account, customer_code. The resulting text is then signed with Private Key and Base64 encoded.

We can see that the data to be signed is a concatenation of the values in the fields: account and customer_code and in that order and from our payload above, that would be: 2018709129392. This is the data we will sign.

Now onto signing. The mechanism of signing this data will depend on the language you are using. For instance, if you are using PHP, you would go about it as follows;

$plainText  = "2018709129392"; // See separate instruction on how to create this concatenation
$privateKey = openssl_pkey_get_private(("file://path/to/privatekey.pem"));
$token      = "QNg9X7cLJSpZVOpaJJ33wX0AbcRF";
openssl_sign($plainText, $signature, $privateKey, OPENSSL_ALGO_SHA256);

Your generated signature is now in a variable $signature in the PHP example.

You can now include it in your request as follows;

                                    
$plainText  = "2018709129392";
$privateKey = openssl_pkey_get_private(("file://path/to/privatekey.pem"));
$token      = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9";

openssl_sign($plainText, $signature, $privateKey, OPENSSL_ALGO_SHA256);


$curl        = curl_init();
$data_string = '{
   "customer_code": "129392",
   "account": "2018709"
}';

curl_setopt_array($curl, array(
    CURLOPT_URL => "https://v3-api.pokeapay.com/account/",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => $data_string,
    CURLOPT_HTTPHEADER => array(
        "Authorization: Bearer " . $token,
        "cache-control: no-cache",
        "Content-Type: application/json",
        "signature: " . base64_encode($signature)
    )
));
$result = curl_exec($curl);
$err    = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $result;
}

Generate Signature

Why signature?

Creating private & public keys

Generating the signature

V3.0.0