孟加拉支付网关接入指南
作为支付平台专家，我将为您介绍如何快速将开源项目接入孟加拉主流支付网关。
主要孟加拉支付网关选项
- bKash – 最流行的移动钱包
- Nagad – 政府支持的电子金融服务
- Rocket – Dutch-Bangla Bank的移动金融服务
- Upay – United Commercial Bank的数字支付方案
快速接入步骤
1. bKash集成流程
// Node.js示例代码
const axios = require('axios');
async function createBkashPayment(amount, orderId) {
const response = await axios.post('https://checkout.sandbox.bka.sh/v1.2.0-beta/checkout/payment/create', {
amount: amount,
merchantInvoiceNumber: orderId,
intent: 'sale'
}, {
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'X-APP-Key': 'YOUR_APP_KEY'
}
});
return response.data.paymentID;
}
2. Nagad集成要点
- API文档：https://developer.nagad.com.bd/
- Sandbox环境可用性良好
- Webhook支持交易状态通知
PHP示例代码（适用于多个网关）
function processBangladeshPayment($gateway, $params) {
switch($gateway) {
case 'bkash':
// bKash处理逻辑...
break;
case 'nagad':
// Nagad处理逻辑...
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.mynagad.com/api/check-out");
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
"merchantId" => "YOUR_MERCHANT_ID",
"orderId" => $params['order_id'],
"amount" => $params['amount']
// ...其他参数...
]));
关键注意事项
- 合规要求
- RBI和Bangladesh Bank的监管规定必须遵守
- PCI DSS合规对于存储卡信息是强制的（如适用）
2.沙盒测试
# bKash沙盒凭据获取方式：
POST /v1/auth/token/grant HTTP/1.1
Host: checkout.sandbox.bka.sh
3.费率结构
| Gateway | Transaction Fee | Settlement Time |
|---------|----------------:|------------------|
| bKash | ~2% | T+3 |
| Nagad | ~0%-5% | T+7 |
4.常见问题解决
*错误码401* → API密钥过期或无效
*错误码403* → IP白名单未配置
建议使用以下开源库加速开发：
composer require nagdev/bangladesh-payment-gateways
npm install bkash-merchant-sdk –save-dev
需要更详细的特定平台实现细节吗？我可以针对您选择的某个具体网关提供深入指导。
深入孟加拉支付网关集成细节
作为支付平台专家，我将为您提供更深入的孟加拉支付网关接入技术细节和最佳实践。
bKash 深度集成指南
1. OAuth2.0认证流程
bKash使用标准的OAuth2.0流程获取访问令牌：
# Python示例 - 获取bKash访问令牌
import requests
def get_bkash_token():
url = "https://checkout.sandbox.bka.sh/v1.2.0-beta/checkout/token/grant"
headers = {
"Content-Type": "application/json",
"username": "YOUR_MERCHANT_USERNAME",
"password": "YOUR_MERCHANT_PASSWORD"
}
payload = {
"app_key": YOUR_APP_KEY,
"app_secret": YOUR_APP_SECRET
}
response = requests.post(url, json=payload, headers=headers)
return response.json()["id_token"]
2. Webhook配置最佳实践
建议配置以下端点处理异步通知：
POST /api/payments/bkash/callback HTTP/1.1
Content-Type: application/json
{
paymentID: 'TR00123456',
status: 'Completed',
amount: '500',
merchantInvoiceNumber: 'ORD-10001'
}
Nagad高级集成方案
3D Secure处理流程
Nagad支持3DS验证，典型流程如下：
// Java示例 - Nagad付款请求创建
public class NagadPayment {
public String createPaymentRequest(String orderId, double amount) throws Exception {
String apiUrl = isSandbox ?
SANDBOX_URL : PRODUCTION_URL;
HttpPost post = new HttpPost(apiUrl + "/create-payment");
// Merchant数字签名生成 (关键安全步骤)
String signatureData = orderId + amount + TIMESTAMP;
String signature = generateSHA256Signature(signatureData);
// ...设置请求头和参数...
try (CloseableHttpResponse response = httpClient.execute(post)) {
PaymentResponse respObj = objectMapper.readValue(
EntityUtils.toString(response.getEntity()),
PaymentResponse.class);
return respObj.getCheckoutUrl();
}
}
private String generateSHA256Signature(String data) {...}
}
Rocket/DBBL Mobile Banking集成要点
USSD回调处理模式（适用于功能手机用户）
流程图:
商户系统 → ROCKET API → SMS/USSD推送 → 用户确认 → Callback URL通知结果
↑ ↓
PIN验证 更新订单状态
PHP实现示例：
function rocketUSSDCallback($paymentRef) {
$statusCheckUrl ="https://rocket.com.bd/api/v2/payment/$paymentRef";
do { //轮询设计(因部分低端设备可能无法callback)
$statusResp=http_get($statusCheckUrl);
if($statusResp->isSuccessful()){
updateOrderStatus($paymentRef,'COMPLETED');
break;
} else if(time() > MAX_TIMEOUT){
logFailedTransaction(...);
break;
}
sleep(POLLING_INTERVAL);
} while(true);
}
Upay特定需求解决方案
常见问题排查表
| 症状 | 可能原因 | 解决方案 |
|---|---|---|
| "Invalid hash value" | 签名算法错误 | 确保使用HMAC-SHA256而非MD5 |
| "Merchant not found" | 终端IP未注册 | 联系Upay技术支持添加您的服务器IP |
| "Daily limit exceeded" | 账户风控限制 | 提交企业资质文件申请提额 |
多网关统一接口设计建议
推荐采用策略模式封装不同网关：
// TypeScript接口抽象示例
interface BangladeshPGateway {
processPayment(order: Order): Promise<PaymentResult>;
handleCallback(data: unknown): Promise<OrderUpdate>;
}
class BkashAdapter implements BangladeshPGateway {...}
class NagadAdapter implements BangladeshPGateway {...}
// Factory根据商户配置返回实例
export function getGateway(config): BangladeshPGateway {
switch(config.gatewayName){
case 'bkash': return new BkashAdapter(config);
case 'nagad': return new NagadAdapter(config);
default:
throw new Error('Unsupported gateway');
}}
需要我针对以下任何方面进一步展开吗？
- bKash批量退款实现方案
- Nagad跨境结算的特别注意事项
- Rocket账单支付的QR码整合方法
# 孟加拉支付网关高级集成方案
作为支付平台专家，我将为您深入探讨更专业的集成场景和解决方案。
bKash批量退款实现方案
1. CSV文件批量处理架构
“`python
# Python批量退款处理器
import csv
from concurrent.futures import ThreadPoolExecutor
def process_bkash_batch_refund(file_path):
with open(file_path, mode=’r’) as csv_file:
reader = csv.DictReader(csv_file)
def refund_single(row):
payload = {
“paymentID”: row[‘original_payment_id’],
“amount”: row[‘refund_amount’],
“trxID”: row[‘original_trx_id’],
“sku”: f”batch_{row[‘batch_id’]}”,
“reason”: row.get(‘reason’, ‘Customer Refund’)
}
try:
response = requests.post(
BKASH_REFUND_URL,
json=payload,
headers={“Authorization”: f”Bearer {get_bkash_token()}”}
)
# 结果写入审计数据库
log_refund_attempt(row, response.json())
except Exception as e:
log_error(row, str(e))
# 使用线程池并行处理(建议不超过5并发，避免API限流)
with ThreadPoolExecutor(max_workers=5) as executor:
executor.map(refund_single, reader)
generate_reconciliation_report(file_path)
“`
关键注意事项：
– DBBL银行工作日9AM-4PM才能处理退款请求
– 每笔退款需保留原始paymentID至少180天
– 单批次建议不超过100笔交易（超出需要分拆）
Nagad跨境结算特别指南
SWIFT汇款对接流程（针对国际商户）
“`
┌─────────────┐ ┌───────────────┐ ┌───────────────────┐
│ Merchant │ → │ Nagad │ → │ Bangladesh Bank │
│ Foreign A/C ├───┤ Nostro Account├───┤ SWIFT Clearing │
└─────────────┘ └───────────────┘ └───────────────────┘
“`
外汇管制要求：
1. 文档准备清单：
– Form C (Bangladesh Bank规定格式)
– Proforma Invoice副本
– BIN证书复印件(如适用)
2. PHP实现汇率锁定：
“`php
function nagadForexLock($amountUSD) {
$forexApiUrl = ‘https://api.nagad.com.bd/forex/v1/lock-rate’;
$response = http_post($forexApiUrl,[
‘currencyPair’ => ‘USD-BDT’,
‘amount’ => $amountUSD,
‘validUntil’ => date(‘c’, strtotime(‘+15 minutes’)) //汇率锁定有效期
]);
if(!$response->isSuccessful()){
throw new ForexException(“无法锁定汇率: “.$response->getError());
}
return [
‘referenceId’ => $response->referenceId,
‘lockedRate’ => $response->exchangeRate, //e.g. 84.50
‘expiryTime’ => $response->expiryTimestamp
];
}
“`
Rocket账单支付的QR码整合
Dynamic QR生成规范（符合BanglaQR标准）
“`java
// Java示例 – QR码内容生成器(BEPS标准)
public class RocketQRGenerator {
private static final String ROCKET_PREFIX = “0002010102122937”;
public String generateDynamicPayload(PaymentRequest request) {
StringBuilder qrBuilder = new StringBuilder(ROCKET_PREFIX);
// Merchant账户信息段
qrBuilder.append(“0016A000000677010111”)
.append(String.format(“%02d”, request.getMerchantId().length()))
.append(request.getMerchantId());
// Transaction动态信息段
qrBuilder.append(“0208”) // Amount字段标识符及长度固定8位
.append(String.format(“%08d”, request.getAmountInPoisha())) ;//金额转换为波沙单位
if(request.isTipEnabled()){
qrBuilder.append(“0303”)
.append(String.format(“%03d”,request.getTipPercentage()));
}
return qrBuilder.toString();
}
}
“`
移动端扫描优化技巧：
1. 尺寸控制公式：
“`
最小物理尺寸(mm) ≥ (扫描距离(cm)/10 ) × (模块数/29 )
例如:2米距离需要至少35mm×35mm的二维码
推荐纠错等级: Level Q (25%容错率)
颜色对比度: >70% (深蓝底白图案效果最佳)
“`
2.React Native集成示例：
“`javascript
import RNQRGenerator from ‘@nayuki/qrcode-generator’;
const rocketQRSettings={
errorCorrectionLevel:’Q’,
margin:4,
scale:(Dimensions.get(‘window’).width *0.7)/29 //动态适配屏幕宽度
};
{({ amount }) => (
)}
“`
Upay企业级异常处理框架
Circuit Breaker模式实现（防止级联故障）
“`go
type upayCircuitBreaker struct{
maxFailures int `default:”3″`
resetTimeout time.Duration `default:”30s”`
failureCount int
lastFailure time.Time
mutex sync.Mutex
}
func(cb *upayCircuitBreaker) Execute(req func()error){
cb.mutex.Lock()
defer cb.mutex.Unlock()
now :=time.Now()
if cb.failureCount >=cb.maxFailures && now.Sub(cb.lastFailure)