Xend Finance Merchant API Documentation

# Requires: pip install cryptography
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import rsa

private_key = rsa.generate_private_key(
    public_exponent=65537,
    key_size=2048,
)

pem_private = private_key.private_bytes(
   encoding=serialization.Encoding.PEM,
   format=serialization.PrivateFormat.PKCS8,
   encryption_algorithm=serialization.NoEncryption()
)

public_key = private_key.public_key()
pem_public = public_key.public_bytes(
   encoding=serialization.Encoding.PEM,
   format=serialization.PublicFormat.SubjectPublicKeyInfo
)

with open('private_key.pem', 'wb') as f:
    f.write(pem_private)
with open('public_key.pem', 'wb') as f:
    f.write(pem_public)
print('Public and private key files generated!')

<?php
$config = [
    "private_key_bits" => 2048,
    "private_key_type" => OPENSSL_KEYTYPE_RSA,
];

// Create the private and public key
$res = openssl_pkey_new($config);

// Extract the private key
openssl_pkey_export($res, $private_key);
file_put_contents('private_key.pem', $private_key);

// Extract the public key
$public_key = openssl_pkey_get_details($res);
$public_key = $public_key["key"];
file_put_contents('public_key.pem', $public_key);

echo "Public and private key files generated!\n";
?>

// C# Example for RSA Key Generation
using System;
using System.IO;
using System.Security.Cryptography;

public class RsaKeyGenerator
{
    public static void Main()
    {
        using(var rsa = new RSACryptoServiceProvider(2048))
        {
            // Export the private key
            var privateKey = rsa.ExportRSAPrivateKeyPem();
            File.WriteAllText("private_key.pem", privateKey);

            // Export the public key
            var publicKey = rsa.ExportSubjectPublicKeyInfoPem();
            File.WriteAllText("public_key.pem", publicKey);

            Console.WriteLine("Public and private key files generated!");
        }
    }
}

# Python Example for RSA Signature
import time
import os
import base64
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.primitives import serialization

def generate_rsa_signature(private_key_pem, payload):
    # Create the exact same sorted string from the payload.
    string_to_sign = '&'.join([f"{k}={json.dumps(v) if isinstance(v, (dict, list)) else v}" for k, v in sorted(payload.items()) if v is not None and v != ''])

    private_key = serialization.load_pem_private_key(
        private_key_pem.encode(),
        password=None,
    )

    signature = private_key.sign(
        string_to_sign.encode('utf-8'),
        padding.PKCS1v15(),
        hashes.SHA256()
    )
    return base64.b64encode(signature).decode('utf-8')

# Example Usage:
with open('path/to/your_private_key.pem', 'r') as f:
    private_key_data = f.read()

request_payload = {
    'firstName': 'John',
    'lastName': 'Doe',
    'email': '[email protected]',
    'countryCode': 'NG',
    'phoneNumber': '08012345678',
    'kycStandard': False,
    'kycProofOfAddress': False,
    'kycBusinessVerification': False,
    'proxyKYCDetails': {
        'idCardType': 'PASSPORT',
        'idCardNumber': 'A12345678',
        'countryOfIssue': 'NG'
    }
}

# Generate nonce for header
nonce_str = os.urandom(16).hex()

rsa_signature = generate_rsa_signature(private_key_data, request_payload)
# Send this rsa_signature in the 'x-rsa-signature' header.

<?php

function generateRsaSignature($privateKey, $payload) {
    // Create the exact same sorted string from the payload.
    ksort($payload);
    $stringToSign = '';
    foreach ($payload as $key => $value) {
        if ($value !== null && $value !== '') {
            $stringToSign .= $key . '=' . $value . '&';
        }
    }
    $stringToSign = rtrim($stringToSign, '&');

    openssl_sign($stringToSign, $signature, $privateKey, OPENSSL_ALGO_SHA256);
    
    return base64_encode($signature);
}

// Example Usage:
$privateKey = file_get_contents('path/to/your_private_key.pem');
$requestPayload = [
    'requestTime' => round(microtime(true) * 1000),
    'amount' => 5000,
    'destinationAccount' => '0123456789'
];

// Generate nonce for header
$nonceStr = bin2hex(random_bytes(16));

$rsaSignature = generateRsaSignature($privateKey, $requestPayload);
// Send this $rsaSignature in the 'x-rsa-signature' header.
?>

// C# Example for RSA Signature
using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Text;

