如何对接印度尼西亚支付API？开发者实战教程

5 月, 周一, 2025
deekpay
印度尼西亚支付

如何对接印度尼西亚支付API？开发者实战教程

一、印度尼西亚支付市场概况

印度尼西亚作为东南亚最大的数字经济体，其电子支付市场近年来呈现爆发式增长。根据最新数据，印尼数字支付交易额预计2025年将达到4000亿美元规模。对于希望进入印尼市场的企业而言，了解并接入当地主流支付方式至关重要。

印尼本土流行的支付方式包括：

银行转账：Mandiri、BCA、BNI等大型银行提供的实时转账
电子钱包：OVO、DANA、LinkAja等占据主导地位
便利店付款：Indomaret和Alfamart两大连锁便利店覆盖广泛
虚拟账户：众多电商平台首选的收款方式

二、前期准备工作

1. 注册公司实体与合规要求

在对接任何印尼支付API前，您需要确保：

已在印尼完成公司注册（PT PMA或本地公司）
获得央行(OJK)颁发的相关金融牌照（视业务类型而定）
PCI DSS合规认证（处理信用卡交易必需）

2. API文档获取渠道

主流印尼支付提供商都会提供完善的开发者文档：

官方开发者门户示例：

• Xendit: developer.xendit.co 

• Doku: doku.com/developer 

• Midtrans: docs.midtrans.com

建议先完整阅读API参考文档和技术规范文件。

三、技术对接详细步骤

Step1: API身份验证配置

大多数印尼支付网关采用OAuth2.0或Basic Auth认证：

# Python示例 - Xendit API认证

import requests



api_key = "your_live_secret_key"

headers = {

    "Authorization": f"Basic {api_key}",

    "Content-Type": "application/json"

}



response = requests.get(

    "https://api.xendit.co/available_virtual_account_banks", 

    headers=headers)

重要安全提示：
✔️永远不要在前端暴露API密钥
✔️使用环境变量管理敏感信息
✔️定期轮换访问凭证

Step2: Webhook设置指南

正确处理异步通知是核心环节：

// Java Spring Boot示例 - Midtrans通知处理

@PostMapping("/payment-notification")

public ResponseEntity<String> handleNotification(

    @RequestBody NotificationPayload payload,

    @RequestHeader("X-Signature") String signature) {

    

    // 1.验证签名有效性 

    if(!SignatureTool.verify(payload, signature, merchantKey)){

        return ResponseEntity.status(403).build();

    }

    

    // 2.处理业务逻辑...

}

必须实现的验证机制包括：
✅ HMAC-SHA256签名校验
✅ IP白名单过滤（常见网关IP需预先配置）
✅幂等性处理（防止重复通知导致多次记账）

Step3: SDK集成最佳实践

推荐优先使用官方SDK提高开发效率：

Node.js集成Midtrans示例:

const midtransClient = require('midtrans-client');



let snap = new midtransClient.Snap({

   isProduction : false,

   serverKey : 'YOUR_SERVER_KEY',

   clientKey : 'YOUR_CLIENT_KEY'

});



snap.createTransaction(parameter)

   .then((transaction)=>{

      console.log(transaction);

   })

各语言SDG获取地址通常位于:

/docs/sdk | /developer-tools | /integration-libraries

Step4: QRIS统一标准接入

自2023年起，所有商户必须支持QRIS互操作标准：

调用参数范例:

{

    "qr_type": "dynamic",

    "amount":150000,

    "merchant_city":"Jakarta",

    "seller_name":"YourStoreID"

}

响应结果解析重点字段:

• qr_string → Base64编码的二维码图像数据  

• expiration_time → UTC格式有效期截止时间戳   

• transaction_id → 用于后续查询的唯一标识符

四、测试与上线全流程

1️⃣沙箱环境测试要点:

测试场景	预期结果	工具推荐
金额边界值	-最小0.01IDR -最大10亿IDR成功处理	Postman Newman
并发请求	<500ms响应时间无数据竞争问题	JMeter

2️⃣生产环境检查清单:

☑️ SSL证书有效且为TLS1.3+版本
☑️ Failover机制已部署（建议至少双AZ架构）
☑️ BI规定的每日对账报表功能已验证

五．常见错误代码速查表

遇到问题时优先排查这些高频错误:

HTTP状态码	原因分析	解决方案
402 PAYMENT_REQUIRED	余额不足/限额超支	联系收单行调整限额
409 CONFLICT	重复订单号 (idempotency-key重复)	生成新的UUID作为请求标识
451 UNAVAILABLE_FOR_LEGAL_REASONS BPJSTK/KYC未完成提交完整的税务登记证明

六．性能优化建议

针对高流量场景特别注意事项:

▸批量查询接口替代单条请求 (如使用/batch_status?reference_ids=id1,id2)
▸启用长连接保持 (Keep-Alive timeout建议≥60s)
▸本地缓存静态数据 (银行列表费率表等TTL设为24h+)

