印度原生支付 API 接口文档说明

印度原生支付API接口文档说明：集成指南与最佳实践

引言：印度数字支付生态概览

随着印度数字经济的飞速发展，其本土化支付体系已成为国际企业进入该市场必须掌握的关键环节。UPI（统一支付接口）、RuPay、NetBanking等原生支付方式占据着印度电子交易的主流地位。本文作为专业的技术指南，将详细解析印度主流支付API的集成规范、技术要点与合规要求，帮助开发者高效安全地接入这一重要市场。

一、核心支付接口详解

1.1 UPI（统一支付接口）集成规范

UPI由印度国家支付公司（NPCI）开发，已成为印度最流行的实时付款系统。其API集成主要包含以下组件：

请求端点配置::

生产环境：https://api.upi.npci.org.in/v3/
沙箱环境：https://sandbox.upi.npci.org.in/v3/

Description of key parameters::

vpa（虚拟付款地址）：格式为“用户名@银行标识”
merchantId：经NPCI认证的商户唯一标识
transactionNote：交易备注信息（限制50字符）

回调处理机制::

{
  "status": "SUCCESS",
  "transactionId": "NPC123456789",
  "amount": "1500.00",
  "timestamp": "2024-01-15T14:30:00Z"
}

1.2 RuPay卡处理接口

作为印度的本土银行卡网络，RuPay的受理要求符合PCI DSS标准：

加密规范::

RSA密钥长度不低于2048位
TLS协议版本需≥1.2
PIN数据使用HSM加密传输

1.3 NetBanking网关对接

支持超过60家印度银行的网银直连：

银行代码标准化映射表
| Bank Code | Bank Name | Transaction Limit |
|———–|——————|——————-|
| HDFC001 | HDFC Bank | ₹200,000 |
| ICICI002 | ICICI Bank | ₹100,000 |
| SBI003 | State Bank of India | ₹500,000 |

二、技术实现流程

2.1身份验证与安全协议

所有API请求必须包含以下认证头：

Authorization: Bearer <jwt_token>
X-Merchant-ID: <your_merchant_id>
X-Timestamp: <unix_timestamp>
X-Signature: <hmac_sha256>

JWT令牌每24小时需刷新一次，签名生成算法如下：

import hmac 
signature = hmac.new(secret_key.encode(), message.encode(), 'sha256').hexdigest()

2.2订单创建流程

步骤分解

POST /api/v1/payments/create

{
   “orderId”: “INV20240115001”，  
   “amount”： {
        “value”：“2500.50”，  
        “currency”：“INR”
    }，
    “paymentMethods”： [“upi”，“netbanking”，“rupay”]，
    ”callbackUrl“："https://yourdomain.com/webhook"，
     ”metadata“:{
          ”customerEmail":"[email protected]"、
           ”productCode":"DIGITAL_SUBSCRIPTION"
     }
}

2 .3 Webhook配置指南

NPCI强制要求所有商户实现双向webhook验证:

必需实现的端点

GET /webhook/verify //用于初次验证  
POST /webhook/notification //接收交易状态更新

三．合规性要求与风险管理

3 .1数据本地化规定

根据《2019年个人数据保护法案》草案及RBI指令:
用户财务数据必须在6小时内同步至印境内服务器
日志记录保存期限不少于7年
跨境数据传输需经明确用户同意

3 .2限额管理策略

个人账户｜商家账户｜特殊许可账户｜
每日转账上限｜₹100,000｜₹500 ,000｜₹5 ,000 ,000
单笔最高金额│₹10 ，０００│Ｒｓ２００，０００│Ｒｓ１，０００，０００

四．错误代码解析手册

常见HTTP状态码对应关系:

400系列错误

{    
    „errorCode‟:“UPI_TIMEOUT‟,
     „localizedMsg‟:“Transaction timeout.Please retry within30 minutes.”,
      „retryable‟ :true   
}

