API 接入文档

信息

所有服务端接口的调用都需要按照要求进行请求内容的编码和签名工作，具体请参考 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 收银台选择支付方式的页面

PAYNICORN的收银台 建议商户都用手机浏览器加载打开 不要用WEBVIEW加载 否则WEBVIEW页面跳转的功能需要商户进行适配

如果该支付方式需要用户的手机号码，可以通过 phone 传入手机号码，跳过 Paynicorn 收银台的输入手机号码页面

通过提供相应的参数，可以跳过 Paynicorn 收银台的 Web 页面，直接发起相应支付，在这种情况下，Paynicorn 响应参数中的 webUrl 为空，商户可以自行实现相关的前端页面

具体支持的支付方法以及相关方法需要传入的参数可以参考 支付方法列表

退款 (Refund)

接口说明

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

接口地址

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

接口参数

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

字段名	类型	填写要求	描述
payTxnId	String(64)	M	原交易单号
cpRefundId	String(64)	M	商户退款订单号
reason	String(64)	M	原因
memo	String(64)	M	备注

响应参数

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

代付 (Payout)

接口说明

代付接口，默认不开通，需要开通联系kailan.ruan@transsion.com

接口地址

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

接口参数

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

字段名	类型	填写要求	描述
orderId	String(64)	M	商户付款订单号
currency	String(3)	M	币种代码(CurrencyCode)，参见附录 国家币种对照表
amount	String(32)	M	金额
countryCode	String(2)	M	国家代码(CountryCode)，参见附录 国家币种对照表
payoutMethod	String(64)	M	转账类型（CARD,MTN,MPESA,PAYNICORNPAY,AIRTEL...）
name	String(64)	M	收款人名字
account	String(64)	M	收款账户
bankCode	String(64)	O	银行码(转账类型为银行卡时必填)参见附录 银行代码

响应参数

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

向paynicorn用户转账

接口说明

实现将向用户发放资金，商户可调用该接口实现，从商户自己的payout账户的资金转给paynicorn app用户

接口地址

https://api.paynicorn.com/trade/customer/oauth/transaction/payout

接口参数

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

字段名	类型	填写要求	描述
orderId	String(64)	M	商户付款订单号
currency	String(3)	M	币种代码(CurrencyCode)，参见附录 国家币种对照表
amount	String(32)	M	金额
countryCode	String(2)	M	国家代码(CountryCode)，参见附录 国家币种对照表
name	String(64)	M	收款人名字
openId	String(64)	M	OpenId

响应参数

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

