HMEA Gateway - Developer Documentation

Merchant Integration Guide

This guide provides a step-by-step process for a merchant to integrate their website with the payment gateway.

Step 1: Obtain Credentials

Before you can use the gateway, you must be registered as a merchant. From the gateway's admin panel, you will receive two critical pieces of information:

Merchant ID: A unique public identifier for your account (e.g., MERCH-B1500AE1A6E4).
API Secret Key: A private key used for secure server-to-server communication. Never share this key publicly.

Step 2: Initiate a Payment

To start a payment, you need to redirect your customer from your website to the gateway's pay.php page with several parameters in the URL.

Gateway Endpoint

The target URL for payment initiation is: https://hmea.top/pay.php

Building the Payment URL

You must construct a URL with the following query parameters:

Parameter	Type	Description
`merchant_id`	String	Required. Your unique Merchant ID.
`amount`	Float	Required. The payment amount (e.g., 150.50).
`invoice_id`	String	Required. A unique ID for this transaction from your system.
`success_url`	String	Required. The URL to redirect the user to after a successful payment.
`fail_url`	String	Required. The URL to redirect the user to after a failed or cancelled payment.
`payer_name`	String	Optional. The full name of the customer.
`payer_email`	String	Optional. The email address of the customer.
`payer_mobile`	String	Optional. The mobile number of the customer.

PHP Example: Payment Form

<?php
// --- MERCHANT CONFIGURATION ---
$my_merchant_id = 'MERCH-B1500AE1A6E4';
$my_success_url = 'https://your-site.com/success.php'; // Must be updated by the merchant
$my_fail_url = 'https://your-site.com/failed.php';     // Must be updated by the merchant
$gateway_url = 'https://hmea.top/pay.php'; // Dynamic Gateway URL

if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    // ... (validation code here) ...

    $invoice_id = 'INV-' . time();
    $payment_params = [
        'merchant_id'  => $my_merchant_id,
        'amount'       => $_POST['amount'],
        'invoice_id'   => $invoice_id,
        'success_url'  => $my_success_url,
        'fail_url'     => $my_fail_url,
        'payer_name'   => $_POST['payer_name'],
        'payer_email'  => $_POST['payer_email'],
        'payer_mobile' => $_POST['payer_mobile']
    ];
    $redirect_url = $gateway_url . '?' . http_build_query($payment_params);
    header("Location: " . $redirect_url);
    exit();
}
?>
<!-- HTML form goes here -->
                            

Step 3: Handle the Return Redirect

After the customer completes the payment process on the bKash site, they will be redirected back to the success_url or fail_url you provided. The gateway will append several query parameters to this URL.

Successful Payment Parameters:

status: Will be 'success'.
amount: The transaction amount.
invoice_id: Your original invoice ID.
trx_id: The final bKash Transaction ID.
signature: A security hash to verify the integrity of the data.

Security Check: Verifying the Signature

To ensure the data has not been tampered with, you **must** verify the signature on your server.

<?php
$api_secret_key = 'YOUR_API_SECRET_KEY'; // Your secret key

$received_data = [
    'status'     => $_GET['status'],
    'amount'     => $_GET['amount'],
    'invoice_id' => $_GET['invoice_id'],
    'trx_id'     => $_GET['trx_id']
];

$received_signature = $_GET['signature'];

// Recreate the signature string
$data_string = implode('|', $received_data) . '|' . $api_secret_key;
$expected_signature = hash('sha256', $data_string);

if (hash_equals($expected_signature, $received_signature)) {
    echo "Payment is verified and successful!";
    // Update your database, show success message, etc.
} else {
    echo "Verification failed! The request may be fraudulent.";
    // Do not process the order.
}
?>
                            

API Reference

The gateway provides a server-to-server API endpoint for verifying transactions at any time.

POST /api/v1/verify_payment.php

This endpoint allows you to check the status of a payment using either your invoice_id or the final bkash_trx_id.

API Endpoint

The target URL for API verification is: https://hmea.top/api/v1/verify_payment.php

Request Body (JSON)

Parameter	Type	Description
`merchant_id`	String	Required. Your unique Merchant ID.
`api_secret_key`	String	Required. Your private API Secret Key.
`invoice_id`	String	Conditional. Required if `bkash_trx_id` is not provided.
`bkash_trx_id`	String	Conditional. Required if `invoice_id` is not provided.

PHP cURL Example

<?php
$api_url = 'https://hmea.top/api/v1/verify_payment.php'; // Dynamic Verification API URL
$post_data = [
    'merchant_id'    => 'MERCH-B1500AE1A6E4',
    'api_secret_key' => 'YOUR_API_SECRET_KEY',
    'invoice_id'     => 'INV-1759648475-369'
];

$ch = curl_init($api_url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($post_data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>
                            

Success Response (JSON)

{
    "status": "success",
    "transaction": {
        "invoice_id": "INV-1759648475-369",
        "payment_status": "completed",
        "amount": "13.99",
        "gateway_payment_id": "TR0011...",
        "bkash_transaction_id": "CJ5...",
        "customer": {
            "name": "Eusof Ali",
            "email": "hmea.bd@gmail.com",
            "mobile": "01729792313"
        }
    }
}
                            

Security

Security is paramount in a payment system. This gateway employs several measures to ensure data integrity and prevent fraud.

Important: Your API Secret Key grants access to your transaction data. Keep it secure and never expose it in client-side code (like JavaScript or HTML).

API Secret Keys: All server-to-server API calls are authenticated using the merchant's unique API Secret Key.
Return URL Signature: When redirecting users back to the merchant's site, the gateway generates a SHA256 hash (signature) of the transaction data and the merchant's secret key. This allows the merchant to verify that the redirect is legitimate and the data hasn't been altered.
Server-Side Verification: The gateway's callback.php script performs its own server-to-server verification with the bKash API before marking a transaction as 'completed', ensuring that a client-side failure doesn't result in an incorrect status.