Ideospay Checkout Docs

CHECKOUT GATEWAY DOCUMENTATION

The checkout gateway allows merchant to receive payment in different currencies.

There are different payment methods available to make payment and different apis to call. Payment methods include card, bank transfer, USSD, pay with bank account

There are 3 major operations to perform so as to complete a payment. The api request body is passed as an encrypted data using the RSA encryption algorithm.

To authorise the api request, public key (which is provided from the merchant dashboard) is required to be passed. on the header on all the requests.

The 3 operations are

Create Order

Pay Order

Verify Payment Status

Create Order

Create order is the point where the customer details, the order details and every other information is been passed to create an order. which then returns the merchant information, the order details including the reference and the payment options available for the selected currency.

A unique reference is required to be passed which is used to identifier the order payment between the different systems involved.

Pay Order

This is the point where the customer select the payment method they prefer to use either Card, USSD, Bank transfer or any other method available.
For Card payment different authorisation and authentication is used based on the card type.

After a payment has been made. the success response respond return from this endpoint does not guarantee the payment is successful because in some cases the customer would have to go through verification and validation process. This is where the 3rd operation comes in

Verify Payment Status

This is the point where the status of the payment can be confirmed. this endpoint can be called couple of times to get the update on a payment

Point to Note

For easy integration, an endpoint is provided only for staging (it is not available on production) to encrypt data to be send for each of this operations

SAMPLE ENCRYPTION CODE

javascript

import rsa from 'node-forge'
const BigInteger = rsa.jsbn.BigInteger
let parser = new DOMParser()
function encryptForge(data, rsa_pub_key) {
  let pk = rsa_pub_key
  let rsaKeyValue = atob(pk)
  rsaKeyValue = rsaKeyValue.split('!')[1]
  const xmlDoc = parser.parseFromString(rsaKeyValue, 'text/xml')
  const modulus = xmlDoc.getElementsByTagName('Modulus')[0].innerHTML
  const exponent = xmlDoc.getElementsByTagName('Exponent')[0].innerHTML
  const pubKey = rsa.pki.setRsaPublicKey(
    parseBigInteger(modulus),
    parseBigInteger(exponent),
  ) // e
  let encryptText = pubKey.encrypt(rsa.util.encodeUtf8(data))
  return btoa(encryptText)
}
function parseBigInteger(b64) {
  return new BigInteger(
    rsa.util.createBuffer(rsa.util.decode64(b64)).toHex(),
    16,
  )
}
export default encryptForge

python

import base64
from Crypto.PublicKey import RSA
from Crypto.Cipher import PKCS1_v1_5
from Crypto.Util.Padding import pad
import xml.etree.ElementTree as ET
def encrypt(data, public_xml):
    try:
        if not data:
            raise Exception("Data sent for encryption is empty")
        print(data)
        # Decode the Base64 string
        decoded_bytes = base64.b64decode(public_xml)
        # Convert the decoded bytes to a string
        decoded_string = decoded_bytes.decode('utf-8')
        public_xml_key = decoded_string.split('!')[1]
        modulus = getXmlComponent(public_xml_key, "Modulus")
        exponent = getXmlComponent(public_xml_key, "Exponent")
        modulus_bytes = base64.b64decode(modulus)
        exponent_bytes = base64.b64decode(exponent)
        # Create an RSA public key from Modulus and Exponent
        key = RSA.construct((int.from_bytes(modulus_bytes, byteorder='big'), int.from_bytes(exponent_bytes, byteorder='big')))
        # Initialize the Cipher for encryption
        cipher = PKCS1_v1_5.new(key)
        # Encrypt data
        encrypted_bytes = cipher.encrypt(bytes(data, 'utf-8'))
        print(encrypted_bytes)
        #Convert to base 64 string
        encrypted_bytes_ = base64.b64encode(encrypted_bytes)
        print(encrypted_bytes_)
        return encrypted_bytes
    except Exception as e:
        raise e
