SoPay 文档中心

简体中文

English

简体中文

English

Appearance

印度支付 API（India Payment API） ​

SoPay 印度支付 API 面向需要接入 印度支付渠道、印度支付通道 和 INR 代收代付能力的商户，提供 Payin、Payout、商户钱包、异步回调和 RSA2 签名能力。

商户只需对接 SoPay 平台 API，无需直接处理底层支付通道协议。国家与币种由商户号自动识别，印度商户固定为 IN / INR，创建订单时无需传 countryCode、currency。

环境与地址 ​

环境API Base（示例，以运维下发为准）
生产https://api.soranopro.com
沙盒https://sandbox-api.soranopro.com

完整路径示例：POST {API_BASE}/api/v1/merchant/payin/create

  • 生产环境仅 HTTPS，建议 TLS 1.2+
  • 沙盒与生产 商户号、密钥、钱包 相互独立
  • 若开启 IP 白名单，请将调用方公网 IP 提交运营配置

商户身份与密钥 ​

项目说明
商户号 merchantNo开户后分配，Header X-Merchant-No
商户 RSA 密钥对商户私钥签名请求；公钥提交给平台
平台 RSA 公钥验证平台异步回调签名
国家/币种商户号绑定，印度为 IN / INR

鉴权与签名详见 签名与商户 API 规范。

请求头（商户 API） ​

Header必填说明
Content-TypePOST 必填application/json
X-Merchant-No是商户号
X-Timestamp是Unix 秒级时间戳
X-Nonce是唯一随机串
X-Sign是RSA2 Base64 签名

API 一览 ​

能力MethodPath
创建代收POST/api/v1/merchant/payin/create
查询代收GET/api/v1/merchant/payin/query
创建代付POST/api/v1/merchant/payout/create
查询代付GET/api/v1/merchant/payout/query
商户钱包GET/api/v1/merchant/wallet
钱包流水GET/api/v1/merchant/wallet/transactions

业务流程概览 ​

代收（Payin） ​

  1. 调用 创建代收，返回 payUrl，部分通道可能同时返回 payQr（UPI intent）
  2. 引导用户打开 payUrl 或 UPI intent 完成支付
  3. 成功后订单变为 completed，钱包增加 netAmount
  4. 平台向订单 notifyUrl 或商户默认 callbackUrl 推送终态回调

代付（Payout） ​

  1. 调用 创建代付，冻结 netAmount = amount + feeAmount
  2. 平台按银行账号或 UPI/VPA 信息发起出款
  3. 终态后回调至 notifyUrl 或商户默认 callbackUrl

印度业务要点 ​

项说明
币种INR，金额最多 2 位小数
代收默认在线收银，返回 payUrl；UPI intent 可能在 payQr 返回
代收查询支持普通查单，也支持 UTR 查询和 UPI 查询
代付银行账户payee_account + payee_realname + extJson.ifsc
代付 UPI/VPAextJson.accountType=vpa，payee_account 或 extJson.vpa 填 UPI 地址
银行编码AIPay 印度通道不依赖 bankCode / receiverBankCode，可不传
扩展字段使用 extJson（对象），不要使用 metadata

手续费说明 ​

类型计费商户侧
代收amount × rate + fixed入账 netAmount = amount - feeAmount
代付amount × rate + fixed冻结 netAmount = amount + feeAmount

代收交易 ​

印度代收为 在线收银 / UPI 收银，创建后返回支付引导信息。

创建代收订单 ​

项目值
MethodPOST
Path/api/v1/merchant/payin/create

请求体

字段类型必填说明
merchantOrderNostring是商户订单号，商户内唯一
amountstring/number是INR 金额，最多 2 位小数
notifyUrlstring否为空则使用商户默认 callbackUrl
remarkstring否订单备注
payer_realnamestring建议付款人姓名
payer_mobilestring建议付款人手机号
payer_emailstring建议付款人邮箱
bankCode / bankNamestring否AIPay 印度通道可不传
extJsonobject否上游扩展字段

