Standard Production Protocol

GoPay Merchant Gateway API Specification

Official integration guide for automated Collections, Disbursals, Balances, and Real-time Status Inquiries.

Gateway Credentials

Each API request requires authentication using your merchant keys assigned by the GoPay Terminal:

Parameter Description Example Value
appId Merchant App Identification / API Key GP_xxxxxxxx
secret_key Cryptographic Merchant Secret Token xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

1. Balance Query API

Fetch live multi-channel balances across all active liquidity wallets (BDT & INR).

POST GET https://api-pay.go-pay.pro/v1/Balance/bdt/ 
{
  "appId": "GP_xxxxxxxx",
  "secret_key": "YOUR_MERCHANT_SECRET_KEY"
}
{
  "code": 200,
  "status": "SUCCESS",
  "message": "Balance fetched successfully.",
  "data": {
    "merchant_id": "MIDxxxx",
    "channels": {
      "channel_1": { "name": "Channel 1 (OkExPay)", "currency": "BDT", "balance": 1500.00 },
      "channel_2": { "name": "Channel 2 (GoPay)", "currency": "BDT", "balance": 3200.50 },
      "channel_3": { "name": "Channel 3 (SafePay)", "currency": "BDT", "balance": 500.00 },
      "channel_4": { "name": "Channel 4 (India UPI/Bank)", "currency": "INR", "balance": 250.00 }
    },
    "total_bdt_balance": 5200.50,
    "total_inr_balance": 250.00
  },
  "timestamp": "2026-09-18 18:15:00"
}
curl -X POST https://api-pay.go-pay.pro/v1/Balance/bdt/ \
  -H "Content-Type: application/json" \
  -d '{"appId":"GP_xxxxxxxx", "secret_key":"YOUR_MERCHANT_SECRET_KEY"}'

2. Collect (Deposit) API

Create deposit invoices and automatically redirect users to the GoPay Cashier interface.

POST https://api-pay.go-pay.pro/v1/Collect/bdt/
Parameter Type Requirement Description
appId String REQUIRED Merchant App ID identifier.
merOrderNo String REQUIRED Unique merchant invoice order ID (e.g., 20260918178822).
amount Decimal REQUIRED Deposit capital in BDT (Min: 100.00).
payMethod String REQUIRED Payment Route (BKASH, NAGAD, ROCKET).
notifyUrl URL REQUIRED Asynchronous webhook URL for IPN transaction notifications.
returnUrl URL REQUIRED User landing page URL after completing cashier checkout. 
<form id="gopay_form" action="https://api-pay.go-pay.pro/v1/Collect/bdt/" method="POST">
    <input type="hidden" name="appId" value="GP_xxxxxxxx">
    <input type="hidden" name="merOrderNo" value="ORD_<?php echo time(); ?>">
    <input type="hidden" name="amount" value="500.00">
    <input type="hidden" name="payMethod" value="NAGAD">
    <input type="hidden" name="notifyUrl" value="https://tigroclub66.com/pay/gopay_notify.php">
    <input type="hidden" name="returnUrl" value="https://tigroclub66.com/">
</form>
<script>document.getElementById('gopay_form').submit();</script>
curl -X POST https://api-pay.go-pay.pro/v1/Collect/bdt/ \
  -d "appId=GP_xxxxxxxx" \
  -d "merOrderNo=20260918178822" \
  -d "amount=500.00" \
  -d "payMethod=BKASH" \
  -d "notifyUrl=https://tigroclub66.com/pay/gopay_notify.php" \
  -d "returnUrl=https://tigroclub66.com/"

3. Deposit Query API

Query real-time status and telemetry of any deposit transaction.

