Payrant API Documentation

Integrate Payrant's virtual account payment gateway with our developer-friendly API

Base URL: https://api-core.payrant.com/palmpay/
Authentication: All requests require Bearer token authentication

Virtual Account API

POST /palmpay/

Create a new virtual account linked to a user's NIN (National Identification Number).

Request Headers

Header	Value	Required
Content-Type	application/json	Yes
Authorization	Bearer YOUR_API_KEY	Yes

Request Body

{
    "documentType": "personal_nin",
    "documentNumber": "08145666933",
    "virtualAccountName": "test_user",
    "customerName": "Test",
    "email": "test@example.com",
    "accountReference": "ELYAKUB-686fe77b5fe0c"
}                            

Field	Type	Description
documentType	string	Must be "personal_nin"
documentNumber	string	User's NIN number
virtualAccountName	string	Account nickname/username
customerName	string	User's first name
email	string	User's email address
accountReference	string	Unique reference for the account

Response (Success)

{
    "status": "Enabled",
    "account_no": "6645962717",
    "virtualAccountName": "test_user(Payrant)",
    "virtualAccountNo": "6645962717",
    "identityType": "personal_nin",
    "licenseNumber": "08145666933",
    "customerName": "Test",
    "accountReference": "4345tett6r"
}                            

cURL Example

curl -X POST 'https://api-core.payrant.com/palmpay/' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 0346c6a374e3c347876dfb6c79fbe33689c5a254fd9dcc6022cf258bef268383' \
-d '{
    "documentType": "personal_nin",
    "documentNumber": "08145666933",
    "virtualAccountName": "test_user",
    "customerName": "Test",
    "email": "test@example.com",
    "accountReference": "ELYAKUB-686fe77b5fe0c"
}'                            

Webhook Notifications

POST Your Webhook URL

Payrant sends transaction notifications to your webhook endpoint when payments are received.

Request Headers

Header	Value
Content-Type	application/json
X-Payrant-Signature	HMAC-SHA256 signature

Webhook Payload

{
    "status": "success",
    "transaction": {
        "reference": "MI1944373825147994112",
        "amount": 300,
        "net_amount": 297,
        "fee": 3,
        "currency": "NGN",
        "timestamp": "2025-07-13 12:30:19",
        "user_id": 52,
        "account_details": {
            "account_number": "6699479580",
            "account_name": "Chibex@2025(Payrant)"
        },
        "payer_details": {
            "account_number": "3145980158",
            "account_name": "OGBADA CHRISTIANA ELIMA",
            "bank_name": "FIRST BANK PLC"
        },
        "metadata": {
            "session_id": "000016250713133014000309166995",
            "reference": "FBNMOBILE:CHIBEX 2025 PAYRANT /NIN VERIFICATION",
            "account_reference": "ELYAKUB-686fe77b5fe0c",
            "signature": "aDwV87zvcJyuSpJPZemeaa5zm30fI="
        }
    }
}                            

Signature Verification (PHP)

// Verify webhook signature
$webhook_secret = 'YOUR_WEBHOOK_SECRET';
$received_signature = $_SERVER['HTTP_X_PAYRANT_SIGNATURE'];
$payload = file_get_contents('php://input');

$expected_signature = hash_hmac('sha256', $payload, $webhook_secret);

if (!hash_equals($expected_signature, $received_signature)) {
    http_response_code(401);
    die('Invalid signature');
}

// Process valid webhook
$data = json_decode($payload, true);
$account_number = $data['transaction']['account_details']['account_number'];
$amount = $data['transaction']['net_amount'];
// Credit user's account                            

Response Requirements

Your endpoint should return HTTP 200 with this response structure:

{
    "status": "success",
    "message": "Webhook processed successfully"
}                            