Modern Digital Wallet for Africa
Welcome to the ThirdMoney Merchant API documentation. This guide provides all necessary details for developers to integrate ThirdMoney wallet and gateway payments into their application, including credential handling, payment initiation, secure IPN handling, and real-time response management.
Obtain your Merchant ID, API Key, and Client Secret from User Dashboard → Merchant → CONFIG. These credentials are mandatory for authenticating all requests and must be securely stored.
Send a POST request to the endpoint below to create a new payment:
Spain
POST /api/v1/initiate-paymentTHIRD-Merchant-Key: Your Merchant IDTHIRD-API-Key: Your API KeyContent-Type: application/jsonNote: Legacy X-Merchant-Key and X-API-Key headers are still supported for backward compatibility but will be deprecated on 2026-07-01. Please migrate to THIRD-* branded headers.
{
"payment_amount": 200.00,
"currency_code": "USD",
"ref_trx": "TRXqgddgddg",
"description": "Order #1234",
"success_redirect": "https://merchant.com/success",
"failure_url": "https://merchant.com/failure",
"cancel_redirect": "https://merchant.com/cancel",
"ipn_url": "https://webhook.site/150456d9-a7fe-49d7-96b8-d08a8adf7ca6"
}Note: Use a real URL for ipn_url to receive webhook callbacks.
After a successful payment initiation, the API returns a payment_url. Redirect your customer to this URL to choose their preferred payment method (wallet, PayPal, Stripe, Mollie, etc.).
{
"payment_url": "https://thirdmoney.digital/payment/checkout?token=abc123",
"info": {
"ref_trx": "TRXqgddgddg",
"description": "Order #1234",
"ipn_url": "https://webhook.site/...",
"cancel_redirect": "https://merchant.com/cancel",
"success_redirect": "https://merchant.com/success",
"merchant_id": 6,
"merchant_name": "Ursula House",
"amount": 200,
"currency_code": "USD"
}
}ThirdMoney sends transaction updates to your defined ipn_url. Each request includes a HMAC signature generated using your client_secret to validate authenticity.
Content-Type: application/jsonTHIRD-Signature: HMAC-SHA256 of the entire payload using client_secretTHIRD-API-Version: v1THIRD-Webhook-ID: Unique webhook delivery identifier{
"data": {
"ref_trx": "TRXqgddgddg",
"description": "Order #1234",
"ipn_url": "https://webhook.site/150456d9-a7fe-49d7-96b8-d08a8adf7ca6",
"cancel_redirect": "https://merchant.com/cancel",
"success_redirect": "https://merchant.com/success",
"merchant_name": "Ursula House",
"amount": 200,
"currency_code": "USD"
},
"message": "Payment Completed",
"status": "completed",
"timestamp": 1747821208
}{
"data": {
"ref_trx": "TRXqgddgddg",
"description": "Order #1234",
"ipn_url": "https://webhook.site/150456d9-a7fe-49d7-96b8-d08a8adf7ca6",
"cancel_redirect": "https://merchant.com/cancel",
"success_redirect": "https://merchant.com/success",
"merchant_name": "Ursula House",
"amount": 200,
"currency_code": "USD"
},
"message": "Payment Failed",
"status": "failed",
"timestamp": 1747820975
}use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
Route::post('/ipn-listener', function (Request $request) {
$clientSecret = 'your_client_secret';
$payload = $request->all();
$signature = $request->header('THIRD-Signature');
$webhookId = $request->header('THIRD-Webhook-ID');
$expected = hash_hmac('sha256', json_encode($payload), $clientSecret);
if (! hash_equals($expected, $signature)) {
Log::warning('Invalid IPN signature.', [
'webhook_id' => $webhookId,
'expected' => $expected,
'received' => $signature,
]);
abort(403);
}
// Process valid transaction
Log::info('Valid webhook received', ['webhook_id' => $webhookId]);
return response()->json(['message' => 'Webhook received.']);
});Best Practice: Validate the signature and log payloads for auditing. Use background jobs to finalize order updates after IPN.
Quick examples for API integration:
use Illuminate\Support\Facades\Http;
$response = Http::withHeaders([
'THIRD-Merchant-Key' => env('MERCHANT_ID'),
'THIRD-API-Key' => env('API_KEY'),
])->post('https://yourdomain.com/api/v1/initiate-payment', [
'payment_amount' => 200,
'currency_code' => 'USD',
'ref_trx' => 'TRXqgddgddg',
]);
return $response->json();curl -X POST https://yourdomain.com/api/v1/initiate-payment \
-H "Content-Type: application/json" \
-H "THIRD-Merchant-Key: $MERCHANT_ID" \
-H "THIRD-API-Key: $API_KEY" \
-d '{"payment_amount":200,"currency_code":"USD","ref_trx":"TRXqgddgddg"}'