Payrant API Documentation

Accept payments, create virtual accounts, and send payouts with Payrant's powerful API.

Base URL: https://api-core.payrant.com/
Authentication: Bearer Token (API Key)

What is Payrant?

Payrant is a payment gateway that enables businesses in Africa to accept payments, create virtual accounts, and send payouts through a simple API.

Key Features

How It Works

  1. Sign up for a Payrant account and get your API keys
  2. Integrate the API into your application
  3. Accept payments through multiple channels
  4. Receive instant webhook notifications for transactions
  5. Withdraw funds or send payouts to customers

Getting Started

Follow these steps to start integrating Payrant into your application.

1. Create an Account

Sign up for a Payrant account at https://payrant.com/signup.

2. Access Your Dashboard

After signing up, you'll be redirected to your dashboard where you can access your API keys and settings.

3. Get Your API Keys

Navigate to the API section in your dashboard to retrieve your keys:

Important: Never expose your secret keys in client-side code or public repositories. Always keep them secure.

4. Test Your Integration

Use the test mode and test bank accounts to verify your integration works correctly before going live.

Authentication

All API requests must be authenticated using a Bearer token in the Authorization header.

POST /auth/login

Get API Token

Authenticate with your email and password to receive an API token.

Request Body

{
    "email": "your@email.com",
    "password": "your_password"
}

Response

{
    "status": "success",
    "message": "Login successful",
    "data": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
        "user": {
            "id": 123,
            "name": "Your Name",
            "email": "your@email.com",
            "business_name": "Your Business"
        }
    }
}

Using the API Token

Include the token in the Authorization header of all subsequent requests:

Authorization: Bearer YOUR_API_TOKEN_HERE
Note: For direct API key authentication, you can use:
Authorization: Bearer YOUR_SECRET_KEY_HERE

Virtual Accounts

Create dedicated virtual accounts for your customers to receive payments.

POST /palmpay/

Create Virtual Account

Creates a new Payrant virtual account linked to user's NIN.

Headers

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

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 identification document (e.g., "nin")
documentNumber string Yes Identification document number
virtualAccountName string Yes Name for the virtual account
customerName string Yes Customer's full name
email string Yes Customer's email address
accountReference string Yes Unique reference for the account

Response (Success)

{
    "status": "Enabled",
    "account_no": "6645962717",
    "virtualAccountName": "test_user(Payrant)",
    "virtualAccountNo": "6645962717",
    "identityType": "personal_nin",
    "licenseNumber": "8149999933",
    "customerName": "Test User",
    "accountReference": "86fe77b5fe0c"
}

Checkout

Accept one-time and recurring payments through Payrant Checkout.

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 Required
Content-Type application/json Yes
Authorization Bearer YOUR_API_KEY Yes

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
email 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)

{
    "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"
    }
}
GET /transaction/api.php?action=verify&reference={reference}

Verify Checkout Transaction

Check the status of a checkout transaction using its reference.

Headers

Key Value Required
Authorization Bearer YOUR_API_KEY Yes

URL Parameters

Parameter Type Required Description
reference string Yes Transaction reference from initialize response

Response (Success)

{
    "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"
    }
}

Payouts

Send money to bank accounts in Nigeria.

POST /payout/transfer

Bank Transfer / Payout

Initiate a bank transfer to any Nigerian bank account.

Headers

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

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)

{
    "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"
    }
}
POST /payout/validate_account/

Validate Account Name

Validate and retrieve the account name for a given bank code and account number.

Headers

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

Request Body

{
    "bank_code": "090405",
    "account_number": "8100000014"
}

Response (Success)

{
    "status": "success",
    "data": {
        "account_number": "8100000014",
        "account_name": "Zainab Umar",
        "bank_code": "090405",
        "verified": true
    }
}
GET /payout/banks_list/

Get Available Banks

Retrieve a list of all supported Nigerian banks and their codes.

Headers

Key Value Required
Authorization Bearer YOUR_API_KEY Yes

Response (Success)

{
    "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-android-upload-image-prod.s3.amazonaws.com/activity/172561365143017-624c18b2f5ef8e2c7c7ec481.png"
            }
        ],
        "total": 150
    }
}

Webhooks

Receive real-time notifications about transactions and transfers.

WEBHOOK Your Webhook URL

Transaction Webhook

Payrant sends transaction notifications to your webhook URL when deposits are made.

Headers

Key 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": "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 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

Webhook Events

Event Description
payment.successful A payment was successfully completed
transfer.completed A transfer was successfully processed
transfer.failed A transfer failed to process
virtual_account.created A virtual account was successfully created

Errors

Payrant uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP Status Codes

Code Name Description
200 OK The request was successful
201 Created The resource was successfully created
400 Bad Request The request was invalid or cannot be served
401 Unauthorized Authentication failed or not provided
403 Forbidden You don't have permission to access the resource
404 Not Found The requested resource doesn't exist
422 Unprocessable Entity The request was well-formed but failed validation
429 Too Many Requests You've exceeded the rate limit
500 Internal Server Error We had a problem with our server
503 Service Unavailable We're temporarily offline for maintenance

Error Responses

When an error occurs, the response body will contain details about what went wrong:

{
    "status": "error",
    "message": "Insufficient balance",
    "code": "insufficient_balance",
    "data": {
        "available_balance": 15.00,
        "required_amount": 32.00
    }
}

Common Error Codes

Error Code Description
invalid_api_key The API key provided is invalid
insufficient_balance Your account balance is insufficient for this transaction
invalid_bank_code The bank code provided is invalid
account_not_found The bank account number was not found
transfer_failed The bank transfer failed
invalid_amount The amount specified is invalid
invalid_nin The NIN provided is invalid

Best Practices

Security

Idempotency

To prevent duplicate operations, use the idempotency key header when making POST requests:

Idempotency-Key: unique_key_for_this_operation

This ensures that if a request is retried due to a network issue, the same operation isn't performed multiple times.

Testing

Handling Webhooks

Error Handling

Code Samples

Initialize Checkout (PHP)