def getXmlComponent(xmlstring, _field):
    try:
        # Parse the XML string
        root = ET.fromstring(xmlstring)
        # Find elements with the specified field name
        modulusElements = root.findall(_field)
        modulusValue = ""
        if modulusElements:
            # Extract the Modulus value from the first element
            modulusValue = modulusElements[0].text
            print("Modulus Value:", modulusValue)
        else:
            print("Modulus element not found.")
        return modulusValue
    except Exception as e:
        # Handle exceptions (e.g., parsing errors)
        print("Error:", str(e))
        return ""
# Example usage:
_data = "{\"order\":{}}"
public_xml = "NDA5NiE8UlNBS2V5VmFsdWU+PE1vZHVsdXM+eTJTSXdvQTY4cmNwZlNYcjJwbWhUYmp3NzRLOEgwTW5CN2NhbWNSVStlMVZmZ3o3d2xISysvYi9kdE9NLzVtYVBZV1l0aW1YcURoNlppTHZyUytqaklhVkhjS2trS3dscTNrK1BTSDR1ckpqeElOQSt4RHBQSW1aWFVLMjJobmp2c2s1YTM2Vkx2Q1NPd2IwTXJXaHJwaXNKem9sS3VEaFR1MjhnYWNsT1FaR2JoNStNazdyV0ZnVjVLZThqcUFZK1FIMk16RmZYNys3ZldKbXhGQTlReEI5SThTODhBMC9SWm5SNUlJQWtrRHh3aGtsSlB0NEtQeG5GT0RmTHQyR3Z0YXp3NmlTNmNUUlBHVkF5MmNocDRrZmZSVFcrd0FhaTlycTV5V2h0cHFaOVlCZ1N1MUFLd2twd01NL3o0cVJHWDJOdWZoOEtnMWV6cUs0WkVnTGhOYnN1aXZ5NmdZNEZxMjdSZWpndDN1S0hmdmExaUtYLysxVVI5cmlIMjJYUVZEMzFIamFieUJoZ2lTcVBIMzgwUVBNMnlpdnpKZDdyWDZqMEpzZk1NRFlGejJzMCtIUHJoQmd6cFBua3l2S0RGMUFZcjRTc2RQaitCNUxrYlZESUg4TC9zZE1DcEpyblJqMWlHRXgvWUl4U1ExdEJFZWFnbWFxVVF2VVJYV2hOeHNIS0Nxa3Buelh3bVdpT3FUR1RNRWdpc2UvbkI3SHVuVlRITEZ0d0UyVE1LYXZxbEFkUHNxMytlSFNqUzhQVmZNK1IxL1VoMUVTR09aOFZZdThTMjdFYWl6dDY4SmhVbDQ0NnVjT0R4VEJTckFYS0ptdGhjZk9MZzNYekU5TVlkaEZiWisxRzlHbi91YkVFd2ZiZVZsOVViVXZ6WDEwZmxTZXRlUnZ0ZDg9PC9Nb2R1bHVzPjxFeHBvbmVudD5BUUFCPC9FeHBvbmVudD48L1JTQUtleVZhbHVlPg=="
encrypted_data = encrypt(_data, public_xml)

java

