在线支付 API 文档

更新时间：2024.10.17 03:53:16

在线支付 API 文档

收款 (Payment)

接口说明

收款作为商户发起收款业务场景的入口，由商户服务端向 Paynicorn 发起收款请求，Paynicorn 会根据的参数封装支付方式列表，并返回收银台链接或者直接发起支付

接口地址

https://api.paynicorn.com/trade/v3/transaction/pay

请求参数

字段填写要求 M:mandatory 必填，O：optional 条件选填

字段名	类型	填写要求	描述
amount	String(32)	M	本币最小单位，保留两位小数，参见附录国家币种对照表
countryCode	String(2)	M	国家代码(CountryCode)，参见附录国家币种对照表
orderId	String(64)	M	唯一请求流水号，幂等处理依据，同一个流水号重复请求会被拒绝
orderDescription	String(1024)	M	交易描述
currency	String(3)	M	币种代码(CurrencyCode)，参见附录国家币种对照表
referenceNo	String(32)	O	原始票据单号，支付关联业务的唯一凭证，支付成功后回调回包含该字段
payMethod	String(64)	O	支付方法编码，指定则使用该支付方法，不进入 paynicorn 收银台，不指定则进入 paynicorn 收银台选择支付方法参见附录支付方法列表
language	String(8)	O	预设收银台语言，不传就使用系统语言
cpFrontPage	String(1024)	O	前端接受支付结果页地址，如提供，支付完成后，页面会自动重定向到该地址
palmAuthCode	String(8)	O	通过 PalmID 授权认证,提供授权支付功能.(需要:1 集成 PalmID, 2 联系 Paynicorn 运营人员开通授权支付权限)
email	String(128)	O	用户邮箱，如提供，则需要使用用户邮箱的渠道会直接使用提供的邮箱，跳过用户填写邮箱页面
phone	String(32)	O	用户手机号 (不含国家区号)，如提供，则需要使用用户手机号码的渠道会直接使用提供的手机号，跳过用户填写手机号页面
cnic	String(32)	O	巴基斯坦支付特有字段，巴基斯坦电子身份证号码
payByLocalCurrency	Boolean	O	是否采用本地币支付,默认为 false,当为 true 并且 currency 不是 countryCode 本地币种的时候会尝试将非本地币转为本地币进行支付
memo	String(1024)	O	扩展信息 (存放 JSON 字符串)，paynicorn 不做处理，回调透传

响应参数

字段名	类型	备注
code	String(16)	状态码参见状态码
message	String(256)	消息参见状态码
txnId	String(64)	交易单号
status	String(2)	订单状态(1:成功；-1：处理中；0：失败)
webUrl	String(64)	H5 支付地址

注意：

针对收款接口，可以通过传入 payMethod 指定该次支付使用的支付方式，跳过 Paynicorn 收银台选择支付方式的页面。
若在多个业务开展国开展收单业务，发起支付预下单统一使用美元货币预下单：currency = USD，countryCode = 用户所在真实国家，PayByLocalCurrency = true。交易系统会根据用户所在国家 countryCode，自动进行货币转化，给用户在支付收银台上展示本位币金额。
如果该支付方式需要用户的手机号码，可以通过 phone 传入手机号码，跳过 Paynicorn 收银台的输入手机号码页面。
通过提供相应的参数，可以跳过 Paynicorn 收银台的 Web 页面，直接发起相应支付，在这种情况下，Paynicorn 响应参数中的 webUrl 为空，商户可以自行实现相关的前端页面。
具体支持的支付方法以及相关方法需要传入的参数可以参考支付方法列表。
客户端通过 WebView 展示 H5 收银台，请参考客户端 WebView 授权为 WebView 开启所需权限。

退款 (Refund)

接口说明

对于成功的收款订单发起退款申请，同步受理，异步处理，结果等查询

接口地址

https://api.paynicorn.com/trade/v3/transaction/refund

接口参数

字段填写要求 M:mandatory 必填，O：optional 条件选填

字段名	类型	填写要求	描述
payTxnId	String(64)	M	原交易单号
refundId	String(64)	M	商户退款订单号

响应参数

字段名	类型	填写要求	备注
code	String(16)	M	状态码参见状态码
message	String(256)	M	消息参见状态码
txnId	String(64)	M	交易单号
status	String(2)	M	订单状态(1:成功；-1：处理中；0：失败)

报文示例

Request Body

{
  "refundId": "92428512966672483",
  "payTxnId": "32428512966672847"
}

Response