七．扩展学习资源

进阶开发者可深入研究:
→《Bank Indonesia Payment System Regulation No21/2019》法规原文
→ ISO20022报文标准在清算系统中的应用
→ Tokenization方案降低PCI审计范围的技术实现

八、印尼支付API高级功能开发

1. 分阶段付款实现方案

印尼电商平台普遍支持分期付款（Cicilan），技术实现要点：

“`php
// PHP示例 – Akulaku分期接口调用
$client = new \GuzzleHttp\Client();
$response = $client->post(‘https://api.akulaku.com/v2/installment’, [
‘headers’ => [
‘X-Api-Key’ => env(‘AKULAKU_KEY’),
‘Accept’ => ‘application/json’
],
‘json’ => [
‘order_id’ => uniqid(),
‘amount’ => 5000000,
‘tenor_options’ => [3,6,12], //可选分期月数
‘customer_phone’ => ‘+62812XXXXXXX’
]
]);

//解析返回的分期选项
$plans = json_decode($response->getBody())->available_plans;
“`

关键参数说明：
– tenor_options：必须包含银行支持的期数（BCA通常为3/6/12期）
– merchant_fee：需明确显示商户承担或用户支付的利息费用

2. DANA电子钱包深度集成

DANA API特殊要求处理流程：

“`javascript
// Node.js DANA OAuth2.0授权示例
const crypto = require(‘crypto’);

function generateDanaSignature(payload, secret) {
return crypto.createHmac(‘sha256’, secret)
.update(JSON.stringify(payload))
.digest(‘hex’);
}

const authPayload = {
grant_type: “client_credentials”,
client_id: “YOUR_DANA_MERCHANT_ID”,
timestamp: new Date().toISOString()
};

const signature = generateDanaSignature(authPayload, “YOUR_SECRET”);
“`

特别注意：
• Timestamp精度需到毫秒级且与服务器时间差不超过5分钟
• redirect_url必须使用HTTPS且域名已备案在DANA商户后台

九、本地化合规增强策略

1. BPJS Kesehatan社保自动扣款

对接政府医保系统的技术规范：

|字段名|类型|验证规则|
|—|—|—|
|bpjs_number|string|13位数字+1位校验码|
|payment_month|date_format`YYYY-MM`不能晚于当前月份|

请求报文示例：
“`xml

…

0001234567890
150000

“`
重要提示：此接口仅限持有PJPAB牌照的支付机构调用

2. 增值税（VAT）实时计算

根据商品类别自动应用不同税率：

“`java
public class IndoVatCalculator {

private static final Map VAT_RATES = Map.of(
“basic_needs”, new BigDecimal(“0”), //基础食品免税
“premium_goods”, new BigDecimal(“11”), //2024年新税率
“digital_services”, new BigDecimal(“11”)
);

public Invoice calculate(Order order) {
BigDecimal rate = VAT_RATES.get(order.getGoodsType());
return new Invoice(
order.getAmount(),
order.getAmount().multiply(rate).divide(100)
);
} }
“`

税务规则注意点：
→奢侈品(Luxury Goods)需额外加征10%-40%附加税
→跨境数字服务适用逆向征税机制(RCM)

十．监控与灾备方案设计

推荐部署的监控指标清单：

*Prometheus配置片段*
“`
scrape_configs:
– job_name:’indonesia_payment’
metrics_path:’/actuator/prometheus’
static_configs:
targets:[‘gateway-service’]

rule_files:
– rules/payment_alerts.yml #预定义规则包括:
#api_error_rate >5%
#settlement_delay >4h
“`

多活架构建议采用：
“`
雅加达主中心 + Batam灾备中心双部署
⇒ MySQL Group Replication保持数据同步
⇒ AWS Global Accelerator实现智能路由切换

当检测到以下情况时自动触发failover：
✖ BCA银行通道连续失败超阈值
✖ Telkomsel骨干网延迟＞800ms持续15分钟以上

十一．开发者常见问题FAQ

Q1:为什么虚拟账户收款后状态未更新？
►99%因为未正确处理DOKU的POST通知，检查Content-Type应为`application/x-www-form-urlencoded`

Q2:如何获取BCA银行的Corporate ID？
►需要向BCA提交SKDP公司注册文件，审批周期通常7工作日

Q3:OVO支付报错”USER_BLOCKED”怎么解决?
►表明终端用户账号异常，引导客户联系OVO客服热线1500965

十二．版本升级注意事项

2024年重大变更提醒：
◉ QRIS标准升级至v2.1 (旧版将于6月停用)
◉ BI强制要求所有交易添加UAIC唯一审计标识码
◉ GoPay将逐步迁移至LinkAja统一平台

建议订阅各支付提供商的技术公告邮件列表，及时获取更新动态。通过遵循本指南的系统性方法，开发者可以高效完成印尼支付生态的集成工作。

如何对接印度尼西亚支付API？开发者实战教程