NAV

OnionPay API Reference

java

简介

OnionPay 提供安全的海外本地化支付服务,宗旨是让客户的本地化支付更轻松。

客户在自己的网站或APP内集成 OnionPay 的支付产品,可以实现在线下和线上场景的收放款服务。OnionPay 提供涵盖全球范围内多个国家的包括钱包、借记卡、信用卡、网银和UPI在内的200多种支付方式的收放款服务。同时OnionPay还提供了个性化的服务产品。

接入指引

商户接入流程概述

img

商户在 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时, 需要遵循以下安全要求:

请求方法

基于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&currency=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&currency=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",
  "country": "IN",
  "currency": "INR",
  "extInfo": {
    "paymentTypes": "credit,debit,ewallet,upi"
  },
  "merTransNo": "demo-1576735973586",
  "notifyUrl": "https://example.com/notifyurl",
  "prodName": "southeast.asia",
  "returnUrl": "https://example.com/returnurl",
  "version": "1.1"
}

        

对应的请求参数为:


{
  "amount": "10",
  "appId": "4189b620f93b48c5904210ff47bb8936",
  "country": "IN",
  "currency": "INR",
  "extInfo": {
    "paymentTypes": "credit,debit,ewallet,upi"
  },
  "merTransNo": "demo-1576735973586",
  "notifyUrl": "https://example.com/notifyurl",
  "prodName": "southeast.asia",
  "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",
  "extInfo": {
    "paymentTypes": "credit,debit,ewallet,upi"
  },
  "merTransNo": "demo-1576735973586",
  "notifyUrl": "https://example.com/notifyurl",
  "prodName": "southeast.asia",
  "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", 
  "extInfo": {"paymentTypes": "credit,debit,ewallet,upi"},
  "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)。
  • OnionPay 返回商户 OnionPay 收银台URL链接。
  • 商家在自己的产品内打开 OnionPay 收银台URL链接,展示给用户。
  • 用户在 OnionPay 收银台上选择支付方式并按照指引完成后续付款操作。
  • 支付完成后将跳转至商户在下单时指定的 returnUrl 链接页面。
  • OnionPay 在获得支付终态时,将把订单信息通过异步通知机制通知到到商户设置的 notifyUrl 地址。
  • 印度 UPI 接入指引

    UPI支付流程

    支付接口

    此接口允许商户通过后端服务器,向OnionPay发起支付请求。OnionPay会根据商户请求做出相应响应;并提示商户下步操作方式。

    版本号

    1.1

    请求地址

    请求参数

    
    {
      "amount": "10",
      "appId": "4189b620f93b48c5904210ff47bb8936",
      "country": "IN",
      "currency": "INR",
      "extInfo": {
        "paymentTypes": "credit,debit,ewallet,upi"
      },
      "merTransNo": "demo-1576735973586",
      "notifyUrl": "https://example.com/notifyurl",
      "prodName": "southeast.asia",
      "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
    扩充参数信息
    选填
    印度支付不需要传;巴西支付需要传用户的 document (即用户的CPF)信息,格式如下:
    "extInfo": { "document": "12345678912" }
    sign
    签名
    必填
    根据其他参数,按照签名机制,计算此字段值,此处使用应用密钥来计算签名

    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
    处理地址
    如果doingredirect,则商户可直接将消费者网页重定向到此地址上
    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

    请求地址

    请求参数

    {
            "merchantId":"47fbcfc0208f8d38f03",
            "tradeNo":"20191219141556118010479493",
            "version":"1.1",
            "sign":"467905b59547fbcfc0208f8d38f0307518c7dcb93211e2f44ff355ff0caac77a"
          }
          

    下列参数中,要求的填写位数为字符的长度。

    字段 说明
    version
    接口版本
    必填
    当前版本为1.1
    merchantId
    appID
    必填
    此字段在商户完善信息后,由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
    商户订单号
    商户发起支付时的订单号
    tradeNo
    OnionPay订单号
    商户发起支付时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

    请求地址

    请求参数

    {
                "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中的字段数据作为业务参数

    通知参数

    通知参数如下:

    字段 说明
    resultCode
    resultCode
    0000为结果正常
    message
    message
    success为结果正常
    transNo
    交易流水ID
    OnionPay平台交易流水号( 同支付接口返回的tradeNo )
    merTransNo
    商户订单号
    商户生成的订单号
    refundNo
    退款单号
    OnionPay退款单号
    merRefundNo
    商户退款单号
    OnionPay商户退款单号
    currency
    币种
    源订单的币种
    amount
    金额
    源订单金额
    processCurrency
    处理币种
    用户实际支付时使用的币种
    processAmount
    处理金额
    用户实际支付金额
    status
    退款状态
    详见退款状态
    createTime
    创建时间
    订单创建时间(交易发生地时区)
    updateTime
    最后处理时间
    最后处理时间 (交易发生地时区)
    sign
    签名
    上述信息均参与签名,详见签名机制

    退款查询接口

    版本号

    1.1

    请求地址

    请求参数

    {
                "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账户内代付的需求。

    业务流程

    img

    1. 商户在商户自服务系统发起代付账户充值申请,用于进行后续代付业务。
    2. 商户可以调用OnionPay的账户查询接口查询商户在OnionPay的当前可代付账户余额,。不用每次代付前都去调用查询接口,因为扣款也是异步完成的,当前的可用余额不一定能保障代付余额大于后续的代付额度。
    3. 在可代付余额充足的情况下,商户调用OnionPay的代付接口提交代付相关信息,发起代付请求。
    4. OnionPay处理代付请求,并在获取到代付结果时通知商户。
    5. OnionPay在获得代付终态时,将把订单信息通过异步通知机制通知到到商户设置的异步通知URL地址。
    6. 商户可在商户自服务系统查看代付订单记录。

    代付接口

    此接口允许商户通过后端服务器,向OnionPay发起代付请求。

    版本号

    1.1

    请求地址

    请求参数

    
    {
      "amount": "100.00",
      "appId": "c6bc0348acc447a9d55fc4eb5100e3c49a",
      "currency": "INR",
      "merTransNo": "demo-1576742093462",
      "notifyUrl": "https://example.com/payout/notifyurl",
      "pmId": "payout.bank.id",
      "prodName": "southeast.asia.payout",
      "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

    {
            "merchantId":"47fbcfc0208f8d38f03",
            "tradeNo":"20191219141556118010479493",
            "version":"1.1",
            "sign":"467905b59547fbcfc0208f8d38f0307518c7dcb93211e2f44ff355ff0caac77a"
          }
          

    下列参数中,要求的填写位数为字符的长度。

    字段 说明
    version
    接口版本
    必填
    当前版本为1.1
    merchantId
    appID
    必填
    此字段在商户完善信息后,由OnionPay生成
    tradeNo
    订单号
    merTransNo二选一
    OnionPay交易号
    merTransNo
    商户订单号
    tradeNo二选一
    商户订单号
    sign
    签名
    必填
    根据其他参数,按照签名机制,计算此字段值,此处使用商户密钥来计算签名
    字段 说明
    resultCode
    代付失败错误码
    当tradeStatus值为failure时,此字段会返回,并且参与通知签名
    message
    代付失败错误信息
    当tradeStatus值为failure时,此字段会返回,并且参与通知签名
    tradeNo
    交易流水ID
    OnionPay平台交易流水号
    merTransNo
    商户订单号
    商户生成的订单号
    currency
    币种
    源订单的币种
    amount
    金额
    源订单金额
    totalFee
    手续费
    代付手续费
    pmId
    代付功能编号
    如果OnionPay能确定此参数时则返回
    tradeStatus
    订单状态
    详见订单状态
    createTime
    创建时间
    订单创建时间(交易发生地时区)
    updateTime
    最后处理时间
    最后处理时间 (交易发生地时区)
    sign
    签名
    上述信息均参与签名,详见签名机制

    账户查询接口

    版本号

    1.1

    请求地址

    请求参数

    {
                "merchantId": "c6bc0348acc447a9d55",
                "accType": "default",
                "version": "1.1",
                "sign": "fa1824c230b00a6407a7b2af53e7307fe2c46727f8e2f4ae0227dd964965bcb5"
              }
              

    下列参数中,要求的填写位数为字符的长度。

    字段 说明
    merchantId
    商户ID
    必填
    此字段在商户完善信息后,由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列表

    此处的内容,是针对于某种支付或者代付功能的补充信息参数做具体的说明。

    收款

    pmId参数(不区分大小写)

    pmId 说明
    UPI UPI支付
    Wallet wallet
    Netbanking Netbanking
    Card Card

    代付

    代付参数列表

    字段 说明
    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
    持卡人地址
    必填
    持卡人地址

    附件码表

    订单状态

    编码 状态
    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

    测试账号

    印度支付测试参数

    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