import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.w3c.dom.NodeList;
import org.xml.sax.SAXException;
import javax.crypto.Cipher;
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.ParserConfigurationException;
import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.UnsupportedEncodingException;
import java.nio.charset.StandardCharsets;
import java.security.*;
import java.security.spec.InvalidKeySpecException;
import java.security.spec.RSAPublicKeySpec;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;
//import javax.xml.bind.DatatypeConverter;
public class EncryptionHelper {
    private PrivateKey privateKey;
    private PublicKey publicKey;
    public  static String getXmlComponent(String xmlstring, String _field) throws IOException, SAXException, ParserConfigurationException {
        // Create a DocumentBuilder
        DocumentBuilderFactory dbFactory = DocumentBuilderFactory.newInstance();
        DocumentBuilder dBuilder = dbFactory.newDocumentBuilder();
        // Parse the XML string
        Document doc = dBuilder.parse(new java.io.ByteArrayInputStream(xmlstring.getBytes("UTF-8")));
        // Normalize the document
        doc.getDocumentElement().normalize();
        NodeList modulusNodeList = doc.getElementsByTagName(_field);
        String modulusValue = "";
        if (modulusNodeList.getLength() > 0) {
            Element modulusElement = (Element) modulusNodeList.item(0);
            // Extract the Modulus value
            modulusValue = modulusElement.getTextContent();
            System.out.println("Modulus Value: " + modulusValue);
        } else {
            System.out.println("Modulus element not found.");
        }
        return modulusValue;
    }
    public static byte[] encrypt(String _data, String publicXml) throws Exception {
        try {
            var data = _data.getBytes();
            if (data == null || data.length < 1) {
                throw new Exception("Data sent for encryption is empty");
            }
            // Extract the Modulus and Exponent from the XML
            // Decode the Base64 string
            byte[] decodedBytes = Base64.getDecoder().decode(publicXml);
            // Convert the decoded bytes to a string
            String decodedString = new String(decodedBytes);
            var publicxmllkey = decodedString.split("!")[1];
            System.out.println(publicxmllkey);
            var modulus = getXmlComponent(publicxmllkey, "Modulus");
            var exponent = getXmlComponent(publicxmllkey, "Exponent");
            String modulusBase64 = modulus;
            String exponentBase64 = exponent/* extract Exponent from publicXml */;
            // Convert the Base64-encoded Modulus and Exponent to byte arrays
            byte[] modulusBytes = Base64.getDecoder().decode(modulusBase64);
            byte[] exponentBytes =Base64.getDecoder().decode(exponentBase64);
            // Create RSAPublicKeySpec from Modulus and Exponent
            RSAPublicKeySpec keySpec = new RSAPublicKeySpec(
                    new java.math.BigInteger(1, modulusBytes),
                    new java.math.BigInteger(1, exponentBytes)
            );
            // Generate the PublicKey from the RSAPublicKeySpec
            KeyFactory keyFactory = KeyFactory.getInstance("RSA");
            PublicKey publicKey = keyFactory.generatePublic(keySpec);
            // Initialize the Cipher for encryption
            Cipher cipher = Cipher.getInstance("RSA/ECB/PKCS1Padding");
            cipher.init(Cipher.ENCRYPT_MODE, publicKey);
            // Encrypt the data
            byte[] encryptedBytes = cipher.doFinal(data);
            return encryptedBytes;
        } catch (Exception e) {
            throw e;
        }
    }
    public EncryptionHelper() throws Exception {
        var rowdata = "Hello World";
        var publicxml = "NDA5NiE8UlNBS2V5VmFsdWU+PE1vZHVsdXM+eTJTSXdvQTY4cmNwZlNYcjJwbWhUYmp3NzRLOEgwTW5CN2NhbWNSVStlMVZmZ3o3d2xISysvYi9kdE9NLzVtYVBZV1l0aW1YcURoNlppTHZyUytqaklhVkhjS2trS3dscTNrK1BTSDR1ckpqeElOQSt4RHBQSW1aWFVLMjJobmp2c2s1YTM2Vkx2Q1NPd2IwTXJXaHJwaXNKem9sS3VEaFR1MjhnYWNsT1FaR2JoNStNazdyV0ZnVjVLZThqcUFZK1FIMk16RmZYNys3ZldKbXhGQTlReEI5SThTODhBMC9SWm5SNUlJQWtrRHh3aGtsSlB0NEtQeG5GT0RmTHQyR3Z0YXp3NmlTNmNUUlBHVkF5MmNocDRrZmZSVFcrd0FhaTlycTV5V2h0cHFaOVlCZ1N1MUFLd2twd01NL3o0cVJHWDJOdWZoOEtnMWV6cUs0WkVnTGhOYnN1aXZ5NmdZNEZxMjdSZWpndDN1S0hmdmExaUtYLysxVVI5cmlIMjJYUVZEMzFIamFieUJoZ2lTcVBIMzgwUVBNMnlpdnpKZDdyWDZqMEpzZk1NRFlGejJzMCtIUHJoQmd6cFBua3l2S0RGMUFZcjRTc2RQaitCNUxrYlZESUg4TC9zZE1DcEpyblJqMWlHRXgvWUl4U1ExdEJFZWFnbWFxVVF2VVJYV2hOeHNIS0Nxa3Buelh3bVdpT3FUR1RNRWdpc2UvbkI3SHVuVlRITEZ0d0UyVE1LYXZxbEFkUHNxMytlSFNqUzhQVmZNK1IxL1VoMUVTR09aOFZZdThTMjdFYWl6dDY4SmhVbDQ0NnVjT0R4VEJTckFYS0ptdGhjZk9MZzNYekU5TVlkaEZiWisxRzlHbi91YkVFd2ZiZVZsOVViVXZ6WDEwZmxTZXRlUnZ0ZDg9PC9Nb2R1bHVzPjxFeHBvbmVudD5BUUFCPC9FeHBvbmVudD48L1JTQUtleVZhbHVlPg==";
        var result = encrypt(rowdata, publicxml);
        // Encode the byte array to a Base64 string
        String base64String = Base64.getEncoder().encodeToString(result);
        System.out.println("Converted successfully");
        System.out.println(base64String);
    }
    public static void main(String[] args) throws Exception {
        EncryptionHelper keyPairGenerator = new EncryptionHelper();
    }
}