public class RsaGenerator
{
    public static string GenerateRsaSignature(string privateKeyPem, Dictionary<string, object> payload)
    {
        // Create the exact same sorted string from the payload.
        var stringToSign = string.Join("&", payload
            .Where(kvp => kvp.Value != null && kvp.Value.ToString() != "")
            .OrderBy(kvp => kvp.Key)
            .Select(kvp => $"{kvp.Key}={kvp.Value}"));

        using (var rsa = new RSACryptoServiceProvider())
        {
            // Import the private key.
            rsa.ImportFromPem(privateKeyPem);

            var dataBytes = Encoding.UTF8.GetBytes(stringToSign);
            var signatureBytes = rsa.SignData(dataBytes, HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1);

            return Convert.ToBase64String(signatureBytes);
        }
    }

    public static void Main()
    {
        var privateKey = File.ReadAllText(@"path\to\your_private_key.pem");
        var requestPayload = new Dictionary<string, object>
        {
            { "requestTime", new DateTimeOffset(DateTime.UtcNow).ToUnixTimeMilliseconds() },
            { "amount", 5000 },
            { "destinationAccount", "0123456789" }
        };

        // Generate nonce for header
        var nonceStr = Guid.NewGuid().ToString("N");

        var rsaSignature = GenerateRsaSignature(privateKey, requestPayload);
        // Send this rsaSignature in the 'x-rsa-signature' header.
    }
}

# Python Example for Webhook Verification
import base64
import json
from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding

def verify_webhook_signature(public_key_pem, payload):
    signature_b64 = payload.pop('signature', None)
    if signature_b64 is None:
        return False

    string_to_verify = '&'.join([f"{k}={json.dumps(v) if isinstance(v, (dict, list)) else v}" for k, v in sorted(payload.items()) if v is not None and v != ''])
    
    public_key = serialization.load_pem_public_key(public_key_pem.encode())
    signature = base64.b64decode(signature_b64)

    try:
        public_key.verify(
            signature,
            string_to_verify.encode(),
            padding.PKCS1v15(),
            hashes.SHA256()
        )
        return True
    except InvalidSignature:
        return False

# Example Usage in a Flask route
@app.route('/webhook', methods=['POST'])
def webhook_handler():
    xend_public_key = '-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----' # From your dashboard
    payload = request.get_json()
    is_valid = verify_webhook_signature(xend_public_key, payload)
    if is_valid:
        return 'OK', 200
    else:
        return 'Invalid signature', 400

<?php

function verifyWebhookSignature($publicKey, $payload) {
    if (!isset($payload['signature'])) {
        return false;
    }
    $signature = base64_decode($payload['signature']);
    unset($payload['signature']);

    ksort($payload);
    $stringToVerify = '';
    foreach ($payload as $key => $value) {
        if ($value !== null && $value !== '') {
            if (is_array($value) || is_object($value)) {
                $stringToVerify .= $key . '=' . json_encode($value) . '&';
            } else {
                $stringToVerify .= $key . '=' . $value . '&';
            }
        }
    }
    $stringToVerify = rtrim($stringToVerify, '&');

    $result = openssl_verify($stringToVerify, $signature, $publicKey, OPENSSL_ALGO_SHA256);

    return $result === 1;
}

// Example Usage
$xendPublicKey = '-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----'; // From your dashboard
$payload = json_decode(file_get_contents('php://input'), true);
$isValid = verifyWebhookSignature($xendPublicKey, $payload);

if ($isValid) {
    http_response_code(200);
    echo 'OK';
} else {
    http_response_code(400);
    echo 'Invalid signature';
}
?>

// C# Example for Webhook Verification
using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Text;
using Newtonsoft.Json.Linq;

public class WebhookVerifier
{
    public static bool VerifyWebhookSignature(string publicKeyPem, string jsonPayload)
    {
        var payload = JObject.Parse(jsonPayload);
        var signatureToken = payload.GetValue("signature", StringComparison.OrdinalIgnoreCase);
        if (signatureToken == null) return false;

        var signature = Convert.FromBase64String(signatureToken.ToString());
        payload.Remove("signature");

        var stringToVerify = string.Join("&", payload
            .Properties()
            .Where(p => p.Value.Type != JTokenType.Null && p.Value.ToString() != "")
            .OrderBy(p => p.Name)
            .Select(p => {
                var value = p.Value;
                if (value.Type == JTokenType.Object || value.Type == JTokenType.Array) {
                    return $"{p.Name}={JsonConvert.SerializeObject(value)}";
                }
                return $"{p.Name}={value}";
            }));

        using (var rsa = new RSACryptoServiceProvider())
        {
            rsa.ImportFromPem(publicKeyPem);
            var dataBytes = Encoding.UTF8.GetBytes(stringToVerify);
            return rsa.VerifyData(dataBytes, signature, HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1);
        }
    }
}