{
  "code": "0000",
  "message": "success",
  "status": "1", //-1: 退款处理中，1: 退款成功，0：退款失败
  "txnId": "32428512966672847"
}

查询交易结果接口 (Query)

接口说明

用于非同步接口和同步接口超时场景查询

接口地址

https://api.paynicorn.com/trade/v3/transaction/query

请求参数

字段填写要求 M:mandatory 必填，O：optional 条件选填

字段名	类型	填写要求	描述
orderId	String(64)	M	商户订单号
txnType	String(8)	M	交易类型

响应参数

字段名	类型	填写要求	备注
code	String(16)	M	状态码参见状态码
message	String(256)	M	消息参见状态码
txnId	String(64)	M	交易单号
status	String(4)	M	支付结果
completeTime	String(16)	O	交易处理完成时间

报文示例

Request Body

{
  "appKey": "7971100",
  "orderId": "92428512966672483",
  "txnType": "payment" //payment 或者 refund
}

Response

{
  "code": "0000",
  "completeTime": "",
  "message": "success",
  "status": "-1", //-1: 支付处理中，1: 支付成功，0：支付失败
  "txnId": "32428513799242015"
}

异步通知接口 (Postback)

接口说明

异步交易结果通知，收款和授权支付不能立即获取交易结果的，在交易状态发生改变的时候，paynicorn 会调用商户设置的异步通知结果，将最新的订单状态通知商户服务端。商户收到回调通知后，需要按照 Paynicorn 的要求进行响应。

响应要求：

HttpsStatus 需要为 200。
Response Body 支持 2 类，商户可以根据自身偏好决定采用哪个：
1. Plain Text 字符串：内容要求为success_txnId，案例：success_32433552680878215。
2. JSON：内容要求为{"status":"success_txnId"}，案例：{"status":"success_32433552680878215"}。

请注意：若没有严格按照上述要求返回响应意味着通知失败，系统会继续通知直到成功，重试次数最多 7 次，通知间隔时间按照 10*2^(n-1)递增(单位:分，n 代表通知次数)，频率是：10min, 20min, 40min, 80min, 160min, 320min。

异步通知对不同接口的回调规则：

本接口会对 Payment 接口发起回调通知。
本接口不会对 Refund 接口发起回调通知，需要商户主动查询交易结果。

接口地址

商户提供，通过商户平台配置，参见设置应用回调地址

请求参数

响应参数

参数名	类型	填写要求	备注
txnId	String(64)	M	支付单号
orderId	String(64)	M	交易流水号
amount	String(32)	M	实际支付金额
pricingAmount	String(32)	M	下单金额
currency	String(3)	M	实际支付币种
pricingCurrency	String(32)	M	下单币种
countryCode	String(2)	M	国家码
payMethod	String(32)	O	支付方式，支付成功状态下会有
status	String(4)	M	支付状态
code	String(6)	M	状态码
message	String(256)	M	消息
memo	String(1024)	O	备注信息
referenceNo	String(32)	M	原始交易凭证

报文示例

{
  "amount": "99.8",
  "code": "0000",
  "countryCode": "NG",
  "currency": "NGN",
  "message": "success",
  "orderId": "92428512966672483",
  "pricingAmount": "99.8",
  "pricingCurrency": "NGN",
  "status": "1", //-1: 支付处理中，1: 支付成功，0：支付失败
  "txnId": "32428512966672847"
}

请注意：

系统会通知成功和失败的订单，若希望只通知成功的订单，可以前往开发者模块关闭支付失败订单通知开关。
商户收到回调通知后，需要按照 Paynicorn 的要求进行响应。
HttpsStatus=200代表接受到通知并返回字符串success_{txnId}，其他代表通知失败。
没有返回success_{txnId}的会继续通知，直到成功，最多 7 次，通知间隔时间按照 10*2^(n-1)递增(单位:分，n 代表通知次数)，频率是：10min, 20min, 40min, 80min, 160min, 320min。

获取支付方式 (PayMethod)

接口说明

获取可用的支付方式

接口地址

https://api.paynicorn.com/trade/v3/transaction/method

请求参数

字段填写要求 M:mandatory 必填，O：optional 条件选填

字段名	类型	填写要求	描述
countryCode	String(2)	M	国家代码(CountryCode)，参见附录国家币种对照表
currency	String(3)	M	币种代码(CurrencyCode)，参见附录国家币种对照表
txnType	String(8)	M	交易类型, 参见附录交易类型

响应参数

字段名	类型	填写要求	备注
code	String(16)	M	状态码参见状态码
message	String(256)	M	消息参见状态码
methodInfo	Array<MethodInfo>	O	可用支付方式列表

