Integration Guide

Overview

Merchant888 provides a simple REST API for accepting deposits (payin) via bKash & Nagad and sending instant payouts in Bangladesh.

Your Credentials

After registration you will receive:

• merchant_code — Your unique merchant identifier
• secret_key — Used only for generating signatures (never send in requests)
• Base URL: https://api.merchant888.site

How to Generate Signature

All requests (except some public ones) require an MD5 signature.

sign = MD5( merchant_code + order_no + order_amount + secret_key )

Exact parameter order may vary per endpoint — always follow the API Docs for the specific endpoint. Parameters are concatenated in alphabetical order or as documented, then MD5 hashed (lowercase hex).

1. Create Payin Order

Create a deposit order. Customer will pay via bKash or Nagad.

 $merchant_code,
    "country_code"  => "BD",
    "order_no"      => $order_no,
    "order_amount"  => $amount,
    "pay_type"      => "bkash", // or nagad
    "notify_url"    => "https://yoursite.com/webhook/payin",
    "return_url"    => "https://yoursite.com/success",
    "sign"          => $sign
];

$ch = curl_init("https://api.merchant888.site/payin");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
    CURLOPT_RETURNTRANSFER => true
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>

const crypto = require('crypto');
const axios = require('axios');

const merchant_code = "YOUR_MERCHANT_CODE";
const secret_key    = "YOUR_SECRET_KEY";
const order_no      = "ORD" + Date.now();
const amount        = "500";

const sign = crypto.createHash('md5')
  .update(merchant_code + order_no + amount + secret_key)
  .digest('hex');

const data = {
  merchant_code,
  country_code: "BD",
  order_no,
  order_amount: amount,
  pay_type: "bkash",
  notify_url: "https://yoursite.com/webhook/payin",
  return_url: "https://yoursite.com/success",
  sign
};

axios.post("https://api.merchant888.site/payin", data)
  .then(res => console.log(res.data))
  .catch(err => console.error(err.response?.data || err));

import hashlib
import time
import requests

merchant_code = "YOUR_MERCHANT_CODE"
secret_key    = "YOUR_SECRET_KEY"
order_no      = f"ORD{int(time.time())}"
amount        = "500"

sign_str = merchant_code + order_no + amount + secret_key
sign = hashlib.md5(sign_str.encode()).hexdigest()

data = {
    "merchant_code": merchant_code,
    "country_code": "BD",
    "order_no": order_no,
    "order_amount": amount,
    "pay_type": "bkash",
    "notify_url": "https://yoursite.com/webhook/payin",
    "return_url": "https://yoursite.com/success",
    "sign": sign
}

r = requests.post("https://api.merchant888.site/payin", json=data)
print(r.json())

curl -X POST https://api.merchant888.site/payin \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_code": "YOUR_MERCHANT_CODE",
    "country_code": "BD",
    "order_no": "ORD123456",
    "order_amount": "500",
    "pay_type": "bkash",
    "notify_url": "https://yoursite.com/webhook/payin",
    "return_url": "https://yoursite.com/success",
    "sign": "GENERATED_MD5_SIGNATURE"
  }'

2. Create Payout Order

Send money instantly to a bKash or Nagad wallet.

// Python example
import hashlib, time, requests

merchant_code = "YOUR_MERCHANT_CODE"
secret_key    = "YOUR_SECRET_KEY"
order_no      = f"PO{int(time.time())}"
amount        = "1000"

sign = hashlib.md5((merchant_code + order_no + amount + secret_key).encode()).hexdigest()

data = {
    "merchant_code": merchant_code,
    "country_code": "BD",
    "order_no": order_no,
    "order_amount": amount,
    "pay_type": "bkash",          # or nagad
    "bank_code": "bkash",
    "bank_card_no": "017XXXXXXXX", # 11-digit phone starting with 0
    "bene_name": "Customer Name",
    "notify_url": "https://yoursite.com/webhook/payout",
    "sign": sign
}

r = requests.post("https://api.merchant888.site/payout", json=data)
print(r.json())

3. Check Balance

import hashlib, requests

merchant_code = "YOUR_MERCHANT_CODE"
secret_key    = "YOUR_SECRET_KEY"
sign = hashlib.md5((merchant_code + secret_key).encode()).hexdigest()

data = {
    "merchant_code": merchant_code,
    "sign": sign
}

r = requests.post("https://api.merchant888.site/balance", json=data)
print(r.json())
# Expected: { "code": 0, "BD": { "balance": "10000", "canPayoutBalance": "8500", ... } }

4. Handle Webhook (Notify URL)

When order status changes, we POST JSON to your notify_url.

# Flask example
from flask import Flask, request
app = Flask(__name__)

@app.route("/webhook/payin", methods=["POST"])
def payin_webhook():
    data = request.json
    # Verify signature if provided
    order_no = data.get("order_no")
    status   = data.get("status")   # success / failed / paying
    amount   = data.get("order_amount")

    if status == "success":
        # Update your database, credit user etc.
        pass

    return "OK"  # Always return 200 OK quickly

Best Practices

• Always use HTTPS for notify_url and return_url
• Store order_no uniquely on your side before creating the order
• Idempotency: check if order already processed before crediting
• Use integer amounts only (no decimal points)
• Phone numbers must be 11 digits starting with 0 (e.g. 017XXXXXXXX)
• Test with small amounts first in sandbox if available