extJson（代收）

键说明
firstName / lastName指定上游姓名字段；未传时使用 payer_realname
mobile指定上游手机号；未传时使用 payer_mobile
email指定上游邮箱；未传时使用 payer_email
payType特殊配置时覆盖上游支付模式；印度默认 1

请求示例

bash
BODY='{
  "merchantOrderNo": "INPAYIN20260702001",
  "amount": "1000.00",
  "notifyUrl": "https://merchant.example.com/in/payin/notify",
  "remark": "pay",
  "payer_realname": "Raj Kumar",
  "payer_mobile": "9123456789",
  "payer_email": "raj@example.com",
  "extJson": {}
}'

curl -X POST "${API_BASE}/api/v1/merchant/payin/create" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-No: M100" \
  -H "X-Timestamp: 1783008000" \
  -H "X-Nonce: ${NONCE}" \
  -H "X-Sign: ${SIGN}" \
  -d "${BODY}"

响应示例

json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "orderNo": "PI20260702110000888888",
    "merchantOrderNo": "INPAYIN20260702001",
    "amount": "1000.00",
    "feeAmount": "10.00",
    "netAmount": "990.00",
    "status": "processing",
    "payUrl": "https://pay.example.com/checkout/abc123",
    "payQr": "upi://pay?...",
    "createdAt": 1783008000
  }
}

查询代收订单 ​

项目值
MethodGET
Path/api/v1/merchant/payin/query

普通查单参数（二选一）：

Query必填说明
orderNo二选一平台订单号
merchantOrderNo二选一商户订单号

AIPay 印度通道还支持在同一个查询接口中选择上游查询方式：

Query说明
queryType=utr + utr=...按 UTR 查询支付状态；若 UTR 已绑定当前订单，平台会更新订单状态
queryType=upi + upi=...查询 UPI 是否属于当前通道；该查询不代表订单已支付

示例：

bash
curl "${API_BASE}/api/v1/merchant/payin/query?orderNo=PI20260702110000888888&queryType=utr&utr=123456789012" \
  -H "X-Merchant-No: M100" \
  -H "X-Timestamp: 1783008300" \
  -H "X-Nonce: ${NONCE}" \
  -H "X-Sign: ${SIGN}"

代收订单结果通知 ​

验签与重试见 异步回调接入指南。

终态 completed / failed / timeout 时 POST 至 notifyUrl 或商户默认 callbackUrl。

json
{
  "orderType": "payin",
  "orderNo": "PI20260702110000888888",
  "merchantOrderNo": "INPAYIN20260702001",
  "status": "completed",
  "amount": "1000.00",
  "feeAmount": "10.00",
  "netAmount": "990.00",
  "completedAt": 1783008600
}

商户应答 HTTP 200 + Body OK。

代付交易 ​

印度代付支持 银行账户出款，并可按通道能力使用 UPI/VPA 出款。

创建代付订单 ​

项目值
MethodPOST
Path/api/v1/merchant/payout/create

请求体

字段类型必填说明
merchantOrderNostring是商户订单号，商户内唯一
amountstring/number是INR 金额，最多 2 位小数
payee_realnamestring是收款人姓名
payee_accountstring是银行账号或 UPI 地址
payee_mobilestring建议收款人手机号
payee_emailstring否收款人邮箱
bankNamestring否银行名称，未传时默认 Bank
bankCode / receiverBankCodestring否AIPay 印度通道可不传
notifyUrlstring否为空则用商户默认 callbackUrl
remarkstring否备注
extJsonobject否见下表

extJson（代付）

键必填说明
ifsc银行账户模式必填11 位 IFSC，如 HDFC0001234
accountType否bank_account（默认）或 vpa
vpa / upiUPI 模式可选UPI 地址；未传时使用 payee_account
address否收款人地址

银行账户请求示例

