Connect your checkout to eligible Topteller wallet payments
Pay with Topteller is a payment integration that allows your platform to accept payments directly from users' Topteller wallets. Your customers can pay using their wallet balance with secure PIN/biometric authentication.
Check the payment status before completing an order
Customers follow the security steps shown in Topteller
Confirm current charges and limits before integrating
Method and timing depend on your merchant agreement
Request merchant access through Topteller and use the credentials provided after approval.
Your checkout collects the customer details required by the current integration flow.
Your server creates a payment request through the API and keeps its reference for status checks.
The customer reviews the request and completes the approval steps shown in Topteller.
Confirm a successful status or callback before fulfilling the order. Settlement follows the terms for your merchant account.
You need a Topteller account with verified KYC to become a merchant.
After your merchant account is approved, you'll receive:
Production: https://vtu.topteller.ng/api/v1/external-payment
Sandbox: https://sandbox.topteller.ng/api/v1/external-payment
/external-payment/initiate
Headers:
X-Platform-API-Key: your_api_key_here
Content-Type: application/json
Request Body:
| Parameter | Type | Required | Description |
|---|---|---|---|
| payer_phone | string | Yes | Customer's phone number (e.g., "08012345678") |
| amount | number | Yes | Payment amount in Naira |
| description | string | No | Payment description for customer |
| metadata | object | No | Additional payment metadata |
Example Request:
{
"payer_phone": "08012345678",
"amount": 5000,
"description": "Payment for Order #12345",
"metadata": {
"order_id": "12345",
"product": "Premium Subscription"
}
}
Example Response:
{
"success": true,
"message": "Payment request created successfully",
"data": {
"reference": "TPR-1234567890",
"payer_phone": "08012345678",
"amount": 5000,
"fee": 60,
"total_amount": 5060,
"status": "pending",
"expires_at": "2024-01-01T12:05:00Z"
}
}
/external-payment/status/{reference}
Headers:
X-Platform-API-Key: your_api_key_here
/external-payment/approve-offline
Request Body:
{
"reference": "TPR-1234567890",
"payer_phone": "08012345678",
"pin": "1234"
}
┌─────────────┐
│ Customer │
└──────┬──────┘
│ Selects "Pay with Topteller"
│ Enters phone number
▼
┌─────────────────┐
│ Your Platform │
│ Calls API │
└──────┬──────────┘
│ POST /initiate
▼
┌────────────────────┐
│ Topteller Server │
│ Creates Request │
└──────┬─────────────┘
│ Sends notification
▼
┌──────────────────┐
│ Customer's Phone │
│ Approves w/ PIN │
└──────┬───────────┘
│ Payment approved
▼
┌────────────────────────┐
│ Wallet → Wallet │
│ Auto Bank Transfer │
└────────────────────────┘
| Fee Type | Amount | Charged To |
|---|---|---|
| Base Fee | ₦60 | Customer (Payer) |
| Percentage Fee | 0% (configurable) | Customer (Payer) |
| Fee Cap | ₦3,000 maximum | Customer (Payer) |
| Settlement | Free | Merchant |
<?php
$apiKey = 'your_api_key_here';
$apiUrl = 'https://vtu.topteller.ng/api/v1/external-payment/initiate';
$data = [
'payer_phone' => '08012345678',
'amount' => 5000,
'description' => 'Payment for Order #12345'
];
$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'X-Platform-API-Key: ' . $apiKey,
'Content-Type: application/json'
]);
$response = curl_exec($ch);
$result = json_decode($response, true);
if ($result['success']) {
echo "Payment reference: " . $result['data']['reference'];
} else {
echo "Error: " . $result['message'];
}
curl_close($ch);
?>
const apiKey = 'your_api_key_here';
const apiUrl = 'https://vtu.topteller.ng/api/v1/external-payment/initiate';
const response = await fetch(apiUrl, {
method: 'POST',
headers: {
'X-Platform-API-Key': apiKey,
'Content-Type': 'application/json'
},
body: JSON.stringify({
payer_phone: '08012345678',
amount: 5000,
description: 'Payment for Order #12345'
})
});
const result = await response.json();
if (result.success) {
console.log('Payment reference:', result.data.reference);
} else {
console.error('Error:', result.message);
}
Configure webhook URL in your merchant dashboard to receive real-time payment notifications.
{
"event": "payment.completed",
"reference": "TPR-1234567890",
"amount": 5000,
"status": "completed",
"payer_phone": "08012345678",
"completed_at": "2024-01-01T12:03:00Z"
}
| Error Code | Description | Solution |
|---|---|---|
| 400 | Invalid request parameters | Check required fields and data types |
| 401 | Invalid API key | Verify your API credentials |
| 404 | User not found | Customer doesn't have Topteller account |
| 402 | Insufficient funds | Customer wallet balance too low |
| 408 | Request expired | Payment request expired (5 min timeout) |
Use our test store to experience the payment flow:
Need help with integration? Contact us: