简介
OnionPay 提供安全的海外本地化支付服务,宗旨是让客户的本地化支付更轻松。
客户在自己的网站或APP内集成 OnionPay 的支付产品,可以实现在线下和线上场景的收放款服务。OnionPay 提供涵盖全球范围内多个国家的包括钱包、借记卡、信用卡、网银和UPI在内的200多种支付方式的收放款服务。同时OnionPay还提供了个性化的服务产品。
接入指引
商户接入流程概述
- 商户注册
商户在 OnionPay 官网提交相关资料,完成注册后等待 OnionPay 准入审核。
- 获取参数
商户可从商户自服务系统获取交易所需要的相关生产参数,包括应用ID、应用密钥。
- 技术联调
由商务人员创建联调对接群,开展技术对接。
- 上线申请
联调完成后,向我司对接人员提供联调成功的订单信息,我司校验通过之后,完成生产环境开通。
- 生产交易
生产环境正式开展交易,并进行日常维护。
概述
此文档描述了 OnionPay 现阶段所支持的接口与能力。
接入准备
在接入OnionPay API接口时,你需要了解并获取以下内容:
名词说明
名称 | 描述 |
---|---|
应用号 | 每个商户都会有唯一的应用ID。 |
应用密钥 | 由 OnionPay 为每个应用生成应用密钥(32位随机字符串),用于发起支付请求、代付请求时进行签名使用。见签名机制。 |
签名值 | 在商户与 OnionPay 进行接口调用时,为了保证数据在网络传输过程中不被抓包篡改, OnionPay 通过相应的逻辑规则,使用sha256的方式,对业务参数进行计算,可生成唯一的字符串,此字符串为签名值 |
pmId | 功能ID |
extInfo | 补充信息参数,如果在支付\代付接口调用时,对应的pmId,上游需要一些付款者的信息才能完成支付时,商户可通过此字段传入对应的补充信息,可跳过补充信息页面。否则OnionPay会返回跳转到补充信息页面的链接 |
请求地址 | 是指由 OnionPay 提供API服务的网关地址。 |
请求参数 | 是指商户系统调用 OnionPay 支付系统API时,发送至 OnionPay 系统时的参数。 |
返回参数 | 是指商户系统调用 OnionPay 支付系统API后,由OnionPay系统返回给商户的参数。 |
OnionPay API接口 | 是指 OnionPay 提供的可通过互联网通信技术,进行信息传递的接口,商户可根据调用方式进行调用。 |
调用方式
请求结构
通过向 OnionPay API的服务端地址发送HTTP POST请求,并按照请求结构 在HTTP body中加入相应请求参数来完成,OnionPay 系统根据请求参数 来响应返回参数 。
通信协议
为了更高的安全性,OnionPay API接口仅支持通过HTTPS通道进行请求通信。 在调用 OnionPay 系统API时, 需要遵循以下安全要求:
- 所有的请求必须使用SSL,否则请求将被拒绝
- 仅支持 TLS 1.2 or TLS 1.1, SSLv3 and TLS 1.0 不被支持
- 商户系统与 OnionPay 系统通信,使用签名验证来确保通信信息完整及通信安全,见(签名机制)
请求方法
基于HTTP协议,商户系统使用POST方式发送请求到 OnionPay API接口。
字符编码
请求及返回结果都使用UTF-8字符集进行编码。
参数格式
请求参数及返回参数均使用JSON格式。
返回参数
字段 | 名称 | 说明 |
---|---|---|
code | 状态码 | http状态码,此字段值只表明接口请求情况,不能说明业务参数无异常 |
msg | 状态描述 | 接口调用结果描述 |
timestamp | 当前时间串 | 当前的时间串 |
data | 业务返回值 | 描述业务调用情况的返回值,具体请参照业务接口中每个接口的data 值 |
通知机制
通知分为两种通知方式,因同步回调可能出现用户模拟操作,或在同步通知未进行跳转时,用户手动关闭浏览器等不可控情况,导致商户造成损失,我们强烈建议商户以异步通知结果来确认订单的支付结果。
如,商户的同步通知地址为:
https://www.example.com/pay/succ/orderno
则在支付成功时,OnionPay 会将用户的浏览器跳转至(此处为方便观看,实际没有换行):
https://www.example.com/pay/succ/orderno?amount=12.01&createTime=2019-01-09 14:53:05¤cy=USD&merTransNo=mtn8888888888&processAmount=170181.70&processCurrency=INR&sign=f99b64ecd3ce69c8683df713163cbf90b4bfd710a0d66eb95ab301dce9363215&transNo=201901091453055080016630&transStatus=success&updateTime=2019-01-09 14:54:00
实际跳转地址为(此处为方便观看,实际没有换行):
https://www.example.com/pay/succ/orderno?amount=12.01&createTime=2019-01-09%2014:53:05¤cy=USD&merTransNo=mtn8888888888&processAmount=170181.70&processCurrency=INR&sign=f99b64ecd3ce69c8683df713163cbf90b4bfd710a0d66eb95ab301dce9363215&transNo=201901091453055080016630&transStatus=success&updateTime=2019-01-09%2014:54:00
- 同步回调
在用户支付成功,或者取消支付时,OnionPay会将消费者的浏览器重定向到商户提供的returnurl
上,并携带相关参数。
同步回调采用get方式跳转,相应的拼接参数,会对每个参数的值进行编码为UTF-8的URLencode处理,随后进行跳转。
- 异步回调
OnionPay会将消费者支付结果的消息通过服务器端发送到商户提供的notifyurl
上,并携带相关参数,以post形式提交。商户需要对结果信息进行签名验证,以防止伪造的通知信息;且必须对返回结果中的订单状态做判断,以确定订单状态。
签名机制
假设调用接口时,需要传递的参数如下:
{
"amount": "10",
"appId": "4189b620f93b48c5904210ff47bb8936",
"currency": "INR",
"merTransNo": "demo-1576735973586",
"notifyUrl": "https://example.com/notifyurl",
"returnUrl": "https://example.com/returnurl",
"version": "1.1"
}
对应的请求参数为:
{
"amount": "10",
"appId": "4189b620f93b48c5904210ff47bb8936",
"currency": "INR",
"merTransNo": "demo-1576735973586",
"notifyUrl": "https://example.com/notifyurl",
"returnUrl": "https://example.com/returnurl",
"sign": "ee2406f9713f9cc234a4e2bb176b1968c500455866e0509a86896264c38dbd20",
"version": "1.1"
}
商户在调用 OnionPay API接口时,需将请求参数中的业务参数,按照
OnionPay
约定好的形式,获取到对应的签名字符串
,并作为请求参数sign传递给OnionPay。
OnionPay进行返回参数
组装时,也会按照此规则进行签名,并传递签名值。因不同的业务接口可能需要参与签名的字段不同,具体请参照业务接口中,各个接口的具体说明。
获取签名字符串:
请求参数json中的业务信息,按照key的Unicode进行排序。然后将参数以 key1=value1&key2=value2&key3=value3
的形式拼接,最后将商户key
或应用key
(不同的接口,签名时使用的key可能不相同,具体接口有说明)拼接至字符串最后,key值为key
。我们暂且称拼接好的字符串为originStr
将originStr
转化为UTF-8
的byte数组后,使用sha256
算法进行编码,再将编码后的数组转码为16进制的字符串。
举例说明
统一下单接口需要传递的请求参数:
{
"amount": "10",
"appId": "4189b620f93b48c5904210ff47bb8936",
"country": "IN",
"currency": "INR",
"merTransNo": "demo-1576735973586",
"notifyUrl": "https://example.com/notifyurl",
"returnUrl": "https://example.com/returnurl",
"sign": "ee2406f9713f9cc234a4e2bb176b1968c500455866e0509a86896264c38dbd20",
"version": "1.1"
}
对于以上需要传送的请求参数,Linux下可通过此方式进行请求(商户可通过不同的开发语言进行开发,后续会补上常用的开发语言的测试Demo):
curl -X POST --header'Content-Type: application/json'--header'Accept: text/html'-d'{
"amount": "10",
"appId": "4189b620f93b48c5904210ff47bb8936",
"currency": "INR",
"merTransNo": "demo-1576735973586",
"notifyUrl": "https://example.com/notifyurl",
"returnUrl": "https://example.com/returnurl",
"sign": "6e6832ee24d784ad09987590a3b7085c2acf65f7e127e87176c63cec0cafe93f",
"version": "1.1"
}
''https://gateway.onion-pay.com/pg/dk/order/create'
对于以上参数,OnionPay 接口会返回内容为:
{
"data": {
"amount": "10",
"currency": "INR",
"doing": "redirect",
"merTransNo": "demo-1576735973586",
"message": "success",
"resultCode": "0000",
"sign": "e28a04a3bcb0dba92d8e7e8d9cfa0c4b6069430f313ae166cbe8b447c65e8f9a",
"tradeNo": "20191219141556118010479493",
"url": "https://onion-pay.com/checkout/b2fda22f77d94373b6123b21a144272e"
},
"code": "200",
"msg": "OK",
"timestamp": "1576736156349"
}
- 本文档中的返回示例为了便于用户查看,做了格式化处理,实际返回结果没有进行换行、缩进等处理。- 下面,我们以统一下单接口举例说明。
SDK下载
Java SDK
Php SDK
C# SDK
API接入文档
收款
业务流程介绍
此接口允许商户通过后端服务器,向 OnionPay 发起支付请求。OnionPay 会根据商户请求做出相应响应;并提示商户下步操作方式。
支付接口传递相关信息,发起支付请求,此时不需要传送支付功能编号(PMID)。
印度 UPI 接入指引
UPI支付流程
- 用户选择使用 UPI 支付,并在收银台上输入 UPI 账号;
- 系统向该 UPI 账号发送交易订单信息;
- 用户主动打开/登录 UPI 客户端,查看订单信息,并完成支付。
支付接口
此接口允许商户通过后端服务器,向OnionPay发起支付请求。OnionPay会根据商户请求做出相应响应;并提示商户下步操作方式。
版本号
1.1
请求地址
- 生产环境:
https://gateway.onion-pay.com/pg/dk/order/create
- 测试环境:
https://gateway-sandbox.onion-pay.com/pg/dk/order/create
请求参数
{
"amount": "10",
"appId": "4189b620f93b48c5904210ff47bb8936",
"country": "IN",
"currency": "INR",
"merTransNo": "demo-1576735973586",
"notifyUrl": "https://example.com/notifyurl",
"returnUrl": "https://example.com/returnurl",
"sign": "ee2406f9713f9cc234a4e2bb176b1968c500455866e0509a86896264c38dbd20",
"version": "1.1"
}
下列参数中,要求的填写位数为字符的长度。
字段 | 说明 |
---|---|
version接口版本 |
当前版本1.1 |
amount订单金额 必填1-9位,保留2位小数 |
订单金额请使用字符串方式表示 |
appId应用号 必填 |
此字段在商户申请应用时,由OnionPay生成 |
country国家代码 选填2位 |
ISO3166-2 标准如使用此字段,且符合跳转OnionPay到收银台情况下,则优先显示此国家的常用支付列表,参见国家币种表 |
currency金额币种 必填3位 |
国际统一币种简称,表示amount 金额的币种,参照国家币种表 |
description订单描述 选填1-80位 |
订单的标题,有些场景如果消费者看到订单信息,可能会展示此字段内容 |
goodsInfo商品信息 选填1-1024位 |
商品信息详情,格式为:商品名称,商品单价,商品数量,商品总额。例:Item1,1000.00,2,2000.00;Item2,1500.00,2,3000.00 |
merTransNo商户订单号 必填1-50位 |
商户自行生成的订单号,建议商户保证唯一性,OnionPay不做唯一性验证 |
payerEmail购买者电子邮箱 选填1-80位 |
购买者电子邮箱地址,必须是有效的 |
payerMobile购买者手机号 选填1-20位 |
购买者的手机号,必须是有效的 |
payerName购买者姓名 选填1-80位 |
购买者完整姓名 |
prodName产品名称 选填 |
此字段由兼容其它支付公司接口,无实际意义 |
pmId支付功能编号 选填 |
功能Id,在调用支付接口时,如果传入此字段,则可以直接请求上游,否则返回跳转到收银台页面的链接, 可选参数(不区分大小写)。 |
notifyUrl异步通知地址 必填1-150位 |
订单在支付成功时,OnionPay会通过后台调用此url通知商户,通知机制请参照通知机制 |
returnUrl同步通知地址 必填1-150位 |
订单支付完毕时,如果上游支持同步跳转,OnionPay会将用户的页面跳转到此url上 |
userId用户Id 选填1-64位 |
如使用此字段,OnionPay的同步/异步通知、订单查询接口将原样返回该字段值 |
merCustomize商户自定义 选填1-255位 |
如使用此字段,OnionPay的同步/异步通知、订单查询接口将原样返回该字段值 |
extInfo扩充参数信息 选填 |
此参数为JSON格式,印度支付具体的参数列表需参考对应的extInfo列表;
巴西支付需要传用户的 document (即用户的CPF)信息,格式如下: "extInfo": { "document": "12345678912" } |
sign签名 必填 |
根据其他参数,按照签名机制,计算此字段值,此处使用应用密钥来计算签名 |
pmId参数(不区分大小写)
pmId | 说明 |
---|---|
UPI | UPI支付 |
Wallet | wallet |
Netbanking | Netbanking |
Card | Card |
data值
当业务处理成功时:
{
"data": {
"amount": "10",
"currency": "INR",
"doing": "redirect",
"merTransNo": "demo-1576735973586",
"message": "success",
"resultCode": "0000",
"sign": "e28a04a3bcb0dba92d8e7e8d9cfa0c4b6069430f313ae166cbe8b447c65e8f9a",
"tradeNo": "20191219141556118010479493",
"url": "https://onion-pay.com/checkout/b2fda22f77d94373b6123b21a144272ed"
},
"code": "200",
"msg": "OK",
"timestamp": "1576736156349"
}
当业务处理失败时:
{
"msg": "OK",
"code": "200",
"data": {
"message": "currency is required",
"resultCode": "400"
},
"timestamp": "1576737442774"
}
当服务器响应失败时:
{
"msg": "Internal Server Error",
"code": "500",
"timestamp": "1576737487259"
}
字段 | 说明 | |
---|---|---|
resultCode统一下单码 |
当统一下单码 为0000 时,表明下单成功,具体业务码,请参照统一下单码表 |
|
message下单码描述 |
当下单码描述 为success 时,表明下单成功,具体业务码,请参照统一下单码表 |
|
当下单码描述 为success ,或统一下单码 为0000 时,才会出现以下内容
|
||
amount订单金额 |
源订单金额 | |
currency订单币种 |
源订单币种 | |
merTransNo商户订单号 |
商户订单号 | |
tradeNo订单号 |
OnionPay的平台订单号 | |
processAmount交易处理金额 |
真实的订单处理额度,如amount为美元时,processAmount是真实支付时对应的人民币的价格 | |
processCurrency交易处理币种 |
消费者在真实付款时,使用的币种 | |
doing处理方式 |
请参照处理方式,根据处理方式,进行数据处理 | |
url处理地址 |
如果doing 为redirect ,则商户可直接将消费者网页重定向到此地址上 |
|
sign签名值 |
请参考签名机制;签名业务字段只取data 中的字段数据作为业务参数 |
通知参数
通用参数如下:
字段 | 说明 |
---|---|
transNo交易流水ID |
OnionPay平台交易流水号( 同支付接口返回的tradeNo ) |
merTransNo商户订单号 |
商户生成的订单号 |
currency币种 |
源订单的币种 |
amount金额 |
源订单金额 |
processCurrency处理币种 |
用户实际支付时使用的币种 |
processAmount处理金额 |
用户实际支付金额 |
transStatus订单状态 |
详见订单状态 |
createTime创建时间 |
订单创建时间(交易发生地时区) |
updateTime最后处理时间 |
最后处理时间 (交易发生地时区) |
payerName付款人姓名 |
如果OnionPay能确定此参数时则返回 |
payerEmail付款人邮箱 |
如果OnionPay能确定此参数时则返回 |
payerMobile付款人电话 |
如果OnionPay能确定此参数时则返回 |
pmId支付功能编号 |
如果OnionPay能确定此参数时则返回 |
paymentType支付方式 |
如果OnionPay能确定此参数时则返回 |
paymentChannel支付渠道 |
如果OnionPay能确定此参数时则返回 |
userId用户Id |
支付请求时,如使用此字段,OnionPay则返回 |
merCustomize商户自定义 |
支付请求时,如使用此字段,OnionPay则返回 |
sign签名 |
上述信息均参与签名,详见签名机制 |
支付查询接口
此接口允许商户通过后端服务器,向OnionPay发起订单查询请求。OnionPay会根据商户请求返回对应的订单查询结果。
版本号
1.1
请求地址
- 生产环境:
https://gateway.onion-pay.com/pg/dk/order/query
- 测试环境:
https://gateway-sandbox.onion-pay.com/pg/dk/order/query
请求参数
{
"merchantId":"47fbcfc0208f8d38f03",
"tradeNo":"20191219141556118010479493",
"version":"1.1",
"sign":"467905b59547fbcfc0208f8d38f0307518c7dcb93211e2f44ff355ff0caac77a"
}
下列参数中,要求的填写位数为字符的长度。
字段 | 说明 |
---|---|
version接口版本 必填 |
当前版本为1.1 |
merchantIdappID 必填 |
此字段在商户完善信息后,由OnionPay生成 |
tradeNo订单号 merTransNo二选一 |
OnionPay交易号 |
merTransNo商户订单号 tradeNo二选一 |
商户订单号 |
sign签名 必填 |
根据其他参数,按照签名机制,计算此字段值,此处使用应用密钥来计算签名 |
data值
当业务处理成功时:
{
"data": {
"amount": "10.00",
"createTime": "2019-12-19 14:15:56",
"currency": "INR",
"merTransNo": "demo-1576735973586",
"message": "success",
"processAmount": "10.00",
"processCurrency": "INR",
"resultCode": "0000",
"sign": "c7b54f5219bf69df4581b1c0a5ca3626a97c2d450f4dae88b6aaf187f81232af",
"tradeNo": "20191219141556118010479493",
"tradeStatus": "pending",
"updateTime": "2019-12-19 14:47:07"
},
"code": "200",
"msg": "OK",
"timestamp": "1576738027034"
}
当业务处理失败时:
{
"data": {
"message": "sign error",
"resultCode": "2002"
},
"code": "200",
"msg": "OK",
"timestamp": "1576738339941"
}
当服务器响应失败时:
{
"msg": "Internal Server Error",
"code": "500",
"timestamp": "1576737487259"
}
字段 | 说明 |
---|---|
resultCode统一下单码 |
当值为0000 时,表明查询业务成功,非0000 时,不能表明订单的状态为失败 |
message下单码描述 |
当值为success 时,表明查询业务成功 |
merTransNo商户订单号 |
商户发起支付时的订单号 |
tradeNoOnionPay订单号 |
商户发起支付时OnionPay生成的订单号 |
amount支付金额 |
支付金额 |
currency币种 |
币种 |
processCurrency交易处理币种 |
兼容其它支付公司参数,无实际作用 |
processAmount交易处理金额 |
兼容其它支付公司参数,无实际作用 |
tradeStatus交易状态 |
交易状态,与支付接口通知机制返回订单状态相同,详见订单状态 |
pmId支付功能编号 |
兼容其它支付公司参数,无实际作用 |
paymentType支付方式 |
兼容其它支付公司参数,无实际作用 |
paymentChannel支付渠道 |
兼容其它支付公司参数,无实际作用 |
userId用户Id |
兼容其它支付公司参数,无实际作用 |
merCustomize商户自定义 |
兼容其它支付公司参数,无实际作用 |
createTime订单创建时间 |
YYYY-MM-dd HH:mm:ss |
updateTime最后处理时间 |
YYYY-MM-dd HH:mm:ss |
tradeCount订单个数 |
兼容其它支付公司参数,无实际作用 |
sign签名值 |
请参考签名机制;签名业务字段只取data 中的字段数据作为业务参数
|
退款接口
版本号
2.0
请求地址
- 生产环境:
https://gateway.onion-pay.com/pg/dk/refund/create
- 测试环境:
https://gateway-sandbox.onion-pay.com/pg/dk/refund/create
请求参数
{
"amount": "2",
"tradeNo": "20191219150101144010478169",
"merchantId": "10000",
"merRefundNo":"demo-1576738678957",
"notifyUrl": "https://example.com/notifyurl",
"currency": "USD",
"version": "2.0",
"sign": "f1bb9507686859fff9b0b0f1fe0931a762e1a97b534e1c8f548a82cfdecc34bd"
}
下列参数中,要求的填写位数为字符的长度。
字段 | 说明 |
---|---|
version接口版本 必填 |
当前版本2.0 |
merchantId商户ID 必填 |
此字段在商户完善信息后,由OnionPay生成 |
tradeNo订单号 必填 |
OnionPay交易号 |
merRefundNo商户退款订单号 必填 |
商户退款订单号 |
amount订单金额 必填1-9位,保留2位小数 |
订单金额请使用字符串方式表示 |
notifyUrl异步通知地址 必填1-150位 |
退款成功时,OnionPay会通过后台调用此url通知商户,通知机制请参照通知机制 |
currency币种 必填3位 |
国际统一币种简称,表示amount 金额的币种,参照国家币种表 |
sign签名 必填 |
根据其他参数,按照签名机制,计算此字段值,此处使用应用密钥来计算签名 |
data值
当业务处理成功时:
{
"data": {
"amount": "2.00",
"createTime": "2019-12-19 15:07:06",
"currency": "USD",
"merRefundNo": "demo-1576738678957",
"message": "success",
"processAmount": "2.00",
"processCurrency": "USD",
"refundNo": "191219150706288010317355",
"resultCode": "0000",
"sign": "0e7fb76499b87d3180205fda6a9522ede585ea1c16892f82fcc201b43f67bb2f",
"status": "success",
"updateTime": "2019-12-19 15:07:06"
},
"code": "200",
"msg": "OK",
"timestamp": "1576739227788"
}
当业务处理失败时:
{
"data": {
"message": "merRefundNo is required",
"resultCode": "3018"
},
"code": "200",
"msg": "OK",
"timestamp": "1576739184034"
}
当服务器响应失败时:
{
"msg": "Internal Server Error",
"code": "500",
"timestamp": "1576737487259"
}
字段 | 说明 | |
---|---|---|
resultCode统一下单码 |
当统一下单码 为0000 时,表明下单成功,具体业务码,请参照统一下单码表 |
|
message下单码描述 |
当下单码描述 为success 时,表明下单成功,具体业务码,请参照统一下单码表 |
|
当下单码描述 为success ,或统一下单码 为0000 时,才会出现以下内容
|
||
amount支付金额 |
支付金额 | |
currency币种 |
币种 | |
processCurrency交易处理币种 |
用户实际支付时使用的币种 | |
refundNo退款订单号 |
OnionPay生成的退款订单号 | |
merRefundNo商户退款订单号 |
商户退款时所传商户退款订单号,不传则不返回 | |
processAmount交易处理金额 |
用户实际支付金额 | |
status退款状态 |
交易状态,与支付接口通知机制返回订单状态相同,详见订单状态 | |
createTime订单创建时间 |
YYYY-MM-dd HH:mm:ss | |
updateTime最后处理时间 |
YYYY-MM-dd HH:mm:ss | |
sign签名值 |
请参考签名机制;签名业务字段只取data 中的字段数据作为业务参数 |
通知参数
通知参数如下:
字段 | 说明 |
---|---|
resultCoderesultCode |
0000为结果正常 |
messagemessage |
success为结果正常 |
transNo交易流水ID |
OnionPay平台交易流水号( 同支付接口返回的tradeNo ) |
merTransNo商户订单号 |
商户生成的订单号 |
refundNo退款单号 |
OnionPay退款单号 |
merRefundNo商户退款单号 |
OnionPay商户退款单号 |
currency币种 |
源订单的币种 |
amount金额 |
源订单金额 |
processCurrency处理币种 |
用户实际支付时使用的币种 |
processAmount处理金额 |
用户实际支付金额 |
status退款状态 |
详见退款状态 |
createTime创建时间 |
订单创建时间(交易发生地时区) |
updateTime最后处理时间 |
最后处理时间 (交易发生地时区) |
sign签名 |
上述信息均参与签名,详见签名机制 |
退款查询接口
版本号
1.1
请求地址
- 生产环境:
https://gateway.onion-pay.com/pg/dk/payout/query
- 测试环境:
https://gateway-sandbox.onion-pay.com/pg/dk/payout/query
请求参数
{
"merchantId": "10000",
"refundNo": "191219150706288010317355",
"merRefundNo": "demo-1576738678957",
"version": "1.1",
"sign": "cf9c6bbc35442f047d9e0043b28b17bf45721dea10274c2901b4300fa3fdea9a"
}
下列参数中,要求的填写位数为字符的长度。
字段 | 说明 |
---|---|
version接口版本 必填 |
当前版本为1.1 |
merchantId商户ID 必填 |
此字段在商户完善信息后,由OnionPay生成 |
refundNo退款订单号 merRefundNo二选一 |
OnionPay退款订单号 |
merRefundNo商户退款订单号 refundNo二选一 |
商户退款订单号 |
sign签名 必填 |
根据其他参数,按照签名机制,计算此字段值,此处使用应用密钥来计算签名 |
data值
当业务处理成功时:
{
"data": {
"amount": "2.00",
"createTime": "2019-12-19 15:07:06",
"currency": "USD",
"merRefundNo": "demo-1576738678957",
"message": "success",
"processAmount": "2.00",
"processCurrency": "USD",
"refundNo": "191219150706288010317355",
"resultCode": "0000",
"sign": "7dfd033ecb8442d6f44c962b1e975bf419075677ac1814a373c39050e8ea08b8",
"status": "success",
"updateTime": "2019-12-19 15:07:08"
},
"code": "200",
"msg": "OK",
"timestamp": "1576739641356"
}
当业务处理失败时:
{
"data": {
"message": "Refund Not Found !",
"resultCode": "3006"
},
"code": "200",
"msg": "OK",
"timestamp": "1576739742091"
}
当服务器响应失败时:
{
"msg": "Internal Server Error",
"code": "500",
"timestamp": "1576737487259"
}
字段 | 说明 | |
---|---|---|
resultCode统一下单码 |
当值为0000 时,表明查询业务成功,但不能表明退款状态为成功,且值不为0000 时,不能理解为退款失败。 |
|
message下单码描述 |
当值为success 时,表明查询业务成功 |
|
当下单码描述 为success ,或统一下单码 为0000 时,才会出现以下内容
|
||
amount支付金额 |
支付金额 | |
currency币种 |
币种 | |
processCurrency交易处理币种 |
用户实际支付时使用的币种 | |
refundNo退款订单号 |
OnionPay生成的退款订单号 | |
merRefundNo商户退款订单号 |
商户退款时所传商户退款订单号,不传则不返回 | |
processAmount交易处理金额 |
用户实际支付金额 | |
status退款状态 |
交易状态,与支付接口通知机制返回订单状态相同,详见订单状态 | |
createTime订单创建时间 |
YYYY-MM-dd HH:mm:ss | |
updateTime最后处理时间 |
YYYY-MM-dd HH:mm:ss | |
sign签名值 |
请参考签名机制;签名业务字段只取data 中的字段数据作为业务参数 |
代付
介绍
OnionPay提供印度的代付接口, 满足商户的银行卡、电子钱包和VA账户内代付的需求。
业务流程
- 商户在商户自服务系统发起代付账户充值申请,用于进行后续代付业务。
- 商户可以调用OnionPay的账户查询接口查询商户在OnionPay的当前可代付账户余额,。不用每次代付前都去调用查询接口,因为扣款也是异步完成的,当前的可用余额不一定能保障代付余额大于后续的代付额度。
- 在可代付余额充足的情况下,商户调用OnionPay的代付接口提交代付相关信息,发起代付请求。
- OnionPay处理代付请求,并在获取到代付结果时通知商户。
- OnionPay在获得代付终态时,将把订单信息通过异步通知机制通知到到商户设置的异步通知URL地址。
- 商户可在商户自服务系统查看代付订单记录。
代付接口
此接口允许商户通过后端服务器,向OnionPay发起代付请求。
版本号
1.1
请求地址
- 生产环境:
https://gateway.onion-pay.com/pg/dk/payout/create
- 测试环境:
https://gateway-sandbox.onion-pay.com/pg/dk/payout/create
请求参数
{
"amount": "100.00",
"appId": "c6bc0348acc447a9d55fc4eb5100e3c49a",
"currency": "INR",
"merTransNo": "demo-1576742093462",
"notifyUrl": "https://example.com/payout/notifyurl",
"version": "1.1",
"sign": "c6bc0348acc447a9d55fc4eb5100e3c49a998ec958c11b062e4040d85958cff5",
"extInfo":
{
"bankCode": "SBIN0007440",
"accountNumber": "12345678912",
"accountHolderName": "ABC lastName"
"payeeLastName": "lastName"
"payeePhone": "911234567890",
"payeeEmail": "abc@gmail.com",
"payeeAddress": "accountHolder's address",
}
}
下列参数中,要求的填写位数为字符的长度。
字段 | 说明 |
---|---|
amount代付订单金额 必填1-9位,保留2位小数 |
代付订单金额请使用字符串方式表示 |
appId应用号 必填 |
此字段在商户申请应用时,由OnionPay生成 |
currency金额币种 必填3位 |
国际统一币种简称,表示amount 金额的币种,参照国家币种表 |
description订单描述 选填1-80位 |
订单的标题,有些场景如果消费者看到订单信息,可能会展示此字段内容 |
merTransNo商户代付订单号 必填1-50位 |
商户自行生成的代付订单号,需要保证唯一性,OnionPay会做唯一性验证, 同一个订单号不可以重复请求接口。 |
notifyUrl代付异步通知地址 必填1-150位 |
代付成功时,OnionPay会通过后台调用此url通知商户,通知机制请参照通知机制 |
pmId功能ID 印度选填,巴西PIX必填 |
巴西PIX方式传PIX账号类型:[CPF, CNPJ, PHONE, EMAIL, EVP, CHAVE_ALEATORIA] |
prodName兼容字段 选填 |
此字段由兼容其它支付公司接口,无实际意义 |
version接口版本 选填 |
当前版本 1.1 |
sign签名 必填 必填 |
根据其他参数,按照签名机制,计算此字段值,此处使用应用密钥来计算签名 |
extInfo扩充参数信息 |
此参数为JSON格式,具体的参数列表需参考pmId对应的extInfo列表 |
data值
当业务处理成功时:
{
"data": {
"amount": "10000",
"currency": "INR",
"merTransNo": "demo-1576742093462",
"message": "success",
"resultCode": "0000",
"sign": "e1618758a8eeccefa001e8694ba07355546f73b78a740a0c146c9d8ef4881487",
"tradeNo": "20191219155755942010474021"
},
"code": "200",
"msg": "OK",
"timestamp": "1576742276065"
}
当业务处理失败时:
{
"msg": "OK",
"code": "200",
"data": {
"message": "sign error",
"resultCode": "2002"
},
"timestamp": "1576741296325"
}
当服务器响应失败时:
{
"msg": "Internal Server Error",
"code": "500",
"timestamp": "1576737487259"
}
字段 | 说明 | |
---|---|---|
resultCode统一下单码 |
当统一下单码 为0000 时,表明下单成功,具体业务码,请参照统一下单码表 |
|
message下单码描述 |
当下单码描述 为success 时,表明下单成功,具体业务码,请参照统一下单码表 |
|
当下单码描述 为success ,或统一下单码 为0000 时,才会出现以下内容
|
||
amount代付订单金额 |
代付订单金额 | |
currency代付币种 |
发起代付请求币种 | |
merTransNo商户代付订单号 |
商户代付订单号 | |
tradeNo订单号 |
OnionPay的平台订单号 | |
sign签名值 |
请参考签名机制;签名业务字段只取data 中的字段数据作为业务参数 |
通知参数
API方式代付接口仅有异步通知,通知机制见通知机制,具体参数如下:
字段 | 说明 |
---|---|
resultCode代付失败错误码 |
当tradeStatus值为failure时,此字段会返回,并且参与通知签名 |
message代付失败错误信息 |
当tradeStatus值为failure时,此字段会返回,并且参与通知签名 |
tradeNo交易流水ID |
OnionPay平台交易流水号 |
merTransNo商户订单号 |
商户生成的订单号 |
currency币种 |
源订单的币种 |
amount金额 |
源订单金额 |
totalFee手续费 |
代付手续费 |
pmId代付功能编号 |
如果OnionPay能确定此参数时则返回 |
tradeStatus订单状态 |
详见订单状态 |
createTime创建时间 |
订单创建时间(交易发生地时区) |
updateTime最后处理时间 |
最后处理时间 (交易发生地时区) |
sign签名 |
上述信息均参与签名,详见签名机制 |
代付查询接口
此接口允许商户通过后端服务器,向OnionPay发起代付查询请求。OnionPay会根据商户请求返回对应的订单查询结果。
版本号
1.1
请求地址
- 生产环境:
https://gateway.onion-pay.com/pg/dk/payout/query
- 测试环境:
https://gateway-sandbox.onion-pay.com/pg/dk/payout/query
请求参数
{
"merchantId":"47fbcfc0208f8d38f03",
"tradeNo":"20191219141556118010479493",
"version":"1.1",
"sign":"467905b59547fbcfc0208f8d38f0307518c7dcb93211e2f44ff355ff0caac77a"
}
下列参数中,要求的填写位数为字符的长度。
字段 | 说明 |
---|---|
version接口版本 必填 |
当前版本为1.1 |
merchantIdappID 必填 |
此字段在商户完善信息后,由OnionPay生成 |
tradeNo订单号 merTransNo二选一 |
OnionPay交易号 |
merTransNo商户订单号 tradeNo二选一 |
商户订单号 |
sign签名 必填 |
根据其他参数,按照签名机制,计算此字段值,此处使用应用密钥来计算签名 |
data值
字段 | 说明 |
---|---|
resultCode代付失败错误码 |
当tradeStatus值为failure时,此字段会返回,并且参与通知签名 |
message代付失败错误信息 |
当tradeStatus值为failure时,此字段会返回,并且参与通知签名 |
tradeNo交易流水ID |
OnionPay平台交易流水号 |
merTransNo商户订单号 |
商户生成的订单号 |
currency币种 |
源订单的币种 |
amount金额 |
源订单金额 |
totalFee手续费 |
代付手续费 |
pmId代付功能编号 |
如果OnionPay能确定此参数时则返回 |
tradeStatus订单状态 |
详见订单状态 |
createTime创建时间 |
订单创建时间(交易发生地时区) |
updateTime最后处理时间 |
最后处理时间 (交易发生地时区) |
sign签名 |
上述信息均参与签名,详见签名机制 |
账户查询接口
版本号
1.1
请求地址
- 生产环境:
https://gateway.onion-pay.com/pg/dk/account/query
- 测试环境:
https://gateway-sandbox.onion-pay.com/pg/dk/account/query
请求参数
{
"merchantId": "c6bc0348acc447a9d55",
"accType": "default",
"version": "1.1",
"sign": "fa1824c230b00a6407a7b2af53e7307fe2c46727f8e2f4ae0227dd964965bcb5"
}
下列参数中,要求的填写位数为字符的长度。
字段 | 说明 |
---|---|
merchantId收款 AppID 必填 |
此字段为收款 AppID,由OnionPay生成 |
currency账户币种 选填3位 |
国际统一币种简称,参照国家币种表 |
accType账户类型 选填 |
账户类型 default、payment、payout |
version接口版本 必填 |
当前版本为1.1 |
sign签名 必填 |
根据其他参数,按照签名机制,计算此字段值,此处使用应用密钥来计算签名 |
data值
当业务处理成功时:
{
"data": {
"accounts": [
{
"accId": "10000",
"accType": "payment",
"balance": "996259.000000",
"currency": "USD",
"frozenAmount": "0.000000",
"merchantId": "10000",
"status": "actived"
},
{
"accId": "10028",
"accType": "payment",
"balance": "28366.000000",
"currency": "CNY",
"frozenAmount": "0.000000",
"merchantId": "10000",
"status": "actived"
},
{
"accId": "10039",
"accType": "payment",
"balance": "161633550.000000",
"currency": "INR",
"frozenAmount": "0.000000",
"merchantId": "10000",
"status": "actived"
},
{
"accId": "10041",
"accType": "payment",
"balance": "0.000000",
"currency": "INR",
"frozenAmount": "0.000000",
"merchantId": "10000",
"status": "actived"
},
{
"accId": "10065",
"accType": "payment",
"balance": "0.000000",
"currency": "SGD",
"frozenAmount": "0.000000",
"merchantId": "10000",
"status": "actived"
},
{
"accId": "10070",
"accType": "payment",
"balance": "26777382.000000",
"currency": "VND",
"frozenAmount": "0.000000",
"merchantId": "10000",
"status": "actived"
}
],
"merchantId": "10000",
"message": "success",
"resultCode": "0000"
},
"code": "200",
"msg": "OK",
"timestamp": "1576741366106"
}
当业务处理失败时:
{
"data": {
"message": "accType is incorrect",
"resultCode": "1001"
},
"code": "200",
"msg": "OK",
"timestamp": "1576741475422"
}
当服务器响应失败时:
{
"msg": "Internal Server Error",
"code": "500",
"timestamp": "1576737487259"
}
字段 | 说明 |
---|---|
resultCode响应码 |
查询响应码 |
message响应信息 |
查询响应信息 |
当响应码 为0000 时,或响应信息 为success ,才会出现以下内容
|
|
merchantId商户ID |
此字段在商户完善信息后,由OnionPay生成 |
accounts账户列表 |
商户的账户列表 |
accouts 账户列表字段 | |
accId账户ID |
商户的账户ID |
accType账户类型 |
账户类型:payment 、payout |
balance账户余额 |
账户余额 |
currency账户币种 |
账户币种 |
frozenAmount账户冻结金额 |
账户冻结金额 |
merchantId商户ID |
此字段在商户完善信息后,由OnionPay生成 |
status账户状态 |
账户状态:pending 、actived、closed |
extInfo列表
此处的内容,是针对于某种支付或者代付功能的补充信息参数做具体的说明。
收款
收款参数列表
字段 | 说明 |
---|---|
citizenId持卡人身份ID 选填 |
持卡人身份ID |
taxNo持卡人纳税编号 选填 |
持卡人纳税编号 |
userId用户Id 选填 |
用户Id |
deviceId设备Id 选填 |
设备Id |
userIp用户ip 选填 |
用户ip |
registerTime用户注册时间 选填 |
用户注册时间 yyyy-MM-dd HH:mm:ss |
latitude纬度 选填 |
地理位置 纬度 |
longitude经度 选填 |
地理位置 经度 |
代付
代付参数列表
字段 | 说明 |
---|---|
bankCode银行编码 1-50位 必填 |
银行编码 印度业务为 IFSC 格式为11位: 4位字母 + N个0 + 数字 如:AAAA0XXXXXX 、 INDB0000018 印度UPI的VPA帐户填:UPI |
accountNumber卡号 1-50位 必填
|
卡号 / VPA 印度VPA(UPI ID)格式:upi@server 巴西PIX格式:PIX账号 |
accountHolderName持卡人姓名 必填 |
持卡人姓名 |
payeePhone持卡人手机号 必填 |
持卡人手机号 |
payeeEmail持卡人邮箱 必填 |
持卡人邮箱 |
payeeAddress持卡人地址 必填 |
持卡人地址 |
citizenId持卡人身份ID 选填 |
持卡人身份ID |
taxNo持卡人纳税编号 选填 |
持卡人纳税编号 |
userId用户Id 选填 |
用户Id |
deviceId设备Id 选填 |
设备Id |
userIp用户ip 选填 |
用户ip |
registerTime用户注册时间 选填 |
用户注册时间 yyyy-MM-dd HH:mm:ss |
latitude纬度 选填 |
地理位置 纬度 |
longitude经度 选填 |
地理位置 经度 |
附件码表
订单状态
编码 | 状态 |
---|---|
pending | 待支付 |
processing | 支付中 |
success | 支付成功 |
failure | 支付失败 |
统一下单码表
暂时未提供,具体错误原因,参照message
信息
国家币种表
ISO代码 | 英文 | 中文 | 币种 |
---|---|---|---|
AE | United Arab Emirates | 阿联酋 | AED |
AR | Argentina | 阿根廷 | ARS |
AU | Australia | 澳大利亚 | AUD |
BB | Barbados | 巴巴多斯 | BBD |
BH | Bahrain | 巴林 | BHD |
BI | Burundi | 布隆迪 | BIF |
BM | Bermuda | 百慕大 | BMD |
BO | Bolivia | 玻利维亚 | BOB |
BR | Brazil | 巴西 | BRL |
BZ | Belize | 伯利兹 | BZD |
CA | Canada | 加拿大 | CAD |
CH | Switzerland | 瑞士 | CHF |
CN | China | 中国 内地 | CNY |
CR | Costa Rica | 哥斯达黎加 | CRC |
CZ | Czech Republic | 捷克 | CZK |
DJ | Djibouti | 吉布提 | DJF |
DK | Denmark | 丹麦 | DKK |
DO | Dominican Republic | 多米尼加 | DOP |
EG | Egypt | 埃及 | EGP |
GB | Great Britain (United Kingdom; England) | 英国 | GBP |
GN | Guinea | 几内亚 | GNF |
GT | Guatemala | 危地马拉 | GTQ |
HK | Hong Kong | 香港 | HKD |
HN | Honduras | 洪都拉斯 | HNL |
HR | Croatia | 克罗地亚 | HRK |
HU | Hungary | 匈牙利 | HUF |
ID | Indonesia | 印尼 | IDR |
IL | Israel | 以色列 | ILS |
IN | India | 印度 | INR |
IS | Iceland | 冰岛 | ISK |
JM | Jamaica | 牙买加 | JMD |
JP | Japan | 日本 | JPY |
KR | South Korea | 韩国 南朝鲜 | KRW |
KW | Kuwait | 科威特 | KWD |
KZ | Kazakhstan | 哈萨克斯坦 | KZT |
LK | Sri Lanka | 斯里兰卡 | LKR |
LT | Lithuania | 立陶宛 | LTL |
MA | Morocco | 摩洛哥 | MAD |
MO | Macao | 澳门 | MOP |
MX | Mexico | 墨西哥 | MXN |
MY | Malaysia | 马来西亚 | MYR |
NO | Norway | 挪威 | NOK |
NZ | New Zealand | 新西兰 | NZD |
PK | Pakistan | 巴基斯坦 | PKR |
PY | Paraguay | 巴拉圭 | PYG |
QA | Qatar | 卡塔尔 | QAR |
RU | Russian Federation | 俄罗斯 | RUB |
SA | Saudi Arabia | 沙特阿拉伯 | SAR |
SE | Sweden | 瑞典 | SEK |
SG | Singapore | 新加坡 | SGD |
TN | Tunisia | 突尼斯 | TND |
TH | Thailand | 泰国 | THB |
UG | Uganda | 乌干达 | UGX |
US | United States of America (USA) | 美国 | USD |
VN | Vietnam | 越南 | VND |
VU | Vanuatu | 瓦努阿图 | VUV |
ZA | South Africa | 南非 | ZAR |
PH | The Philippines | 菲律宾 | PHP |
测试账号
请联系 OnionPay 商务开通测试账户
印度支付测试参数
Credit
Number | Expiry | CVV | Name |
---|---|---|---|
4444 3333 2222 1111 | 07/2023 | 123 | Test |
4111 1111 1111 1111 | 07/2023 | 123 | Test |
Paytm Wallet
Mobile | Password | OTP |
---|---|---|
77777 77777 | Paytm12345 | 489871 |
Paytm ( Credit & Debit )
Number | Expiry | CVV |
---|---|---|
4200 0000 0000 0000 | 07/2029 (未来日期即可) | 123 |
Netbanking
Bank Name |
---|
TEST Bank |