查询交易结果接口 (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	交易处理完成时间

异步通知接口 (Postback)

接口说明

异步交易结果通知，收款和授权支付不能立即获取交易结果的，在交易状态发生改变的时候，paynicorn会调用商户设置的异步通知结果，将最新的订单状态通知商户服务端。

接口地址

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

请求参数

响应参数

参数名	类型	填写要求	备注
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	原始交易凭证

警告

商户收到回调通知后，需要按照 Paynicorn 的要求进行响应

HttpsStatus=200代表接受到通知并返回字符串success_{txnId}，其他代表通知失败

没有返回success_{txnId}的会继续通知，直到成功，最多10次，通知间隔时间按照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	折扣

获取VAS报表数据 (VasReport)

接口说明

获取VAS交易报表数据

接口地址

https://api.paynicorn.com/trade/merchant/report/query

请求参数

字段填写要求 M:mandatory 必填，O：optional 可选择的

字段名	类型	填写要求	描述
appKey	String	M	产品appKey
countries	Array<String>	O	国家编码， 国家币种对照表
operators	Array<String>	O	运营商，参考地址
pageNo	String	M	分页参数，当前页码
pageSize	String	M	分页参数, 每页条数
apkPackage	String	O	包名
districtChannel	String	O	分发渠道, 参见附录 分发渠道
metric	String	M	分组字段report_day,country,cp_id,api_key,apk_package,district_channel,operator
startDay	String	M	开始日期
endDay	String	M	结束日期

响应参数

字段名	类型	填写要求	备注
code	String(16)	M	状态码参见 状态码
message	String(256)	M	消息参见 状态码
data	Array<Content>	O	VAS交易分析列表

Content

字段名	类型	填写要求	描述
amountSumUsd	Double	M	美金销售额
dau	Integer	O	DAU
estimatedIncome	Double	O	预估收益
metric	String	M	聚合字段
metricValue	String	M	聚合数据值
operatorDivide	Double	O	运营商分成
paySuccessCount	Integer	O	成功总笔数
payUserCount	Integer	O	支付用户数量
platformDivide	Double	O	平台分成
realizationEfficiency	Double	O	变现效率
smsSuccessCount	Integer	O	订单总笔数

根据cpid拉取该商户下所有的应用的appkey

接口说明

根据cpid拉取该商户下所有的应用的appkey

接口地址

https://api.paynicorn.com/trade/merchant/report/cpinfo/queryAppKeyList

请求参数

字段填写要求 M:mandatory 必填，O：optional 可选择的

字段名	类型	填写要求	描述
cpId	String	M	cpId

响应参数

字段名	类型	填写要求	备注
code	String(16)	M	状态码参见 状态码
message	String(256)	M	消息参见 状态码
data	Array<String>	O	appKey列表

VAS交易数据

接口说明

根据分发渠道参数查询VAS交易流水的接口

接口地址

https://api.paynicorn.com/trade/merchant/report/getListByDistrictChannel

请求参数

字段填写要求 M:mandatory 必填，O：optional 可选择的

字段名	类型	填写要求	描述
districtChannel	Integer	M	分发渠道枚举 0:plamstore,1:AHA,2:游戏,3:分发,4:AHA快游戏,5:游戏-aha,6:游戏-palm,99:SDK测试
startTime	String	M	开始时间，格式:yyyy-MM-dd (开始时间和结束时间间隔不超过30天)
endTime	String	M	结束时间，格式:yyyy-MM-dd (开始时间和结束时间间隔不超过30天)

响应参数

字段名	类型	填写要求	备注
code	String(16)	M	状态码参见 状态码
message	String(256)	M	消息参见 状态码
data	Array<Content>	O	VAS交易列表

Content

字段名	类型	填写要求	描述
packageName	String	M	包名
countryCode	String	M	国家码
usdSum	String	M	美金交易金额

话费充值接口

接口说明

给指定手机号充值话费

接口地址

https://api.paynicorn.com/trade/topup/api/topup

请求方式：post

请求参数

参数名	参数类型	填写要求	描述
appKey	string	M	商户应用Appkey
transId	string	M	商户交易号
countryCode	string	M	国家码
bizType	string	M	业务类型 说明：固定是m_topup 话费
operatorCode	string	M	运营商编码(根据手机号查询运营商接口获取)
benefitNo	string	M	要充值的号码(不需要国家码)
amount	BigDecimal	M	充值金额(支持的金额以paynicorn 运营提供为准)
memo	string	O	备注
currency	string	O	充值币种（默认本币）

响应参数

参数名	参数类型	填写要求	备注
code	int	M	请求处理的标识
msg	string	M	请求处理信息
result	JsonObj	O	返回结果

result对象参数

参数名	参数类型	填写要求	描述
transId	string	M	交易ID
statusCode	string	M	交易状态
description	string	M	描述

示例

Request

{
    "appKey": "p3k0Y312LzX6Dv87lVa1",
    "transId": "123456789",
    "countryCode": "NG",
    "bizType": "m_topup",
    "operatorCode": "9mobile",
    "benefitNo": "08184123954",
    "amount": 100,
    "memo": "话费充值",
    "currency": "USD"
}

Response

{
    "code": 1200,
    "msg": "success",
    "result": {
        "transId": "123456789",
        "statusCode": "0",
        "description": "transaction in processing"
    }
}

充值交易查询接口

接口说明

查询交易状态及交易详情信息接口

接口地址

https://api.paynicorn.com/trade/topup/api/query

请求方法：post

请求参数

参数名	参数类型	填写要求	描述
appKey	string	M	商户应用ID
transId	string	M	商户交易号

响应参数

参数名	参数类型	填写要求	描述
code	int	M	请求处理的标识
msg	string	M	请求处理信息
result	JsonObj	O	返回结果

result参数

参数名	参数类型	填写要求	描述
transId	string	M	交易ID
statusCode	string	M	交易状态
description	string	M	描述
countryCode	string	M	国家码
bizType	string	O	业务类型,冗余字段，兼容老版本
operatorCode	string	M	运营商编码
benefitNo	string	M	要充值的号码
amount	BigDecimal	M	充值金额
packageId	string	O	流量套餐ID，冗余字段，兼容老版本
packageDesc	string	M	流量套餐描述
memo	string	M	备注
tokenData	string	O	返回给用户的token数据（电费）,冗余字段，兼容老版本

示例

Request

{
  "appKey": "p3k0Y312LzX6Dv87lVa1",
  "transId": "1234567890"
}

Response

{
    "code": 1200,
    "msg": "success",
    "result": {
        "transId": "1234567890",
        "statusCode":"1",
        "description":"transaction successful",
        "countryCode": "NG",
        "bizType": "m_topup",
        "operatorCode": "9mobile",
        "benefitNo": "08184123954",
        "packageId": "3199"
    }
}

查询美元汇率

接口说明

查询美元对其他币种汇率

接口地址

https://api.paynicorn.com/trade/currency/queryall

请求方法get

请求参数

无

响应参数

参数名	参数类型	填写要求	描述
timestamp	int	M	请求处理时间
source	string	M	源币种(目前只支持USD)
date	string	M	汇率日期
quotes	JsonObj	M	汇率列表

示例

Request

无

Response

{
timestamp: 1669852815,
source: "USD",
date: "2022-12-01",
quotes: {
  USDAED: 3.673096,
  USDAFN: 88.00051,
  USDALL: 112.04978,
  USDAMD: 394.49316,
  USDANG: 1.801792,
  USDAOA: 506.778,
  USDARS: 167.29599,
  USDAUD: 1.470707,
  USDAWG: 1.8025,
  USDAZN: 1.70203,
  USDBAM: 1.887484,
  USDBBD: 2.01851,
  USDBDT: 101.625946,
  USDBGN: 1.880171,
  USDBHD: 0.376977,
  USDBIF: 2057,
  USDBMD: 1,
  USDBND: 1.366038,
  USDBOB: 6.922825,
  USDBRL: 5.185427,
  USDBSD: 0.999701,
  USDBTC: 0.000058287394,
  USDBTN: 81.34654,
  USDBWP: 12.833945,
  USDBYN: 2.524778,
  USDBYR: 19600,
  USDBZD: 2.015036,
  USDCAD: 1.34145,
  USDCDF: 2053.5005,
  USDCHF: 0.94399,
  USDCLF: 0.032273,
  USDCLP: 890.49866,
  USDCNY: 7.079098,
  USDCOP: 4830.05,
  USDCRC: 596.62616,
  USDCUC: 1,
  USDCUP: 26.5,
  USDCVE: 107.409874,
  USDCZK: 23.356098,
  USDDJF: 177.72017,
  USDDKK: 7.135103,
  USDDOP: 54.749958,
  USDDZD: 138.3823,
  USDEGP: 24.553802,
  USDERN: 15,
  USDETB: 53.449898,
  USDEUR: 0.95935,
  USDFJD: 2.20365,
  USDFKP: 0.833742,
  USDGBP: 0.828127,
  USDGEL: 2.709428,
  USDGGP: 0.833742,
  USDGHS: 14.501907,
  USDGIP: 0.833742,
  USDGMD: 62.000053,
  USDGNF: 8795,
  USDGTQ: 7.823112,
  USDGYD: 209.14679,
  USDHKD: 7.804855,
  USDHNL: 24.770071,
  USDHRK: 7.240965,
  USDHTG: 140.4584,
  USDHUF: 392.31955,
  USDIDR: 15637.5,
  USDILS: 3.449914,
  USDIMP: 0.833742,
  USDINR: 81.30555,
  USDIQD: 1460,
  USDIRR: 42450,
  USDISK: 143.57977,
  USDJEP: 0.833742,
  USDJMD: 153.9838,
  USDJOD: 0.709299,
  USDJPY: 137.3605,
  USDKES: 122.55028,
  USDKGS: 84.4482,
  USDKHR: 4133.9995,
  USDKMF: 477.2498,
  USDKPW: 899.9047,
  USDKRW: 1306.3798,
  USDKWD: 0.30739,
  USDKYD: 0.833193,
  USDKZT: 468.93112,
  USDLAK: 17320,
  USDLBP: 1516.6195,
  USDLKR: 368.413,
  USDLRD: 154.05042,
  USDLSL: 16.959995,
  USDLTL: 2.95274,
  USDLVL: 0.60489,
  USDLYD: 4.897688,
  USDMAD: 10.713499,
  USDMDL: 19.503962,
  USDMGA: 4360,
  USDMKD: 59.19027,
  USDMMK: 2099.392,
  USDMNT: 3424.7883,
  USDMOP: 8.03322,
  USDMRO: 356.99982,
  USDMUR: 44.349873,
  USDMVR: 15.329961,
  USDMWK: 1029.4956,
  USDMXN: 19.26735,
  USDMYR: 4.477795,
  USDMZN: 63.830173,
  USDNAD: 16.959755,
  USDNGN: 443.93994,
  USDNIO: 36.390152,
  USDNOK: 9.828445,
  USDNPR: 130.15486,
  USDNZD: 1.58387,
  USDOMR: 0.385008,
  USDPAB: 0.999701,
  USDPEN: 3.832495,
  USDPGK: 3.514953,
  USDPHP: 56.40496,
  USDPKR: 224.00002,
  USDPLN: 4.479064,
  USDPYG: 7198.6104,
  USDQAR: 3.6405,
  USDRON: 4.728594,
  USDRSD: 112.54012,
  USDRUB: 61.025005,
  USDRWF: 1061,
  USDSAR: 3.759412,
  USDSBD: 8.223823,
  USDSCR: 12.99729,
  USDSDG: 568.5075,
  USDSEK: 10.481435,
  USDSGD: 1.359375,
  USDSHP: 1.3774,
  USDSLE: 18.308893,
  USDSLL: 18330,
  USDSOS: 569.5037,
  USDSRD: 31.630503,
  USDSTD: 20697.98,
  USDSVC: 8.747726,
  USDSYP: 2512.3792,
  USDSZL: 16.959745,
  USDTHB: 35.080048,
  USDTJS: 10.047338,
  USDTMT: 3.5,
  USDTND: 3.261503,
  USDTOP: 2.362799,
  USDTRY: 18.634974,
  USDTTD: 6.774496,
  USDTWD: 30.792976,
  USDTZS: 2332.0005,
  USDUAH: 36.913754,
  USDUGX: 3743.8357,
  USDUYU: 39.525738,
  USDUZS: 11220,
  USDVEF: 1078295.5,
  USDVES: 10.940798,
  USDVND: 24645,
  USDVUV: 119.15339,
  USDWST: 2.734576,
  USDXAF: 633.0745,
  USDXAG: 0.044737,
  USDXAU: 0.000564,
  USDXCD: 2.70255,
  USDXDR: 0.760671,
  USDXOF: 633.4985,
  USDXPF: 116.050316,
  USDYER: 250.37497,
  USDZAR: 17.14145,
  USDZMK: 9001.202,
  USDZMW: 17.104736,
  USDZWL: 321.9996
}
}

手机号查询充值运营商

接口说明

根据手机号查询手机号归属的运营商

接口地址

https://api.paynicorn.com/trade/topup/api/queryOperatorCode

请求方法：post

请求参数

参数名	参数类型	填写要求	描述
nationalPhoneNo	string	M	手机号
countryCode	string	M	国家码

响应参数

参数名	参数类型	填写要求	描述
code	int	M	请求处理的标识
msg	string	M	请求处理信息
result	JsonObj	M	返回结果

result对象参数

参数名	参数类型	填写要求	描述
countryCode	string	M	国家编码
currency	string	M	币种编码
areaCode	string	M	国家区号
operatorCode	string	M	PAYNICORN运营商编码
operatorName	string	M	运营商全程

示例

Request

  {
  "countryCode": "NG",
  "nationalPhoneNo": "07012345678"
  }

Response

  {
  "code": 1200,
  "msg": "success",
      "result": {
        "countryCode": "NG",
        "currency": "NGN",
        "areaCode": "234",
        "operatorCode": "NG_AIRTEL",
        "operatorName": "Airtel Nigeria"
      }
  }

查询话费充值产品接口

接口说明

查询paynicorn支持的流量充值产品

接口地址

https://api.paynicorn.com/trade/topup/api/queryGoods

方法: POST

描述: 查询话费产品

请求参数

参数位置	参数名	参数类型	是否必须	描述
Body	appKey	string	Y	商户应用Appkey
Body	productCode	string	Y	产品类型（data_topup 流量充值）
Body	operatorCode	string	N	运营商编码
Body	countryCode	string	N	国家码

响应参数

参数位置	参数名	参数类型	描述
Body	code	int	请求处理的标识
Body	msg	string	请求处理信息
Body	result	JsonObj	返回结果

result对象参数

参数位置	参数名	参数类型	描述
result	productCode	string	产品类型
result	countryCode	string	国家
result	operatorCode	string	运营商编码
result	goodsId	string	产品ID
result	rechargeAmount	BigDecimal	固定充值金额
result	rechargeMinAmount	BigDecimal	区间充值最小金额
result	rechargeMaxAmount	BigDecimal	区间充值最大金额
result	rechargeCurrency	string	充值币种
result	buyingType	string	购买方式(固定金额:FIXED, 区间金额:RANGE)

示例

Request

{
    "appKey": "p3k0Y312LzX6Dv87lVa1",
    "productCode":"m_topup",  
    "countryCode":"UG",       
    "operatorCode":""        
}

Response

{
    "code": 1200,
    "msg": "success",
    "result": [
        {
            "id": 36,
            "productCode": "m_topup",
            "countryCode": "UG",
            "operatorCode": "UG_MTN",
            "goodsId": "UG78341450565",
            "rechargeAmount": 10.00,
            "rechargeMinAmount": 0.00,
            "rechargeMaxAmount": 0.00,
            "rechargeCurrency": "UGX",
            "buyingType": "FIXED"
        }
    ]
}

查询流量充值产品接口

接口说明

查询paynicorn支持的流量充值产品

接口地址

post https://api.paynicorn.com/trade/topup/api/data/queryGoods

请求参数

参数名	参数类型	填写要求	描述
appKey	string	M	商户应用Appkey
countryCode	string	O	国家码，查询指定国家流量产品
productCode	string	M	产品类型（冗余字段，固定data_topup 流量充值）
operatorCode	string	O	运营商编码，查询指定运营商流量产品

响应参数

参数名	参数类型	填写要求	描述
code	int	M	请求处理的标识
msg	string	M	请求处理信息
result	JsonObj	O	返回结果

result对象参数

参数名	参数类型	填写要求	描述
productCode	string	M	产品类型
countryCode	string	M	国家
operatorCode	string	M	运营商编码
goodsId	string	M	产品ID
goodsDesc	string	M	产品描述
amount	string	M	产品售价

示例

Request

{
    "appKey": "p3k0Y312LzX6Dv87lVa1",
    "countryCode": "NG",
    "productCode": "data_topup",
    "operatorCode": "NG_MTN"
}

Response

{
    "code": 1200,
    "msg": "success",
    "result": {
          "productCode": "data_topup",
          "countryCode": "NG",
          "operatorCode": "NG_MTN",
          "goodsId": "NG72347153587",
          "goodsDesc": "100MB/7Day",
          "amount": 100.0
    }
}

流量充值接口

接口说明

给指定手机充值流量

接口地址

post https://api.paynicorn.com/trade/topup/api/data/topup

请求参数

参数名	参数类型	填写说明	描述
appKey	string	M	商户应用Appkey
transId	string	M	商户交易号
benefitNo	string	M	要充值的号码
goodsId	string	M	产品ID(根据流量产品查询接口返回或者联系运营获取支持列表)
memo	string	O	备注

响应参数

参数名	参数类型	填写要求	描述
code	int	M	请求处理的标识
msg	string	M	请求处理信息
result	JsonObj	O	返回结果

result对象参数

参数名	参数类型	填写要求	描述
transId	string	M	交易ID
orderId	string	M	系统订单号
statusCode	string	M	交易状态
description	string	M	描述

示例

Request

{
    "appKey": "p3k0Y312LzX6Dv87lVa1",
    "transId": "123456789",
    "benefitNo": "08184123954",
    "goodsId": "NG72347153587",
    "memo": "流量充值"
}

Response

{
    "code": 1200,
    "msg": "success",
    "result": {
        "transId": "123456789",
        "orderId": "1057312678641614851",
        "statusCode": "0",
        "description": "transaction in processing"
    }
}

流量充值交易查询接口

接口说明

查询流量充值状态及交易详情信息

接口地址

post https://api.paynicorn.com/trade/topup/api/data/query

请求参数

参数名	参数类型	填写要求	描述
appKey	string	M	商户应用ID
transId	string	M	商户交易号

响应参数

参数名	参数类型	填写要求	描述
code	int	M	请求处理的标识
msg	string	M	请求处理信息
result	JsonObj	O	返回结果

result参数

参数名	参数类型	填写要求	描述
transId	string	M	交易ID
statusCode	string	M	交易状态
countryCode	string	M	国家码
operatorCode	string	M	运营商编码
benefitNo	string	M	要充值的号码
goodsId	string	M	流量套餐ID
goodsDesc	string	M	流量套餐描述
memo	string	M	备注

示例

Request

{
  "appKey": "p3k0Y312LzX6Dv87lVa1",
  "transId": "1234567890"
}

Response

{
    "code": 1200,
    "msg": "success",
    "result": {
        "transId": "1234567890",
        "statusCode":"1",
        "countryCode": "NG",
        "operatorCode": "9mobile",
        "benefitNo": "08184123954",
        "goodsId": "NG72347153587",
        "goodsDesc": "100MB/7Day"
    }
}

充值异步通知（recharge_callback）

接口说明

充值系统完成充值流程后，会回调商户在后台配置的商户回调接口，通知商户充值结果以及充值详情。 注意：回调接口URL须为外部可正常访问，且不带后缀参数的URL地址，接收请求类型为POST

接口地址

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

请求参数

响应参数

参数名	类型	填写要求	备注
orderNo	String	M	充值订单ID
originOrderNo	String	M	源订单ID(接入方订单ID)
status	Integer	M	回调状态(0.充值中，1.成功，2.失败)
timestamp	Integer	M	订单完成时间

警告

充值完成后，充值后台会把充值相关信息发送给商户，商户需要接收处理该回调通知请求，并返回正确应答。 如果后台接收到的商户应答不符合规范或超时，后台则判定通知失败，并且会按一定的间隔定期重新发起通知。 通知的间隔频率为5s/1min/8min/27min/64min…… 总计14次, 回调的最大时间间隔36小时， 超过36小时未响应则不再回调。如果遇到重复的回调，接入方需要保证结果的幂等性。