php

require 'vendor/autoload.php';
use phpseclib3\Crypt\RSA;
use phpseclib3\Math\BigInteger;
function getXmlComponent($xmlstring, $field)
{
    try {
        // Load XML
        $xml = new SimpleXMLElement($xmlstring);
        // Register namespaces if any
        $namespaces = $xml->getNamespaces(true);
        foreach ($namespaces as $prefix => $namespace) {
            if ($prefix === '') {
                $prefix = 'default';
            }
            $xml->registerXPathNamespace($prefix, $namespace);
        }
        // Construct the correct XPath query
        $result = null;
        if (!empty($namespaces)) {
            foreach ($namespaces as $prefix => $namespace) {
                $prefix = $prefix ?: 'default';
                $result = $xml->xpath("//$prefix:$field");
                if ($result) {
                    break;
                }
            }
        } else {
            $result = $xml->xpath("//$field");
        }
        // Check if the element was found
        if ($result && count($result) > 0) {
            return (string)$result[0];
        } else {
            echo "Element $field not found.\n";
            return "";
        }
    } catch (Exception $e) {
        echo "Error: " . $e->getMessage() . "\n";
        return "";
    }
}
function encryptData($data, $public_xml)
{
    try {
        if (!$data) {
            throw new Exception("Data sent for encryption is empty");
        }
        // Decode the Base64 string
        $decoded_bytes = base64_decode($public_xml);
        $decoded_string = mb_convert_encoding($decoded_bytes, 'UTF-8');
        $public_xml_key = explode('!', $decoded_string)[1];
        echo $public_xml_key;
        $modulus = getXmlComponent($public_xml_key, "Modulus");
        $exponent = getXmlComponent($public_xml_key, "Exponent");
        $modulus_bytes = base64_decode($modulus);
        $exponent_bytes = base64_decode($exponent);
        // Create an RSA public key from Modulus and Exponent
        $rsa = RSA::loadFormat('raw', [
            'n' => new BigInteger($modulus_bytes, 256),
            'e' => new BigInteger($exponent_bytes, 256)
        ]);
        echo "Trying to encrypt data" . "\n";
        // Encrypt data
        $rsa = $rsa->withPadding(RSA::ENCRYPTION_PKCS1);
        $encrypted = $rsa->encrypt($data);
        // Convert to base 64 string
        $encrypted_base64 = base64_encode($encrypted);
        echo "base 64 value" . "\n";
        echo $encrypted_base64 . "\n";
        return $encrypted_base64;
    } catch (Exception $e) {
        echo "Error: " . $e->getMessage() . "\n";
        return "No encrypted ata";
    }
}
// Example usage
$data = "{\r\n    \"customer\": {\r\n        \"firstname\": \"firstname\",\r\n        \"lastname\": \"lastname\",\r\n        \"mobile\": \"+2348158200000\",\r\n        \"country\": \"NG\",\r\n        \"email\": \"email@pay.dev\"\r\n    },\r\n    \"order\": {\r\n        \"amount\": 3,\r\n       
\"reference\": \"223232323121212122121QWW2QWWW\",\r\n        \"description\": \"Pay\",\r\n        \"currency\": \"USD\"\r\n    },\r\n    \"payment\": {\r\n        \"RedirectUrl\": \"https://www.hi.com\"\r\n    }\r\n}";
$public_xml = "NDA5NiE8UlNBS2V5VmFsdWU+PE1vZHVsdXM+eStWT0Q0Ymp2bnZ5Wmh6eW9ySDRNMDlpRGlGeXFwTlRGYVV6WU9ER3lFaXNqRFBkdEVCdjJvbzNyTm1vMkt6TmJTSGl1MzdmeDhKdWN3bHRIUHUrank0bUFSNGp5N0ZiOURkT2x3blpVaDVUMnlXSUU2OExhL3hGTFJQUTN3TmpkNER0RStpbkM0YStHQ1hQR0FTVm5XS3MrM1hQcEpiS1FFVHZxYUluVUZ0RVZQaGtabGtWNXpNRWU0eVVDNzZDSGxxR0hWMWJobXNEdS9GKzVEVHMvY1REd2NOSStXN1RHUjZuRmhnUFkrQU9vV3R2QzRobVBYc1VhR3NjVjNkbkV6Q0lDUTMxZHQwZ0NYdVdqN21LZ1dyT3N2a2IvaUp6RkVpRzdRL1hqaENiTzRRWENZcEF2eEpWSGkrQWV2WlYxTDQrRW9vZWVLU3N0REoxYlF2WW00L1NnQmszN0FZQXNEUElRZFUzaGsrbFdSWjhXeWRhZ2RlV3FHbVUybEt2Y1Z6MDMzVk1RMlZzS2x0NmFldG01Rmtsc3FpeFJPWUpxZHBMUU1BZldQVGxVLytQUUxMWHFEbUxOZ3ZFWm5PUEFjeE1EbEg2dEh0RVhvLysxQ1RmNzdEaDhPTGpmcGgvWTBCU3pjRndDODE0NUlld0hBSW9ZTTFLeUNvdElFazVyQXVxZks2aHpEWS9CUnN6VkNLYTVNNTVXRDJzclJ6dFVtNHNlaUNoVzlZVlV6ZUg1MFV3RmN3b1pLTlN5UEhYMXJocE54eTZkV2JXWVNuMjQwZTVwWEFQWFgyNUEwRElWK1RUMjcxNnRPQ2pxanpaMENZbXpkZ3ozYmVlQi8yQzRKV2lsZlNxejYyY3llWDVFem5PdE9rNkRNWEZrY2xPMzhMNVU4RTIwZlU9PC9Nb2R1bHVzPjxFeHBvbmVudD5BUUFCPC9FeHBvbmVudD48L1JTQUtleVZhbHVlPg==";
$encrypted_data = encryptData($data, $public_xml);
echo "Encrypted data" . "\n";
echo $encrypted_data . "\n";