孟加拉支付通道API对接指南

1. 概述

本指南提供在孟加拉国集成主流支付通道API的技术指导，包括本地和国际支付解决方案。

2. 主要支付渠道

a) bKash (移动钱包)

API文档: https://developer.bkash.com
认证方式: OAuth2.0
关键端点:
- /token – 获取访问令牌
- /create – 创建交易
- /execute -执行交易

b) Nagad (电子钱包)

沙盒环境: https://sandbox.mynagad.com:30000
生产环境: https://api.mynagad.com
认证方式: API密钥+商户凭证

c) Rocket (DBBL移动银行)

测试URL: https://www.rocket.com.bd/api/v1/test/payment
生产URL: https://www.rocket.com.bd/api/v1/live/payment

d) Upay (国际卡处理)

3. API对接详细步骤

a) bKash集成流程

商户注册
- 在bKash商户门户(bkash.com/business)完成注册
- 获取Merchant Wallet ID、Username和Password

环境配置

// Node.js示例配置

const bkashConfig = {

  baseURL: process.env.BKASH_BASE_URL,

  merchantID: process.env.BKASH_MERCHANT_ID,

  username: process.env.BKASH_USERNAME, 

  password: process.env.BKASH_PASSWORD,

  appKey: process.env.BKASH_APP_KEY,

  appSecret: process.env.BKASH_APP_SECRET

};

认证流程

# Python获取token示例

import requests



auth_url = "https://tokenized.sandbox.bka.sh/v1.2.0-beta/tokenized/checkout/token/grant"

headers = {

    "Content-Type": "application/json",

    "username": MERCHANT_USERNAME, 

    "password": MERCHANT_PASSWORD  

}

data = {

    "app_key": APP_KEY,

    "app_secret": APP_SECRET  

}



response = requests.post(auth_url, json=data, headers=headers)

access_token = response.json()["id_token"]

支付请求 (REST API调用)

POST /v1/payment/create HTTP/1.1

Host: api.bkash.com  

Authorization: Bearer {access_token}  

Content-Type: application/json  



{

  "mode": "0011", //即时支付模式代码 

  "payerReference":"CUST12345",

  callbackURL:"https://yourdomain.com/callback",

  amount:"500", //BDT金额(最小单位)

 currency:"BDT"   

}

b) Nagad快速集成方案

Webhook处理注意事项：

IP白名单需包含Nagad服务器IP段(203...*)
HMAC签名验证必须实现：

// Java签名验证示例

public boolean verifySignature(String payload, String receivedSignature){

 String secretKey ="YOUR_SECRET";

 Mac sha256_HMAC = Mac.getInstance("HmacSHA256");

 sha256_HMAC.init(new SecretKeySpec(secretKey.getBytes(),"HmacSHA256"));

 String computedSignature=Base64.encodeBase64String(

      sha256_HMAC.doFinal(payload.getBytes()));

 return computedSignature.equals(receivedSignature); 

}

4. Debit/Credit卡处理通道（国际）

Upay技术参数：

参数	值
API版本	v3
编码	UTF-8
加密方式	AES-128-CBC
证书格式	.pfx

PHP加密示例：

$iv = openssl_random_pseudo_bytes(16);

$encryptedData=openssl_encrypt(

 $plaintext,'aes-128-cbc',

 $apiKey,$options=OPENSSL_ZERO_PADDING,$iv);

5．常见错误代码表

孟加拉本地支付特有的状态码：

代码	含义	解决方案
2017 余额不足提示用户充值钱包或更换支付方式
3006 运营商系统繁忙建议5分钟后重试并记录该交易尝试次数
8809 无效的OTP 检查短信网关是否正常接收验证码

需要特别注意：所有金额必须以最小货币单位(Poisha，即乘以100)发送。

6．合规要求

根据孟加拉国央行(Bangladesh Bank)规定：

✅必须存储原始交易数据至少5年
✅跨境交易需额外添加15% VAT标记
❌禁止加密货币相关交易

建议在结算报表中明确显示以下字段：

TRX_ID | CUSTOMER_NID_BIN(PII脱敏)| AMOUNT_IN_BDT VAT_STATUS SETTLEMENT_DATE

7. 高级集成方案与优化建议

a) 多支付渠道智能路由

# Python支付路由示例

def select_payment_channel(amount, user_agent):

    if amount < 500: # 小额交易优先移动钱包

        if "Android" in user_agent:

            return "bkash"

        else:

            return "nagad"

    elif amount > 10000: #大额走银行卡通道 

        return "upay"

    else:

        return "rocket"



# 结合机器学习模型优化路由决策

from sklearn.ensemble import RandomForestClassifier

model = joblib.load('payment_routing_model.pkl')

def smart_route(user_profile):

    features = [

        user_profile['device_type'],

        user_profile['transaction_history'], 

        user_profile['location']

    ]

    return model.predict([features])[0]

b) 异步处理架构设计

推荐消息队列配置：

// Spring Boot + RabbitMQ配置示例

@Bean

public Queue bkashQueue() {

   return new Queue("payment.bkash", true);

}



@RabbitListener(queues = "payment.bkash")

public void handleBkashPayment(PaymentRequest request) {

   //调用bKash API并处理响应  

}

Redis缓存策略：

SET payment:{txid} '{"status":"processing","timestamp":1625097600}' EX300 NX



// Lua脚本原子操作：

local key=KEYS[1]

local status=redis.call('GET',key)

if status=="completed" then 

   return2 --防止重复处理  

else 

   redis.call('SETEX',key,3600,'processing')   

end

8．本地化特殊需求

a) BIN号段验证（孟加拉专属）

function isBangladeshiCard(cardNumber){

 const binPrefixes=['405071','505874','606033'];

 const first6=cardNumber.substring(0,6); 

return binPrefixes.some(prefix=>first6.startsWith(prefix));

}

b) NID身份证校验算法（政府要求）：

def validate_nid(nid):    

     if len(nid)==10:#旧版格式        

         checksum=int(nid[-1])

         total=sum(int(d)* (9-i)%10 for i,d in enumerate(nid[:9]))

         returntotal%10==checksum     

     elif len(nid)==17:#新版智能卡         

          #...完整算法需包含日期校验位等复杂逻辑...

          pass      

     else:          

          raise ValueError("InvalidNIDLength")

9．性能监控指标（孟加拉市场基准）

指标	达标阈值	测量方法
API成功率	≥99.5%	Prometheus计数器+Granfana仪表盘
3DS认证延迟	<4秒	NewRelic/Sentry端到端追踪
峰值TPS容量	1000+/秒	Locust压力测试

推荐部署架构：

用户设备 → CloudflareCDN → AWS新加坡区域ECS集群 → MongoDB分片集群(Dhaka可用区)

                                      ↓ 

                                  本地银行专线接入点(DhakaPOP)

10．灾备方案特别注意事项

由于孟加拉频繁发生网络中断：

双ISP接入：必须同时连接BDCOM和GP骨干网
离线模式：支持二维码生成/扫描的离线支付流程
短信补偿机制：当主通道失败时自动切换至SMS/USSD

应急签名验证流程：

if(!internetAvailable()){

 verifyPaymentByUSSD("*322*"+txId+"#");//运营商特定短代码 

}else{

 normalApiVerification(); 

}

如需更具体的实现案例或某个支付渠道的深度技术细节，请告知您的具体使用场景和技术栈。