API DOCUMENTATION
Developer Guide
Integrate Payrant's powerful payment APIs into your application with our comprehensive documentation, code examples, and interactive guides.
Getting Started
Base URL
https://api-core.payrant.com/
Authentication
All API requests require authentication using a Bearer token in the Authorization header:
Authorization: Bearer YOUR_API_KEY
Note: Replace
YOUR_API_KEY with your actual API key from the Payrant dashboard.
Authentication
Payrant uses API keys to authenticate requests. You can view and manage your API keys in the Payrant dashboard.
Getting Your API Key
- Sign up for a Payrant account
- Navigate to the API section in your dashboard
- Generate a new API key
- Copy and securely store your API key
Security Warning: Keep your API keys secure and never expose them in client-side code or public repositories.
Virtual Accounts API
POST
/palmpay/
Create Virtual Account
Creates a new Payrant virtual account linked to user's NIN for receiving payments.
Headers
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | Request content type |
| Authorization | Bearer YOUR_API_KEY | Your API authentication token |
Request Body
{
"documentType": "nin",
"documentNumber": "8149999933",
"virtualAccountName": "test_user",
"customerName": "Test User",
"email": "test@example.com",
"accountReference": "86fe77b5fe0c"
}
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| documentType | string | Yes | Type of document (e.g., "nin") |
| documentNumber | string | Yes | NIN number or document identifier |
| virtualAccountName | string | Yes | Name for the virtual account |
| customerName | string | Yes | Customer's full name |
| string | Yes | Customer's email address | |
| accountReference | string | Yes | Unique reference for the account |
Response (Success)
200 OK
{
"status": "Enabled",
"account_no": "6645962717",
"virtualAccountName": "test_user(Payrant)",
"virtualAccountNo": "6645962717",
"identityType": "personal_nin",
"licenseNumber": "8149999933",
"customerName": "Test",
"accountReference": "86fe77b5fe0c"
}
Checkout API
POST
/transaction/api.php?action=initialize
Initialize Checkout Transaction
Create a new checkout transaction and generate a virtual account for payment collection.
Headers
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | Request content type |
| Authorization | Bearer YOUR_API_KEY | Your API authentication token |
Request Body
{
"email": "customer@example.com",
"amount": 100,
"callback_url": "https://yoursite.com/callback",
"webhook_url": "https://yoursite.com/webhook",
"metadata": {
"order_id": "ORDER_123",
"customer_name": "John Doe"
}
}
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| string | Yes | Customer's email address | |
| amount | number | Yes | Transaction amount in NGN |
| callback_url | string | No | URL to redirect after payment |
| webhook_url | string | No | URL to receive payment notifications |
| metadata | object | No | Additional data (order_id, customer_name, etc.) |
Response (Success)
200 OK
{
"status": true,
"message": "Transaction initialized successfully",
"data": {
"reference": "TXN_1756911546_77_015d87df",
"checkout_url": "https://payrant.com/api-core/transaction/checkout.php?ref=TXN_1756911546_77_015d87df",
"amount": 100,
"email": "customer@example.com",
"account_number": "6680456766",
"bank_name": "PalmPay",
"status": "pending"
}
}
Response (Error)
400 Bad Request
{
"status": false,
"message": "Invalid API key"
}
GET
/transaction/api.php?action=verify&reference={reference}
Verify Checkout Transaction
Check the status of a checkout transaction using its reference.
Headers
| Key | Value | Description |
|---|---|---|
| Authorization | Bearer YOUR_API_KEY | Your API authentication token |
URL Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| reference | string | Yes | Transaction reference from initialize response |
Response (Success)
200 OK
{
"status": true,
"data": {
"reference": "TXN_1756911546_77_015d87df",
"amount": 100,
"email": "customer@example.com",
"account_number": "6680456766",
"bank_name": "PalmPay",
"status": "successful",
"paid_at": "2025-01-03 15:30:00"
}
}
Response (Not Found)
404 Not Found
{
"status": false,
"message": "Transaction not found"
}
Payout API
POST
/payout/transfer
Bank Transfer / Payout
Initiate a bank transfer to any Nigerian bank account. Supports all major banks and fintech companies.
Headers
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | Request content type |
| Authorization | Bearer YOUR_API_KEY | Your API authentication token |
Request Body
{
"bank_code": "090405",
"account_number": "8100000014",
"account_name": "Zainab Umar",
"amount": 20.00,
"description": "Payment for services",
"notify_url": "https://myapp.com/webhook/transfer"
}
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| bank_code | string | Yes | Bank code (e.g., "090405" for Moniepoint) |
| account_number | string | Yes | Recipient's account number |
| account_name | string | Yes | Recipient's account name |
| amount | number | Yes | Transfer amount (minimum 10 NGN) |
| description | string | No | Transfer description/remark |
| notify_url | string | No | Your webhook URL for transfer notifications |
Response (Success)
200 OK
{
"status": "success",
"message": "Transfer initiated successfully",
"data": {
"transfer_id": 13,
"reference": "TRANSFER_1756824073_77",
"order_no": "41250902144113531387",
"amount": 100,
"fee": 20,
"total_debit": 120,
"bank_name": "Moniepoint",
"account_name": "Zainab Umar",
"account_number": "8100000014",
"status": "processing",
"estimated_completion": "2-5 minutes",
"webhook_url": "configured"
}
}
Response (Error)
400 Bad Request
{
"status": "error",
"message": "Insufficient balance",
"data": {
"available_balance": 15.00,
"required_amount": 32.00
}
}
POST
/payout/validate_account/
Validate Account Name
Validate and retrieve the account name for a given bank code and account number before initiating a transfer.
Request Body
{
"bank_code": "090405",
"account_number": "8100000014"
}
Response (Success)
200 OK
{
"status": "success",
"data": {
"account_number": "8100000014",
"account_name": "Zainab Umar",
"bank_code": "090405",
"verified": true
}
}
Note: Always validate account details before initiating a transfer to ensure the recipient's account name is correct and the account exists.
GET
/payout/banks_list/
Get Available Banks
Retrieve a list of all supported Nigerian banks and their codes.
Response (Success)
200 OK
{
"status": "success",
"data": {
"banks": [
{
"bankCode": "090832",
"bankName": "5TT MFB",
"bankUrl": "https://transsnet-android-upload-image-prod.s3.amazonaws.com/activity/17518943562816-small%20bank.png",
"bgUrl": "https://transsnet-android-upload-image-prod.s3.amazonaws.com/activity/175189436366510-big%20bank.png"
},
{
"bankCode": "110072",
"bankName": "78 FINANCE COMPANY LIMITED",
"bankUrl": "https://transsnet-android-upload-image-prod.s3.amazonaws.com/activity/172564145415418-Sure%20Anchor%20MFB%20%282%29.png",
"bgUrl": "https://transsnet-app-images-prod.s3.eu-west-1.amazonaws.com/20220405/624c18b2f5ef8e2c7c7ec481.png"
}
],
"total": 150
}
}
Webhooks
Webhooks allow you to receive real-time notifications about payment events. Payrant will send HTTP POST requests to your specified webhook URLs when events occur.
WEBHOOK
Your Webhook URL
Payment Webhook
Receive notifications when payments are made to your virtual accounts or checkout transactions.
Headers
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | Content type of the payload |
| X-Payrant-Signature | HMAC-SHA256 signature | Webhook signature for verification |
| X-Payrant-Event | payment.successful | Event type (for checkout payments) |
Webhook Payload (Virtual Account Payment)
{
"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": "Chib@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 /",
"account_reference": "-686fe77b5fe0c",
"signature": "aDwV87zvcJyuSpJPZemeaa5zm30fI="
}
}
}
Webhook Payload (Checkout Payment)
{
"status": "success",
"transaction": {
"reference": "MI1965417746539921408",
"amount": "99.00",
"net_amount": 98,
"fee": "1.00",
"currency": "NGN",
"timestamp": "2025-09-09 14:11:21",
"user_id": 77,
"account_details": {
"account_number": "6657015962",
"account_name": "Checkout Transaction (Payrant)"
},
"payer_details": {
"account_number": "8100000614",
"account_name": "ZAINAB UMAR",
"bank_name": "OPAY"
},
"metadata": {
"session_id": "100004250909141120140720447926",
"reference": "Transfer from ZAINAB UMAR",
"account_reference": "TXN_1757427015_77_05ad73fc",
"signature": "XT3URllP3XAlmKyVgKZzyZZ60yMCzM6hY3n2erWLIztD9OwIgmDSX%2F%2FTCraXQL015pZIPzXDQtgeXqTxvMD8eIYvsAABBKoN1riwMLHE4yK%2FWw7DtmQZe8oxQCywiKNn%2BLm7N4329fy27CqntZe3TMLL%2BtLL%2FxU1SIiId7VqhzA%3D"
}
}
}
Payment Type Identification:
• Checkout Payments:
• Virtual Account Payments:
• Checkout Payments:
"account_name": "Checkout Transaction (Payrant)"• Virtual Account Payments:
"account_name": "user@email.com(Payrant)"
Webhook 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);
$accountName = $data['transaction']['account_details']['account_name'];
if ($accountName === 'Checkout Transaction (Payrant)') {
// This is a Checkout Payment
$reference = $data['transaction']['reference'];
$amount = $data['transaction']['amount'];
// Update order status, send confirmation email, etc.
} else {
// This is a Virtual Account Payment
// Handle VA payment logic
}
// Always return 200 to acknowledge receipt
http_response_code(200);
echo json_encode(['status' => 'received']);
WEBHOOK
Your Transfer Webhook URL
Transfer Status Webhook
Receive notifications when transfer status changes (processing, completed, failed).
Webhook Events
| Event | Description |
|---|---|
| transfer.processing | Transfer initiated and being processed |
| transfer.completed | Transfer successful, funds delivered |
| transfer.failed | Transfer failed, funds refunded |
Webhook Payload (Success)
{
"status": "success",
"event": "transfer.completed",
"data": {
"reference": "TRANSFER_1756818101_77",
"amount": 20.00,
"fee": 12.00,
"total_amount": 32.00,
"bank_name": "Moniepoint",
"account_number": "8100029614",
"account_name": "Muhammad Umar",
"status": "completed",
"palm_pay_ref": "41250902130141801212",
"created_at": "2025-01-02 14:01:41",
"updated_at": "2025-01-02 14:02:15"
}
}
Webhook Payload (Failed)
{
"status": "error",
"event": "transfer.failed",
"data": {
"reference": "TRANSFER_1756818101_77",
"amount": 20.00,
"fee": 12.00,
"total_amount": 32.00,
"bank_name": "Moniepoint",
"account_number": "8100029614",
"account_name": "Muhammad Umar",
"status": "failed",
"failure_reason": "Invalid account number",
"created_at": "2025-01-02 14:01:41",
"updated_at": "2025-01-02 14:02:15"
}
}
Code Examples
cURL Examples
Initialize Checkout Transaction
curl -X POST 'https://payrant.com/api-core/transaction/api.php?action=initialize' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d '{
"email": "customer@example.com",
"amount": 100,
"callback_url": "https://yoursite.com/callback",
"webhook_url": "https://yoursite.com/webhook",
"metadata": {
"order_id": "ORDER_123",
"customer_name": "John Doe"
}
}'
Verify Checkout Transaction
curl -X GET 'https://payrant.com/api-core/transaction/api.php?action=verify&reference=TXN_1756911546_77_015d87df' \
-H 'Authorization: Bearer YOUR_API_KEY'
Create Virtual Account
curl -X POST 'https://api-core.payrant.com/palmpay/' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d '{
"documentType": "nin",
"documentNumber": "12344556666778",
"virtualAccountName": "test_user",
"customerName": "Test",
"email": "test@example.com",
"accountReference": "86fe77b5fe0c"
}'
Initiate Bank Transfer
curl -X POST 'https://api-core.payrant.com/payout/transfer' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d '{
"bank_code": "090405",
"account_number": "8100029614",
"account_name": "Muhammad Umar",
"amount": 20.00,
"description": "Payment for services",
"notify_url": "https://myapp.com/webhook/transfer"
}'
PHP Examples
Initialize Checkout (PHP)
Error: {"status":"error","message":"Invalid API key"}
Webhook Handler (PHP)
Invalid signature