Developer Documentation

Introduction & Authentication

This documentation provides a comprehensive guide to integrating our payment gateway. All API requests must be authenticated by including your API key in the request header.

Authorization: Bearer YOUR_SECRET_API_KEY

Payment Flow Overview

The integration process relies on the user's browser to confirm the payment. The flow follows these steps:

1. Step 1: Initiate Payment. Your server sends a secure request to our /v1/checkout endpoint, including your site's unique Base URL for verification.
2. Step 2: Redirect User. Our API validates your Base URL and responds with a unique payment_url. Your application must immediately redirect the user's browser to this URL.
3. Step 3: Customer Pays. The customer completes the payment on our secure checkout page.
4. Step 4: Return to Your Site. After a successful payment, our gateway redirects the user's browser back to the success_url you provided, appending the unique transaction_id as proof of payment.
5. Step 5: Verify on Your Server. Your script at the success_url reads this transaction_id and updates your database to mark the order as "Paid".

1. Initiate a Payment

To start a payment, send a POST request to the Payment Initiation Endpoint. For security, you must include your site's Base URL to verify the request's origin.

Endpoint

POST https://your-domain.com/api/v1/checkout

Request Body (JSON)

{
    "amount": 150.50,
    "client_base_url": "https://your-domain.com/api",
    "customer_name": "John Doe",
    "customer_email": "john.doe@example.com",
    "success_url": "https://yourwebsite.com/order/success.php",
    "cancel_url": "https://yourwebsite.com/cart.php",
    "meta_data": "{\"order_id\": \"YOUR_UNIQUE_ORDER_ID_123\"}"
}

Parameters

• amount (float, required): The total amount to be paid.
• client_base_url (string, required): Your site's API Base URL. This must exactly match the "Base URL" found on your API Settings page.
• customer_name (string, optional): The customer's full name.
• customer_email (string, optional): The customer's email address.
• success_url (string, required): The URL on your site where the customer will be redirected after a successful payment.
• cancel_url (string, required): The URL where the customer is sent if they cancel.
• meta_data (JSON string, optional): A JSON string for any extra data, like your internal order_id.

Success Response (JSON)

{
    "status": "success",
    "payment_url": "https://your-domain.com/checkout?trx_id=a1b2c3..."
}
// Your server must now redirect the user's browser to the value of "payment_url".

Error Response (Example)

If the client_base_url does not match the one stored in your settings, the request will be rejected:

{
    "status": "error",
    "message": "Domain mismatch. দুঃখিত, সংযোগ স্থাপন করা যায়নি।"
}

2. Handle the Customer's Return

After a successful payment, the user will be redirected to your success_url with the payment's unique transaction ID appended as a query parameter.

Example Return URL:

https://yourwebsite.com/order/success.php?transaction_id=CJH1D2Y4W1

What Your `success.php` Script Must Do:

1. Read the transaction_id from the URL's query parameters.
2. Update your order's status to "Paid" or "Completed" in your database, storing the received transaction_id as proof of payment.
3. Display a "Thank You" or order confirmation message to the customer.

Code Example (Plain PHP):

<?php
$transactionId = $_GET['transaction_id'] ?? null;

if ($transactionId) {
    // 1. Find the order in your database that was pending.
    // 2. Update its status to 'completed'.
    // 3. Store the $transactionId as the payment reference.
    // 4. Show a success message to the customer.
    echo "Thank you! Your payment with Transaction ID: " . htmlspecialchars($transactionId) . " was successful.";
} else {
    echo "Payment verification failed.";
}
?>