印尼支付通道API接入教程

1. 准备工作

在开始接入印尼支付通道API前，请确保您已完成以下准备：

1. 注册商户账号：与目标支付服务提供商完成签约
2. 获取API密钥：从支付平台获取Merchant ID、API Key和Secret Key
3. 确定环境：
   • 沙箱环境(测试)：用于开发和测试
   • 生产环境：正式上线使用

2. API基础信息

通用参数

• API地址：
  • 测试环境：https://api-sandbox.payment-provider.co.id
  • 生产环境：https://api.payment-provider.co.id
• Content-Type: application/json
• Authorization: Bearer {your_api_key}

HTTP状态码

• 200: Success (成功)
• 400: Bad Request (请求参数错误)
• 401: Unauthorized (认证失败)
• 500: Internal Server Error (服务器错误)

3. API接口说明

a) OVO电子钱包支付

// OVO支付请求示例(POST /v1/payments/ovo)

{

    "merchant_order_id": "ORDER123456",

    "amount": "100000",

    "phone_number": "+6281234567890",

    "description": "Pembelian Produk A",

    "callback_url": "https://yourwebsite.com/callback"

}



// OVO响应示例(成功)

{

    "status": {

        "code": "",

        // ...其他字段...

b) DANA电子钱包集成步骤:

1. 初始化SDK
2. 创建订单
3. 处理回调

c) GoPay接入要点:

GoPayApiClient client = new GoPayApiClient.Builder()

                .setEnv(Environment.SANDBOX)

                .setCredentials("your-client-id", 

                              // ...

d) Mandiri银行转账(Bank Transfer)

POST /v1/payments/bank-transfer/mandiri HTTP/1.

Host: api.payment-provider.co.id  

Authorization: Bearer your_api_key_here  



{  

   // ...JSON请求体...

}

e) BCA虚拟账户(Virtual Account)

PHP代码示例:

$params = [

 'customer_name' => 'John Doe',

 'expiry_date' => date('Y-m-d H:i:s', strtotime('+24 hours')),

];

$response = $client->post('/va/bca', $params);

4. Webhook配置指南:

Field	Description
URL	https://yoursite.com/webhooks
Events	payment.success, payment.failed

5. SDK下载链接:
Android SDK | iOS SDK

6. Q&A常见问题:

Q: SSL证书要求?
A: TLS必须≥v.

Q:如何验证签名?

Python验签代码片段:

def verify_signature(payload, signature):

 expected_sign = hmac.new(

     key=secret.encode(),

     msg=payload.encode(),...).hexdigest()

 return expected_sign == signature 

7. Support联系方式:
Email [email protected] +622150012345

8. 支付流程详细说明

a) 标准支付流程时序图

商户系统 -> 支付平台: 1.创建订单(API调用)

支付平台 --> 商户系统: 返回支付页面URL/QR码

客户 -> 支付平台: 2.完成付款

支付平台 -> 商户系统:3.Webhook通知(异步)

商户系统 ->4.查询订单状态(可选)

b) QRIS统一扫码支付集成

请求示例：

POST /v1/payments/qris

{

    "amount": "50000",

    "merchant_order_id": "ORD-20231115-001",

    "description": "Pembelian Makanan", 

    "expiry_minutes":30,

    // ...其他参数...

}

响应处理：

//成功响应示例：

{

   qr_code_url:"https://.../qrcode.png",

   deep_link:"gopay://...", 

   status:"PENDING"

}

9.各通道限额表（IDR）

Channel	Min Amount	Max Amount
OVO	10,000	10,000,000
DANA	5,000	5,000,000
GoPay	–	–

10.SDK初始化配置（Android）

val config = PaymentConfig.Builder()

            .setAppKey("your_app_key")

            .setPublicKey("-----BEGIN PUBLIC KEY-----\n...")

            .setSandboxMode(true) //生产环境设为false  

            .build() 



PaymentSDK.init(context，config)

11.iOS Swift集成要点

func application(_ application：UIApplication，

                didFinishLaunchingWithOptions...) -> Bool {

    

PaymentSDK.setup(

        merchantId："YOUR_MID"，

        secretKey："YOUR_SECRET") 



return true }

12. 错误代码对照表

常见错误处理：

E1001 - Invalid signature (签名无效)

解决方案：

1.检查时间戳是否在±15分钟内  

2.重新生成签名密钥  



E2003 - Insufficient balance (余额不足)  

