孟加拉支付网关API集成指南

1. 准备工作

在开始集成孟加拉支付网关API前，请确保：

注册商户账户：联系当地支付服务提供商(如bKash、Nagad、Rocket等)获取商户ID和API凭证
确定交易类型：明确您需要集成的功能(收款、退款、查询等)
准备开发环境：确保您的服务器能够处理HTTPS请求并具备JSON解析能力

2. API基础信息

常用端点

- 生产环境: https://api.paymentprovider.com/v1/

- 沙盒环境: https://sandbox.paymentprovider.com/v1/

HTTP头信息

Content-Type: application/json

Authorization: Bearer {your_api_key}

X-MERCHANT-ID: {your_merchant_id}

3. 核心API集成步骤

A. SDK安装(以PHP为例)

composer require payment-provider/sdk

或直接使用HTTP客户端：

$client = new GuzzleHttp\Client();

B. 发起支付请求示例(PHP)

$response = $client->post('https://api.paymentprovider.com/v1/payments', [

    'headers' => [

        'Authorization' => 'Bearer '.$apiKey,

        'X-MERCHANT-ID' => $merchantId,

        'Content-Type' => 'application/json',

    ],

    'json' => [

        'amount' => 1000, // Taka金额(最小单位)

        'currency' => "BDT",

        'order_id' => uniqid(),

        'customer_msisdn' => "88017XXXXXXXX", //客户手机号(bKash格式)

        'callback_url' => "https://yourdomain.com/callback",

    ]

]);

C. Webhook处理示例(Node.js)

app.post('/payment-callback', (req, res) => {

    const signature = req.headers['x-signature'];

    

    //验证签名逻辑

    

    const paymentStatus = req.body.status;

    

    if(paymentStatus === "COMPLETED") {

       //更新订单状态为已付款 

       console.log(`Payment ${req.body.transaction_id} succeeded`);

       return res.sendStatus(200);

   }

   

   console.error("Payment failed:", req.body);

   return res.sendStatus(400); 

});

4. API响应处理

成功响应示例:

{

   "status": "PENDING",

   "transaction_id": "TRX123456789",

   "payment_url": "..."

}

错误响应示例:

{

   "error_code": "",

   ""

}

5. 常见API功能实现

A. 支付状态查询

import requests



def check_payment_status(transaction_id):

    url = f"https://api.paymentprovider.com/v1/payments/{transaction_id}"

    headers = {

        "Authorization": f"Bearer {API_KEY}",

        "X-MERCHANT-ID": MERCHANT_ID

    }

    

    response = requests.get(url, headers=headers)

    return response.json()



# 使用示例

status = check_payment_status("TRX123456789")

print(status)

B. 退款处理(Java示例)

public JSONObject processRefund(String transactionId, BigDecimal amount) throws Exception {

    String url = "https://api.paymentprovider.com/v1/refunds";

    

    HttpRequest request = HttpRequest.newBuilder()

        .uri(URI.create(url))

        .header("Content-Type", "application/json")

        .header("Authorization", "Bearer " + apiKey)

        .header("X-MERCHANT-ID", merchantId)

        .POST(HttpRequest.BodyPublishers.ofString(

            new JSONObject()

                .put("original_transaction_id", transactionId)

                .put("amount", amount.multiply(new BigDecimal(100)).intValue())

                .toString()

        ))

        .build();

        

    HttpResponse<String> response = HttpClient.newHttpClient()

                                        .send(request, HttpResponse.BodyHandlers.ofString());

                                        

    return new JSONObject(response.body());

}

6. 安全最佳实践

敏感数据保护：
- API密钥和商户ID应存储在环境变量中，不要硬编码在代码里
- PCI DSS合规：不直接处理银行卡信息

请求验证：

// Node.js签名验证示例 

const crypto = require('crypto');



