API Integration

Integrate Elbatal-Pay payments into your website

Overview
Integration Guide
API Endpoints

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.

1

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.

2

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.

3

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:

HeaderDescription
X-API-KeyYour merchant API key (from payment gateway settings)
X-API-TimestampCurrent Unix timestamp (server must be within 5 minutes)
X-API-SignatureHMAC-SHA256 hex digest of the signature payload

Signature payload = api_key + timestamp + HTTP method + request URI + request body

Formula signature = hash_hmac('sha256', api_key . timestamp . method . uri . body, api_secret)

Connection Information

API Base URL https://pay.elbatal-app.com

PHP Integration

Use the following PHP code to create a signed API request:

PHP <?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):

JavaScript (Node.js) 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:

Bash 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.

ParameterTypeRequiredDescription
amountfloatYesPayment amount (> 0)
currencystringNoCurrency code (default: USD)
item_namestringNoProduct or service name
buyer_namestringNoBuyer's full name
buyer_emailstringNoBuyer's email address
transaction_refstringNoUnique ref (auto-generated if omitted)
return_urlstringNoRedirect URL on success
cancel_urlstringNoRedirect URL on cancel
webhook_urlstringNoWebhook URL for async notifications
Response 200 { "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.

ParameterTypeRequiredDescription
transaction_refstringYes*Transaction reference
transaction_idintYes*Transaction ID (alternative)

* Either transaction_ref or transaction_id is required.

Response 200 { "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.

ParameterTypeRequiredDescription
statusstringNoFilter: pending, completed, failed, cancelled, refunded
pageintNoPage number (default: 1)
per_pageintNoResults per page (default: 20, max: 100)
Response 200 { "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.

ParameterTypeRequiredDescription
transaction_refstringYes*Transaction reference
transaction_idintYes*Transaction ID (alternative)

* Either transaction_ref or transaction_id is required.

Response 200 { "success": true, "data": { "status": "completed", "message": "Payment captured" } }

POST api_void_charge

Cancels / voids a pending charge. Body is JSON.

ParameterTypeRequiredDescription
transaction_refstringYes*Transaction reference
transaction_idintYes*Transaction ID (alternative)

* Either transaction_ref or transaction_id is required.

Response 200 { "success": true, "data": { "status": "cancelled", "message": "Payment voided" } }

POST api_refund_charge

Refunds a completed charge. Body is JSON.

ParameterTypeRequiredDescription
transaction_refstringYes*Transaction reference
transaction_idintYes*Transaction ID (alternative)

* Either transaction_ref or transaction_id is required.

Response 200 { "success": true, "data": { "status": "refunded", "message": "Payment refunded" } }

Error Response Format

All endpoints return errors with an appropriate HTTP status code:

Error Response { "success": false, "error": "Descriptive error message" }
Status CodeDescription
401Missing or invalid authentication headers / expired timestamp
404Unknown action
422Validation error (e.g. missing required field, invalid amount)