引导用户充值或更换付款方式  

13. 测试卡号列表

银行转账测试账号：

BCA Virtual Account:

虚拟账号格式：39358+随机数8位  

PIN码使用：123456  



Mandiri Virtual Account:

虚拟账号格式：70012+随机数7位   

验证码固定为888999   

14. 性能优化建议

批量查询接口：

GET /v1/orders/batch?order_ids=ID1，ID2，ID3...

最多支持50个订单同时查询  

Response压缩启用GZIP可减少70%流量 

15. 合规要求

必须实现的商家后台功能：
✓交易记录保存至少5年
✓退款API必须实现幂等性控制
✓敏感数据加密存储(AES-256+)

16. 高级功能接入指南

a)分账到账配置:

Java代码示例：

               .setReceiverType("MERCHANT") 

               .setPercentage(new BigDecimal("70"));



List<SplitRule> rules = Arrays.asList(rule); request.setSplitRules(rules);

b)定期扣款（Recurring）:

需要额外申请权限并提交以下材料：

• SSM营业执照副本
• RBI备案证明复印件

17. 安全最佳实践

✔️关键日志脱敏处理（如手机号显示为62889）
✔️每季度轮换API密钥
✔️使用IP白名单限制访问来源

18. Support升级渠道：

紧急技术问题联系表格:

问题类型：[ ]生产中断 [ ]资金异常 [ ]安全漏洞

优先级选择：🔥Critical ⏳High ⚠Normal

附件上传截图/logs（最大20MB）

19. 多语言错误消息处理

印尼语本地化示例

{

  "error": {

    "code": "E2005",

    "message": {

      "en": "Payment expired", 

      "id": "Pembayaran kadaluarsa",

      "cn": "支付已过期"

    }

  }

}

20. Tokenization API (卡片/钱包令牌化)

安全存储支付方式流程：

1. 前端调用SDK获取token
2. 传送token至商户后端
3. 商户服务器通过API验证token

// React Native示例代码

const { token, error } = await PaymentSDK.tokenize({

   paymentMethod: 'credit_card',

   cardNumber: '4242424242424242', 

   expiryMonth: '12',

   // ...其他参数...

});

21. PCI DSS合规指南

敏感数据处理要求：

• ✅允许：传输令牌(token)
• ❌禁止：原始卡号CVV存储
• 🔐必须：TLS1.2+加密通信

22. Webhook安全验证步骤

Node.js中间件示例：

app.post('/webhook', (req, res) => {

  

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

 const rawBody = JSON.stringify(req.body);

 

 if(!verifySignature(signature，rawBody)){

 return res.status(403).send('Invalid signature');

 }



 //处理业务逻辑... 



});

23 .对账文件自动下载

SFTP配置信息：

参数	值
Host	recon.payment-provider.co.id
端口	22022
用户名	merchant_[your_id]
每日生成时间	雅加达时间03:00 AM

文件命名格式：
RECON_{YYYYMMDD}_{MERCHANTID}.csv

24 .移动端UI定制选项

Android XML自定义属性：

<paymentButton  

 app:buttonColor="#FF6200EE"  

 app:textSize="16sp"   

 app:cornerRadius="8dp" />

iOS SwiftUI主题配置:

 primaryColor:.orange,

 font:.systemFont(ofSize16))

25. 国别化特殊要求

印尼央行(Bank Indonesia)规定:

• QRIS交易必须显示商家名称和位置信息
• DANA支付需要额外用户身份证校验(KYC)

26. 汇率结算说明

多币种处理规则（当订单非IDR时）:

最终结算金额=订单金额×当日BI中间汇率+2%货币转换费  

结算周期:T+3工作日(T为交易日)

27. 调试工具包下载

包含以下资源：
🔧 Postman测试集合(含预置环境变量)
📱 Xcode/Android Studio模拟器配置文件
📄 PDF版完整错误代码手册

28. 大额交易特别流程

单笔超过50百万IDR的交易需要:
1️⃣人工审核触发条件
2️⃣短信OTP二次验证
3️⃣填写付款用途说明

29．性能基准测试数据

API响应时间承诺(SLA):
||沙箱环境|生产环境|
|—|—|—|
平均响应|<800ms|<500ms
99百分位|<1s <750ms

30．弃用接口列表(2024年起失效)

⚠️即将停用的旧版接口：
• /v0/createOrder →改用/v1/payments
• Basic Auth认证 →全面切换Bearer Token