MethodInfo

字段名	类型	填写要求	备注
code	String(32)	M	支付方式代码
name	String(32)	M	支付方式名称
icon	String(128)	M	支付方式图标 URL
methodType	String(16)	M	支付方式类型
supportAmount	Array<Decimal>	O	支持金额,离散值,与 minAmount\maxAmount 不会同时出现
minAmount	Decimal	O	支持最小金额,与 supportAmount 不会同时出现
maxAmount	Decimal	O	支持最大金额,与 supportAmount 不会同时出现
discount	Decimal	O	折扣
inputs	Array<InputInfo>	O	参数信息

InputInfo

字段名	类型	填写要求	备注
hint	String(32)	O	参数输入提示
name	String(32)	O	参数名称
reg	String(32)	O	参数校验正则表达式
tips	String(32)	O	参数报错提示信息
type	String(32)	O	参数类型

报文示例

Request Body

{
  "countryCode": "NG",
  "currency": "NGN",
  "txnType": "payment"
}

Response

{
  "code": "0000",
  "message": "success",
  "methodInfo": [
    {
      "code": "PALMPAY",
      "discount": null,
      "icon": "https://cdn.shalltry.com/public-prod/operation/image/1609320891941.png",
      "maxAmount": 9223372036854775807,
      "methodType": "OTHERS",
      "minAmount": 0,
      "name": "PalmPay",
      "supportAmount": [],
      "subscribeAmount": null,
      "mccmncSubscribeAmount": null,
      "inputs": [
        { "hint": "PhonePK_tips", "name": "Phone_PK", "reg": "^[0]?3\\d{9}$", "tips": "invalidPhone", "type": "Phone" },
        {
          "hint": "CNICTips_FULL",
          "name": "CNIC_PK_FULL",
          "reg": "^[0-9]\\d{12}$",
          "tips": "invalidFullCNIC",
          "type": "CNIC"
        }
      ]
    },
    {
      "code": "BANKTRANSFER",
      "discount": null,
      "icon": "https://cdn.shalltry.com/public-prod/operation/image/1609320880283.png",
      "maxAmount": 9223372036854775807,
      "methodType": "OTHERS",
      "minAmount": 0,
      "name": "Bank Transfer",
      "supportAmount": [],
      "subscribeAmount": null,
      "mccmncSubscribeAmount": null,
      "inputs": []
    },
    {
      "code": "USSD",
      "discount": null,
      "icon": "https://cdn.shalltry.com/public-prod/operation/image/1663163871968.png",
      "maxAmount": 9223372036854775807,
      "methodType": "OTHERS",
      "minAmount": 0,
      "name": "USSD",
      "supportAmount": [],
      "subscribeAmount": null,
      "mccmncSubscribeAmount": null,
      "inputs": []
    },
    {
      "code": "CARD",
      "discount": null,
      "icon": "https://cdn.shalltry.com/public-prod/operation/image/1663163573271.png",
      "maxAmount": 9223372036854775807,
      "methodType": "OTHERS",
      "minAmount": 0,
      "name": "Card",
      "supportAmount": [],
      "subscribeAmount": null,
      "mccmncSubscribeAmount": null,
      "inputs": []
    }
  ]
}

请注意：

获取业务开展国支付方式列表的接口，仅在业务方应用内购物车需要承担收银台的下单逻辑的时候使用。

上一篇： API 接口签名验证

下一篇：付款产品

在线支付 API 文档

在线支付 API 文档 #

收款 (Payment) #

接口说明 #

接口地址 #

请求参数 #

响应参数 #

退款 (Refund) #

接口说明 #

接口地址 #

接口参数 #

响应参数 #

报文示例 #

查询交易结果接口 (Query) #

接口说明 #

接口地址 #

请求参数 #

响应参数 #

报文示例 #

异步通知接口 (Postback) #

接口说明 #

接口地址 #

请求参数 #

响应参数 #

报文示例 #

获取支付方式 (PayMethod) #

接口说明 #

接口地址 #

请求参数 #

响应参数 #

报文示例 #

在线支付 API 文档

收款 (Payment)

接口说明

接口地址

请求参数

响应参数

退款 (Refund)

接口说明

接口地址

接口参数

响应参数

报文示例

查询交易结果接口 (Query)

接口说明

接口地址

请求参数

响应参数

报文示例

异步通知接口 (Postback)

接口说明

接口地址

请求参数

响应参数

报文示例

获取支付方式 (PayMethod)

接口说明

接口地址

请求参数

响应参数

报文示例