bash
BODY='{
  "merchantOrderNo": "INPAYOUT20260702001",
  "amount": "5000.00",
  "bankName": "HDFC Bank",
  "payee_realname": "Priya Sharma",
  "payee_account": "123456789012",
  "payee_mobile": "9876543210",
  "payee_email": "priya@example.com",
  "notifyUrl": "https://merchant.example.com/in/payout/notify",
  "remark": "payout",
  "extJson": {
    "ifsc": "HDFC0001234"
  }
}'

UPI/VPA 请求示例

json
{
  "merchantOrderNo": "INPAYOUT20260702002",
  "amount": "500.00",
  "payee_realname": "Priya Sharma",
  "payee_account": "priya@upi",
  "payee_mobile": "9876543210",
  "notifyUrl": "https://merchant.example.com/in/payout/notify",
  "extJson": {
    "accountType": "vpa"
  }
}

响应示例

json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "orderNo": "PO20260702120000999999",
    "merchantOrderNo": "INPAYOUT20260702001",
    "amount": "5000.00",
    "feeAmount": "50.00",
    "netAmount": "5050.00",
    "status": "processing",
    "payoutMethod": "BANK_TRANSFER",
    "createdAt": 1783011600
  }
}

查询代付订单 ​

项目值
MethodGET
Path/api/v1/merchant/payout/query

Query（二选一）：orderNo 或 merchantOrderNo

json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "orderNo": "PO20260702120000999999",
    "merchantOrderNo": "INPAYOUT20260702001",
    "status": "completed",
    "amount": "5000.00",
    "feeAmount": "50.00",
    "netAmount": "5050.00",
    "completedAt": 1783012200
  }
}

代付订单结果通知 ​

验签与重试见 异步回调接入指南。

终态 completed / failed / timeout 时 POST 至 notifyUrl 或商户默认 callbackUrl。

json
{
  "orderType": "payout",
  "orderNo": "PO20260702120000999999",
  "merchantOrderNo": "INPAYOUT20260702001",
  "status": "completed",
  "amount": "5000.00",
  "feeAmount": "50.00",
  "netAmount": "5050.00",
  "completedAt": 1783012200
}

商户应答：HTTP 200 + Body OK。

通用查询接口 ​

商户余额查询 ​

项目值
MethodGET
Path/api/v1/merchant/wallet
json
{
  "code": 0,
  "data": {
    "countryCode": "IN",
    "currency": "INR",
    "balance": "100000.00",
    "pendingBalance": "0.00",
    "frozenBalance": "5050.00",
    "status": 1
  }
}

钱包流水 ​

项目值
MethodGET
Path/api/v1/merchant/wallet/transactions

Query：page（默认 1）、pageSize（默认 20，最大 100）

附录 ​

订单状态枚举 ​

status终态说明
created否已创建
processing否处理中
partial_paid否部分支付
completed是成功
failed是失败
timeout是超时
cancelled是已取消

代付出款方式 ​

payoutMethod说明
BANK_TRANSFER银行账户 / UPI 出款
PROMPTPAY未填银行信息时的历史默认值

extJson 字段汇总 ​

代收：firstName、lastName、mobile、email、payType

代收查询：queryType=utr&utr=... 或 queryType=upi&upi=... 使用 Query 参数传递

代付：ifsc、accountType、vpa、upi、address

错误码说明 ​

统一响应：{ "code": 0, "msg": "ok", "data": ... }，以 code 判断成败。

msg说明
merchant balance insufficientINR 余额不足
merchant order no already exists订单号重复
signature invalid验签失败
aipay bank_account payout requires extJson.ifsc银行账户代付缺少 IFSC
50210 等上游参数、限额或通道错误

创建超时请先 查询 再决定是否重试；代付失败请换新 merchantOrderNo。

相关阅读 ​

最后更新于:

基于 MIT 许可证发布。

Copyright © 2024–2026 SoPay

2-1-2 Nihonbashi-Hongokucho,Chuo-ku,Tokyo