Payment Confirmation

After the account validation has successfully responded with the account details. You can proceed to confirm the payment for the service.

Prepare Transaction Details

Payment confirmation requires the PIN to be sent as part of the request. This PIN is shared in the account approval email. The PIN parameter is sent as a sha1 hash string converted to upper case. Below is pseudocode to describe how the hash is created.

PHP

<?php

function getShaHash($pin) {
    return strtoupper(sha1($pin));
}

?>

NodeJs

const crypto = require("crypto");

function getShaHash(pin) {
    return crypto.createHash("sha1").update(pin, "utf8").digest("hex").toUpperCase();
}

Java

import java.security.MessageDigest;

public class ShaHasher {

    public static String getShaHash(String pin) throws Exception {
        MessageDigest sha1 = MessageDigest.getInstance("SHA-1");

        byte[] pinBytes = pin.getBytes("UTF-8");

        sha1.update(pinBytes);

        byte[] hashBytes = sha1.digest();

        // Convert the hash bytes to a hex string
        StringBuilder hexString = new StringBuilder();
        for (byte b : hashBytes) {
            hexString.append(String.format("%02x", b));
        }

        // Return the uppercase hash string
        return hexString.toString().toUpperCase();
    }
}

C#

using System.Security.Cryptography;

public class ShaHasher
{
    public static string GetShaHash(string pin)
    {
        using (var sha1 = SHA1.Create())
        {
            byte[] pinBytes = Encoding.UTF8.GetBytes(pin);
            byte[] hashBytes = sha1.ComputeHash(pinBytes);
            return BitConverter.ToString(hashBytes).Replace("-", string.Empty).ToUpper();
        }
    }
}

Python

import hashlib

def get_sha_hash(pin):
    sha1 = hashlib.sha1()
    sha1.update(pin.encode("utf-8"))
    return sha1.hexdigest().upper()

Ruby

require 'digest/sha1'

def get_sha_hash(pin)
  Digest::SHA1.hexdigest(pin).upcase
end

Send Payment Request

Send a JSON POST request to the API endpoint below;

POST https://sandbox.ellypayapp.com/merchant/process-payment

Request

Request Body

Parameter	Type	Description	Required
validation_reference	string	The validation reference returned in the validation procedure here. This reference is generated by EllyPay	YES
pin	string	The sha1 hash value of the PIN as described in the above section	YES
secret_code	string	This one is a special parameter that applies to Airtel Money Withdraw transactions. The customer secret code should be Base64 encoded before sending the API request.	NO

Response

Response Body

Parameter	Type	Description
id	integer	The transaction ID
amount	float	The transaction amount
product_code	string	The code of the product for which the payment has been done
product_name	string	The name of the product
agent_reference	string	The reference from your system. This is the value that's sent for the prior validation request.
internal_reference	string	The unique reference generated by EllyPay for the transaction
agent_commission	float	The commission to be earned by the transacting account (where applicable)
status	string	The status of the transaction. Value can be one of; PENDING, FAILED, CANCELLED or SUCCESSFUL
message	string	Message describing the status of the transaction

Sample Request

{
	"validation_reference": "ELPREFYRWWVRKLG6W1WB",
	"pin": "893250BACD4B9C0594A81B19D1A76C2534668B66",
	"secret_code": "MzI5MzM2"
}

Sample Response (OK)

{
    "code": 202,
    "status": "accepted",
    "message": "Transaction still in progress. Please standby for status confirmation",
    "data": {
        "id": 227563,
        "amount": 500,
        "product_code": "AirtelWithdraw",
        "product_name": "Airtel Money Withdraw",
        "agent_reference": "CSTREFYRWWVRKLG6W1P3",
        "internal_reference": "ELPREFYRWWVRKLG6WE33",
        "agent_commission": 63,
        "status": "PENDING",
        "message": "Transaction still in progress. Please standby for status confirmation"
    }
}

Sample Response (Error)

{
    "code": 422,
    "status": "error",
    "message": "Unknown value 'ELI3HSP4MXKLG6W2IA' for parameter validation_reference",
    "data": {
        "id": 270553,
        "amount": 500,
        "product_code": "AirtelWithdraw",
        "product_name": "Airtel Money Withdraw",
        "agent_reference": "CSTREFYRWWVRKLG6W1P3",
        "internal_reference": "ELPREFYRWWKVZKMAYCO7T",
        "agent_commission": 0,
        "status": "FAILED",
        "message": "Unknown value 'ELI3HSP4MXKLG6W2IA' for parameter validation_reference",
        "details": {}
    }
}

As mentioned in the registration section, the API is asynchronous. The 202 response is an acknowledgement of your request. The EllyPay will send a payment notification with the updated status of the transaction. The notification data has the same structure as the acknowledgement response above with the addition of the details object that could hold extra data about the transaction. A sample is shared below

/*sample callback data for a UMEME transaction*/
{
  "id": 24546,
  "amount": 30000,
  "product_code": "YAKA",
  "product_name": "UMEME YAKA",
  "agent_reference": "CSTREFYRWWVRKLG6W1P3",
  "internal_reference": "ELPREFYRWWM8FKMBH1A5A",
  "agent_commission": 700,
  "status": "SUCCESSFUL",
  "description": "Purchase completed successfully for 04250513159",
  "details": {
    "token": "6931 3037 4217 9675 2152",
    "units": 39.4,
    "customer_name": "SSUNA, RICHARD",
    "account_number": "04250513159"
  }
}

Handling Payment Notifications/Callbacks

Whenever the status of the transaction changes (to failure or success), we notify your service via callbacks. Below are the hints to take note of as regards these payment notifications.

• All callbacks are sent to the callback URL you provide during registration.

• A secure callback URL is required and notifications will ONLY be sent to https URLs. If you don't receive these notifications, ensure to check this.

• The callback request is a POST with JSON encoded data.

• We expect that your service will acknowledge the callback request by responding with HTTP code 200 otherwise we will retry a few more times (if the response code is below the 500 range) and then stop.

• The callback request includes an extra header ellypay-signatureand this can optionally be used to verify that the callback request originated from our servers. If the signature is valid, you can proceed with your business logic.

• The next section describes the signature verification procedure.