API Integration
Integrate Elbatal-Pay payments into your website
Quick Start
Elbatal-Pay provides a full REST API with HMAC authentication for secure payment processing. Follow the steps below to integrate Elbatal-Pay into your project.
Create a Merchant Account
Register an account and create an Elbatal-Pay payment gateway from the dashboard to obtain your API Key and API Secret.
Sign Your Requests
Every API request must include three headers: X-API-Key, X-API-Timestamp, and X-API-Signature. The signature is an HMAC-SHA256 hash of your request data signed with your API Secret.
Create & Manage Charges
Use the api_create_charge endpoint to create payments, api_capture_charge to complete, api_void_charge to cancel, and api_refund_charge to refund.
Authentication
All REST API endpoints require HMAC-SHA256 request signing. You must provide three HTTP headers:
| Header | Description |
|---|---|
X-API-Key | Your merchant API key (from payment gateway settings) |
X-API-Timestamp | Current Unix timestamp (server must be within 5 minutes) |
X-API-Signature | HMAC-SHA256 hex digest of the signature payload |
Signature payload = api_key + timestamp + HTTP method + request URI + request body
signature = hash_hmac('sha256', api_key . timestamp . method . uri . body, api_secret)
Connection Information
PHP Integration
Use the following PHP code to create a signed API request:
<?php
$apiKey = 'YOUR_API_KEY';
$apiSecret = 'YOUR_API_SECRET';
$apiUrl = 'https://pay.elbatal-app.com';
function hmacSign($apiKey, $apiSecret, $method, $uri, $body) {
$timestamp = time();
$dataToSign = $apiKey . $timestamp . $method . $uri . $body;
$signature = hash_hmac('sha256', $dataToSign, $apiSecret);
return [$timestamp, $signature];
}
$payload = json_encode([
'amount' => 10.00,
'currency' => 'USD',
'item_name' => 'Product Name',
'buyer_name' => 'John Doe',
'buyer_email' => '[email protected]',
]);
$uri = '/api.php?action=api_create_charge';
list($ts, $sig) = hmacSign($apiKey, $apiSecret, 'POST', $uri, $payload);
$ch = curl_init($apiUrl . $uri);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'X-API-Key: ' . $apiKey,
'X-API-Timestamp: ' . $ts,
'X-API-Signature: ' . $sig,
],
CURLOPT_TIMEOUT => 30,
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
if ($data['success']) {
echo 'Charge created: ' . $data['data']['transaction_ref'];
} else {
echo 'Error: ' . ($data['error'] ?? 'Unknown error');
}
JavaScript Integration
Use the following JavaScript code from a Node.js environment (keep secrets server-side):
const crypto = require('crypto');
const apiKey = 'YOUR_API_KEY';
const apiSecret = 'YOUR_API_SECRET';
const apiUrl = 'https://pay.elbatal-app.com';
function hmacSign(apiKey, apiSecret, method, uri, body) {
const timestamp = Math.floor(Date.now() / 1000);
const dataToSign = apiKey + timestamp + method + uri + body;
const signature = crypto
.createHmac('sha256', apiSecret)
.update(dataToSign)
.digest('hex');
return { timestamp, signature };
}
const body = JSON.stringify({
amount: 10.00,
currency: 'USD',
item_name: 'Product Name',
buyer_name: 'John Doe',
buyer_email: '[email protected]',
});
const uri = '/api.php?action=api_create_charge';
const { timestamp, signature } = hmacSign(apiKey, apiSecret, 'POST', uri, body);
fetch(apiUrl + uri, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': apiKey,
'X-API-Timestamp': String(timestamp),
'X-API-Signature': signature,
},
body: body,
})
.then(r => r.json())
.then(res => {
if (res.success) {
console.log('Charge created:', res.data.transaction_ref);
} else {
console.error('Error:', res.error);
}
});
⚠ Never expose your API Secret in client-side browser code. Sign requests server-side only.
cURL Example
Test the API directly from your terminal:
API_KEY="YOUR_API_KEY"
API_SECRET="YOUR_API_SECRET"
API_URL="https://pay.elbatal-app.com"
# Generate HMAC signature
BODY='{"amount":10.00,"currency":"USD","item_name":"Test Product"}'
TIMESTAMP=$(date +%s)
DATA_TO_SIGN="${API_KEY}${TIMESTAMP}POST/api.php?action=api_create_charge${BODY}"
SIGNATURE=$(echo -n "$DATA_TO_SIGN" | openssl dgst -sha256 -hmac "$API_SECRET" | awk '{print $2}')
curl -s -X POST "${API_URL}/api.php?action=api_create_charge" \
-H "Content-Type: application/json" \
-H "X-API-Key: ${API_KEY}" \
-H "X-API-Timestamp: ${TIMESTAMP}" \
-H "X-API-Signature: ${SIGNATURE}" \
-d "$BODY" | jq .
API Reference
All REST API endpoints require HMAC authentication headers: X-API-Key, X-API-Timestamp, X-API-Signature.
POST api_create_charge
Creates a new pending payment charge. Body is JSON.
| Parameter | Type | Required | Description |
|---|---|---|---|
amount | float | Yes | Payment amount (> 0) |
currency | string | No | Currency code (default: USD) |
item_name | string | No | Product or service name |
buyer_name | string | No | Buyer's full name |
buyer_email | string | No | Buyer's email address |
transaction_ref | string | No | Unique ref (auto-generated if omitted) |
return_url | string | No | Redirect URL on success |
cancel_url | string | No | Redirect URL on cancel |
webhook_url | string | No | Webhook URL for async notifications |
{
"success": true,
"data": {
"id": 1,
"transaction_ref": "TXN-...",
"amount": 10.00,
"currency": "USD",
"status": "pending",
"buyer_name": "John Doe",
"buyer_email": "[email protected]",
"item_name": "Product Name",
"created_at": "2026-06-26T12:00:00+00:00"
}
}
GET api_get_charge
Retrieves details of a single charge. Query parameters.
| Parameter | Type | Required | Description |
|---|---|---|---|
transaction_ref | string | Yes* | Transaction reference |
transaction_id | int | Yes* | Transaction ID (alternative) |
* Either transaction_ref or transaction_id is required.
{
"success": true,
"data": {
"id": 1,
"transaction_ref": "TXN-...",
"amount": 10.00,
"currency": "USD",
"status": "pending",
"payment_method": "elbatal_pay",
"buyer_name": "John Doe",
"buyer_email": "[email protected]",
"meta_data": { "item_name": "Product Name" },
"created_at": "2026-06-26T12:00:00+00:00",
"updated_at": "2026-06-26T12:00:00+00:00"
}
}
GET api_list_charges
Lists charges for your gateway with optional filters. Query parameters.
| Parameter | Type | Required | Description |
|---|---|---|---|
status | string | No | Filter: pending, completed, failed, cancelled, refunded |
page | int | No | Page number (default: 1) |
per_page | int | No | Results per page (default: 20, max: 100) |
{
"success": true,
"data": {
"charges": [
{
"id": 1,
"transaction_ref": "TXN-...",
"amount": 10.00,
"currency": "USD",
"status": "pending",
"payment_method": "elbatal_pay",
"buyer_name": "John Doe",
"buyer_email": "[email protected]",
"created_at": "2026-06-26T12:00:00+00:00",
"updated_at": null
}
],
"total": 42,
"page": 1,
"per_page": 20,
"total_pages": 3
}
}
POST api_capture_charge
Completes / captures a pending charge. Body is JSON.
| Parameter | Type | Required | Description |
|---|---|---|---|
transaction_ref | string | Yes* | Transaction reference |
transaction_id | int | Yes* | Transaction ID (alternative) |
* Either transaction_ref or transaction_id is required.
{
"success": true,
"data": {
"status": "completed",
"message": "Payment captured"
}
}
POST api_void_charge
Cancels / voids a pending charge. Body is JSON.
| Parameter | Type | Required | Description |
|---|---|---|---|
transaction_ref | string | Yes* | Transaction reference |
transaction_id | int | Yes* | Transaction ID (alternative) |
* Either transaction_ref or transaction_id is required.
{
"success": true,
"data": {
"status": "cancelled",
"message": "Payment voided"
}
}
POST api_refund_charge
Refunds a completed charge. Body is JSON.
| Parameter | Type | Required | Description |
|---|---|---|---|
transaction_ref | string | Yes* | Transaction reference |
transaction_id | int | Yes* | Transaction ID (alternative) |
* Either transaction_ref or transaction_id is required.
{
"success": true,
"data": {
"status": "refunded",
"message": "Payment refunded"
}
}
Error Response Format
All endpoints return errors with an appropriate HTTP status code:
{
"success": false,
"error": "Descriptive error message"
}
| Status Code | Description |
|---|---|
| 401 | Missing or invalid authentication headers / expired timestamp |
| 404 | Unknown action |
| 422 | Validation error (e.g. missing required field, invalid amount) |