function verifySignature(payload, receivedSignature) {

    const secret = process.env.WEBHOOK_SECRET;

    const hmac = crypto.createHmac('sha256', secret);

    const computedSignature = hmac.update(JSON.stringify(payload)).digest('hex');

    

    return computedSignature === receivedSignature;

}

错误处理建议：

try {

    $response->getBody()->getContents();

} catch (Exception $e) {

//记录完整错误日志但不暴露给用户

    

$logger->error("[Payment Error] ".$e->getMessage(), [

'trace' => $e->getTrace(),

'request' => $requestData 

]);



//返回通用错误消息给客户端  

http_response_code(500);

echo json_encode(['error' => 'Payment processing failed']);

}

7．测试与上线清单

✅沙盒环境测试项目	要求
基本支付流程	成功创建交易并跳转至支付页面
异步通知	模拟所有可能的状态回调
异常场景	无效金额、重复订单号等情况处理
对账文件下载	确认能正确解析每日结算报表

生产环境检查项:

HTTPS证书有效且配置正确
IP白名单已添加至商户后台
Webhook端点负载测试通过

8．本地化注意事项

孟加拉国特有需求:

货币与金额

BDT单位为波夏(Poisha)，1塔卡=100波夏
API通常要求以最小单位提交整数金额（如10塔卡→amount:1000）

手机号格式：必须包含国家代码(880)但去除前置+或00

特殊业务规则：部分网关限制单笔交易不超过50万BDT

9. 高级集成功能

A. 批量付款处理

# Python批量付款示例（适用于工资发放等场景）

def batch_payments(payment_list):

    url = "https://api.paymentprovider.com/v1/batch-payments"

    headers = {

        "Authorization": f"Bearer {API_KEY}",

        "X-MERCHANT-ID": MERCHANT_ID,

        "X-BATCH-ID": str(uuid.uuid4())

    }

    

    payload = {

        "batch_type": "DISBURSEMENT",

        "payments": [

            {

                "recipient_msisdn": payment['phone'],

                "amount": int(payment['amount'] * 100),

                "reference_id": payment['emp_id']

            } for payment in payment_list

        ]

    }

    

    response = requests.post(url, json=payload, headers=headers)

    

    # 处理异步回调结果

B. OTP验证集成（针对高金额交易）

// Java OTP验证流程示例

public class OTPService {

    

    public boolean verifyTransactionWithOTP(String transactionId, String otp) {

        

        // Step 1: Request OTP verification from gateway 

        

        // Step 2: Handle different response scenarios

10．调试与故障排除

常见错误代码表：

HTTP状态码	API错误码	Bangla含义	解决方案
400	INVALID_AMOUNT	অবৈধ পরিমাণ	检查金额是否为整数且≥最小交易额
401	AUTH_FAILED	অনুমোদন ব্যর্থ হয়েছে

实时日志分析建议：

# Linux系统查看最近API调用日志（示例）

tail -f /var/log/payment_gateway.log | grep -E 'status_code=(4\d{2}|5\d{2})'

网络连接测试工具：

// Node.js网络诊断脚本可用以下方式检测:

const ping = require('net-ping');

const session = ping.createSession();



session.pingHost('api.paymentprovider.com', (error, target) => {

});

11．合规与法律要求

孟加拉国央行(Bangladesh Bank)特别规定：

数据存储：所有交易记录需在境内保存至少5年

-- MySQL建表示例应符合以下结构字段:

CREATE TABLE transactions (

    id VARCHAR(36) PRIMARY KEY,

    amount DECIMAL(12,2),

    customer_msisdn VARCHAR(15),

    status ENUM(),

反洗钱(AML)：单日累计超过75万BDT需人工审核
增值税(VAT)：必须在发票中明确显示15%的增值税信息

需要继续扩展哪个部分的详细内容？例如：

🛡️更深入的安全防护措施
📱移动端SDK的具体接入方法
💳银行卡绑定支付的特殊流程

孟加拉支付网关-三方支付

开发者指南：如何集成孟加拉支付网关API？