*５XX系统级错误处理

五、高级功能与定制化集成

5.1 自动扣款（Mandate）功能实现

印度支付API支持预授权交易，适用于订阅制服务：

创建授权请求示例::

POST /api/v1/mandates/create
{
    "mandateType": "FIXED_AMOUNT",
    "amount": {
        "fixed": "999.00",
        "maximum": null
    },
    "frequency": "MONTHLY",
    "startDate": "2024-02-01",
    "endDate": "2024-12-31",
    "customerVPA": user@bankname,
}

状态管理流程::

CREATED → CUSTOMER_APPROVAL_PENDING → ACTIVE 
→ EXECUTED (每次扣款) → EXPIRED/CANCELLED

5.2 QR码支付动态生成

针对线下场景的静态与动态QR码规范：

API参数配置表
| 参数名 | 类型 | 必填 | 说明 |
|——–|——|——|——|
| qrType | string | Y | STATIC/DYNAMIC |
| amountLocked | boolean | N | DYNAMIC类型时可锁定金额 |
| expiryMinutes | integer | Y(仅DYNAMIC) | QR码有效时间 |

生成响应包含标准化的upi://pay?格式URI，符合NPCI《QR代码规范2.0》。

六、性能优化与监控建议

6 .1 API响应时间基准

根据印度数字支付基础设施特点，建议设置以下SLA目标：

关键路径（如发起交易）：P95 < 800ms
状态查询类接口：P99 < -300ms
对账文件下载: P90 < -5s （考虑到网络波动）

应部署本地边缘节点以应对国际链路延迟。主要数据中心推荐选择孟买或金奈。

6 .2可观测性指标

必须监控的核心业务指标包括:

payment_initiation_success_rate:按支付方式细分成功率
webhook_delivery_latency_p99:确保回调及时性
bank_downtime_impact:实时监测各银行系统状态

推荐使用以下维度进行仪表盘拆分:

payment_method= upi, netbanking, rupay  
bank_name = hdfc, icici, sbi  
region = north,south,east,west

七．测试环境搭建指南

7 .1沙箱账户申请流程

interviewsNPCI开发者门户完成以下步骤:

注册企业账号并提交GSTIN证明文件。
选择需要测试的支付产品模块。
获取测试用的虚拟银行账户和UPI ID列表。
下载对应的RSA密钥对用于签名验证。

7 .2模拟器工具链

官方提供的NPCI Sandbox App可在应用商店下载，其功能包括:

模拟任意成功/失败交易场景
自定义网络延迟和超时
生成完整的审计日志供合规检查

八．版本管理与迁移策略

8 .1当前活跃版本支持情况

v3.x (主流支持，至2025年12月)
├── UPI Collect: ✅ 
├── UPI Intent: ✅ 
└── RuPay EMV: ✅ 

v2.x (已弃用维护模式)
└--停止新商户接入--

所有API变更将通过官方变更日志提前6个月公告。

8 ．２向后兼容性保证

NPCI承诺对于已标记为“deprecated”的参数保持至少两个主版本的兼容窗口期。重要通知将通过注册邮箱及商户面板横幅同步推送。

九．常见问题排查清单(F A Q)

Q１：如何处理“BANK_RESPONSE_TIMEOUT”？

A１：
①首先检查[NPCI系统状态页面]确认是否为区域性故障；
②若个别用户遇到此问题，引导其切换付款方式或稍后重试；
③记录完整会话ID并提交给技术支持团队进行链路追踪；

Q２：“INVALID_VPA_FORMAT”的可能原因？

A２：
①检查是否包含空格或特殊字符；
②验证银行后缀是否正确（如@oksbi vs @sbi）；
③通过公开的VPA校验工具预先验证格式；

Q３：结算周期和手续费如何计算？

A３：
①UPI个人间转账目前零手续费；商业收款费率通常为0．3%-0

印度原生支付 API 接口文档说明