POST GET https://api-pay.go-pay.pro/v1/Deposit-Query/bdt/ 
{
  "appId": "GP_xxxxxxxx",
  "secret_key": "YOUR_MERCHANT_SECRET_KEY",
  "order_id": "202608291787981759552569"
}
{
  "code": 200,
  "status": "SUCCESS",
  "message": "Order fetched successfully.",
  "data": {
    "order_id": "202608291787981759552569",
    "merchant_id": "MID333255",
    "upstream_trade_no": "GP202608291135592467",
    "channel_provider": "GOPAY",
    "method": "Nagad",
    "amount": 100.00,
    "fee": 1.85,
    "net_amount": 98.15,
    "status": "Success",
    "created_at": "2026-08-29 11:35:59"
  }
}

4. IPN / Webhook Callback Handling

Mandatory Acknowledgment & Secret Key Check: GoPay delivers webhooks with your secret_key. Your server MUST verify this token and echo strictly lowercase ok on success. 
<?php
require_once("gopayconfig.php");

$raw = file_get_contents("php://input");
$data = json_decode($raw, true) ?: $_POST;

$receivedSecretKey = $data['secret_key'] ?? '';
$orderNo           = $data['merOrderNo'] ?? ($data['order_id'] ?? '');
$amount            = $data['amount'] ?? 0;
$status            = strtoupper($data['orderStatus'] ?? ($data['status'] ?? ''));

// Validate Secret Key
if (defined('gopay_SECRET_KEY') && $receivedSecretKey !== gopay_SECRET_KEY) {
    echo "fail";
    exit;
}

if (!empty($orderNo) && ($status === 'SUCCESS' || $status === '1')) {
    // 1. Credit balance to user account
    // 2. Mark order as paid
    echo "ok";
    exit;
}

echo "fail";
?>

5. Pay-Out (Withdraw) API

Automated disbursement directly from your specified channel liquidity balance.

POST https://api-pay.go-pay.pro/v1/Pay-Out/bdt/
Strict Registered Check: Recipient numbers must be registered and marked Active in your Withdraw API Manage dashboard prior to calling this endpoint. 
{
  "appId": "GP_xxxxxxxx",
  "secret_key": "YOUR_MERCHANT_SECRET_KEY",
  "channel": 1,
  "amount": 500.00,
  "method": "bkash",
  "receiver_phone": "01605232033",
  "receiver_name": "Rahim Khan"
}
{
  "appId": "GP_xxxxxxxx",
  "secret_key": "YOUR_MERCHANT_SECRET_KEY",
  "channel": 4,
  "amount": 1000.00,
  "account_no": "919876543210",
  "ifsc_code": "HDFC0001234",
  "receiver_name": "Amit Sharma"
}
{
  "code": 200,
  "status": "SUCCESS",
  "message": "Withdrawal processed and logged successfully.",
  "data": {
    "payout_id": "DF20260918178833",
    "gateway_trade_no": "F5442E81148E5A09413E4455704A3CA0DD544BD8389F7",
    "merchant_id": "MIDxxxx",
    "channel": 1,
    "amount": 500.00,
    "fee": 7.50,
    "total_deduction": 507.50,
    "status": "Success",
    "target_number": "01605232033"
  }
}

6. Withdraw Query API

Inspect status, transaction ID, and fee details of any outbound payout request.

POST GET https://api-pay.go-pay.pro/v1/withdraw-Query/bdt/ 
{
  "appId": "GP_xxxxxxxx",
  "secret_key": "YOUR_MERCHANT_SECRET_KEY",
  "payout_id": "DF20260828231643835"
}
{
  "code": 200,
  "status": "SUCCESS",
  "message": "Withdrawal details fetched successfully.",
  "data": {
    "payout_id": "DF20260828231643835",
    "transfer_id": "F5442E81148E5A09413E4455704A3CA0DD544BD8389F7",
    "merchant_id": "MID333255",
    "channel_wallet": 1,
    "account_name": "ffffff",
    "mobile_number": "01605232033",
    "method": "Nagad",
    "amount": 400.00,
    "fee": 6.00,
    "net_amount": 400.00,
    "status": "Success",
    "created_at": "2026-08-28 17:16:44"
  }
}