话费充值

更新时间：2024.06.25 09:52:42

话费充值

话费充值接口

接口说明

给指定手机号充值话费。

异步通知：

成功的交易有异步通知，但失败/处理中的交易不会callback给商户，需要商户主动查询交易结果。

接口地址

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

请求方式：post

请求参数

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

响应参数

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

参数名	参数类型	填写要求	描述
transId	string	M	商户订单 ID
orderId	string	M	话费充值订单号 ID
statusCode	string	M	交易状态，0: 充值处理中，1: 充值成功，2：充值失败
description	string	M	描述

报文示例

Request Body

{
    "transId":"V3T1719295709739",
    "appKey": "T90B124766qU95d385O4",
    "countryCode": "NG",
    "bizType": "m_topup",
    "operatorCode": "NG_AIRTEL",
    "benefitNo": "9073542823",
    "amount": 1000,
    "memo": ""
}

Response

{
  "code": 1200,
  "msg": "success",
  "result": {
    "transId": "V3T1712672262694", //商户订单ID
    "statusCode": "0",
    "description": "transaction in process",
    "orderId": 12418046125113395 //话费充值订单号ID
  }
}

注意：

若同步响应返回下述错误码和错误消息，商户可以主动关单：

code 错误代码	msg 错误消息
4001	invalid signature
4002	invalid appId
4003	unsupported business
4004	unsupported amount
4005	invalid packageId
4006	invalid benefitNo
4007	invalid transId
4008	transId is null
4009	transId already exist
4010	phone number is empty
4011	unknown operator
4012	no active wallet of this currency
4013	Insufficient balance
4014	Exceed the minute limit
4015	Exceed the daily times limit
4016	channel disable
4017	channelCode is null
4018	channelCode is error
4019	sp product is null
4020	appKey is null
4021	callbackUrl is null
4022	callback url error
4023	secret key is null
4024	unknown appKey
4025	sp order mapping error
4027	Pleas check product information
4027	Please activate the product function
4028	Paynicorn CP Insufficient balance
4030	Recharge phone error
4031	Recharge country error
4032	Recharge operator error
4033	Exceed operator the minute limit

若同步响应返回的结果如下，则可以结合业务逻辑进行判断或者查询此订单的状态来决定是否要关闭此订单：

code 错误代码	msg 错误消息
4026	merchant Overbooking

上述两种情况的示例报文响应：

{
  "code": 4028, "msg": "Paynicorn CP Insufficient balance"
}

充值交易查询接口

接口说明

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

接口地址

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数据（电费）,冗余字段，兼容老版本

报文示例

RequestBody

{
  "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"
  }
}

若返回的响应如下，本订单可以被主动关闭：

{
  "code": 4007,
  "msg": "invalid transId"
}

{
  "code": 4008,
  "msg": "transId is null"
}

手机号查询充值运营商

接口说明

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

接口地址

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	产品类型
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 Body

{
    "appKey": "T90B124766qU95d385O4",
    "countryCode": "NG",
    "productCode": "m_topup"
}

Response

{
        "code": 1200,
        "msg": "success",
        "result": [{
                "id": 111,
                "productCode": "m_topup",
                "countryCode": "NG",
                "operatorCode": "NG_9MOBILE",
                "goodsId": "NG75850224649",
                "rechargeAmount": 0.00,
                "rechargeMinAmount": 5.00,
                "rechargeMaxAmount": 50000.00,
                "rechargeCurrency": "NGN",
                "buyingType": "RANGE"
        }, {
                "id": 112,
                "productCode": "m_topup",
                "countryCode": "NG",
                "operatorCode": "NG_AIRTEL",
                "goodsId": "NG76268129842",
                "rechargeAmount": 0.00,
                "rechargeMinAmount": 50.00,
                "rechargeMaxAmount": 199999.00,
                "rechargeCurrency": "NGN",
                "buyingType": "RANGE"
        }, {
                "id": 113,
                "productCode": "m_topup",
                "countryCode": "NG",
                "operatorCode": "NG_GLOMOBILE",
                "goodsId": "NG76268155966",
                "rechargeAmount": 0.00,
                "rechargeMinAmount": 10.00,
                "rechargeMaxAmount": 50000.00,
                "rechargeCurrency": "NGN",
                "buyingType": "RANGE"
        }, {
                "id": 114,
                "productCode": "m_topup",
                "countryCode": "NG",
                "operatorCode": "NG_MTN",
                "goodsId": "NG76268187529",
                "rechargeAmount": 0.00,
                "rechargeMinAmount": 50.00,
                "rechargeMaxAmount": 200000.00,
                "rechargeCurrency": "NGN",
                "buyingType": "RANGE"
        }, {
                "id": 864,
                "productCode": "m_topup",
                "countryCode": "NG",
                "operatorCode": "NG_MTN",
                "goodsId": "NG86726385341",
                "rechargeAmount": 50.00,
                "rechargeMinAmount": 0.00,
                "rechargeMaxAmount": 0.00,
                "rechargeCurrency": "NGN",
                "buyingType": "FIXED"
        }, {
                "id": 865,
                "productCode": "m_topup",
                "countryCode": "NG",
                "operatorCode": "NG_AIRTEL",
                "goodsId": "NG86726395639",
                "rechargeAmount": 50.00,
                "rechargeMinAmount": 0.00,
                "rechargeMaxAmount": 0.00,
                "rechargeCurrency": "NGN",
                "buyingType": "FIXED"
        }, {
                "id": 866,
                "productCode": "m_topup",
                "countryCode": "NG",
                "operatorCode": "NG_GLOMOBILE",
                "goodsId": "NG86726402194",
                "rechargeAmount": 50.00,
                "rechargeMinAmount": 0.00,
                "rechargeMaxAmount": 0.00,
                "rechargeCurrency": "NGN",
                "buyingType": "FIXED"
        }, {
                "id": 867,
                "productCode": "m_topup",
                "countryCode": "NG",
                "operatorCode": "NG_9MOBILE",
                "goodsId": "NG86726416039",
                "rechargeAmount": 50.00,
                "rechargeMinAmount": 0.00,
                "rechargeMaxAmount": 0.00,
                "rechargeCurrency": "NGN",
                "buyingType": "FIXED"
        }, {
                "id": 868,
                "productCode": "m_topup",
                "countryCode": "NG",
                "operatorCode": "NG_MTN",
                "goodsId": "NG86726440785",
                "rechargeAmount": 100.00,
                "rechargeMinAmount": 0.00,
                "rechargeMaxAmount": 0.00,
                "rechargeCurrency": "NGN",
                "buyingType": "FIXED"
        }, {
                "id": 869,
                "productCode": "m_topup",
                "countryCode": "NG",
                "operatorCode": "NG_AIRTEL",
                "goodsId": "NG86726447520",
                "rechargeAmount": 100.00,
                "rechargeMinAmount": 0.00,
                "rechargeMaxAmount": 0.00,
                "rechargeCurrency": "NGN",
                "buyingType": "FIXED"
        }, {
                "id": 870,
                "productCode": "m_topup",
                "countryCode": "NG",
                "operatorCode": "NG_GLOMOBILE",
                "goodsId": "NG86726452919",
                "rechargeAmount": 100.00,
                "rechargeMinAmount": 0.00,
                "rechargeMaxAmount": 0.00,
                "rechargeCurrency": "NGN",
                "buyingType": "FIXED"
        }, {
                "id": 871,
                "productCode": "m_topup",
                "countryCode": "NG",
                "operatorCode": "NG_9MOBILE",
                "goodsId": "NG86726459135",
                "rechargeAmount": 100.00,
                "rechargeMinAmount": 0.00,
                "rechargeMaxAmount": 0.00,
                "rechargeCurrency": "NGN",
                "buyingType": "FIXED"
        }, {
                "id": 887,
                "productCode": "m_topup",
                "countryCode": "NG",
                "operatorCode": "NG_MTN",
                "goodsId": "NG90954544534",
                "rechargeAmount": 500.00,
                "rechargeMinAmount": 0.00,
                "rechargeMaxAmount": 0.00,
                "rechargeCurrency": "NGN",
                "buyingType": "FIXED"
        }, {
                "id": 888,
                "productCode": "m_topup",
                "countryCode": "NG",
                "operatorCode": "NG_AIRTEL",
                "goodsId": "NG90954553494",
                "rechargeAmount": 500.00,
                "rechargeMinAmount": 0.00,
                "rechargeMaxAmount": 0.00,
                "rechargeCurrency": "NGN",
                "buyingType": "FIXED"
        }, {
                "id": 889,
                "productCode": "m_topup",
                "countryCode": "NG",
                "operatorCode": "NG_9MOBILE",
                "goodsId": "NG90954558552",
                "rechargeAmount": 500.00,
                "rechargeMinAmount": 0.00,
                "rechargeMaxAmount": 0.00,
                "rechargeCurrency": "NGN",
                "buyingType": "FIXED"
        }, {
                "id": 890,
                "productCode": "m_topup",
                "countryCode": "NG",
                "operatorCode": "NG_GLOMOBILE",
                "goodsId": "NG90954562643",
                "rechargeAmount": 500.00,
                "rechargeMinAmount": 0.00,
                "rechargeMaxAmount": 0.00,
                "rechargeCurrency": "NGN",
                "buyingType": "FIXED"
        }, {
                "id": 934,
                "productCode": "m_topup",
                "countryCode": "NG",
                "operatorCode": "NG_9MOBILE",
                "goodsId": "NG10207839146",
                "rechargeAmount": 200.00,
                "rechargeMinAmount": 0.00,
                "rechargeMaxAmount": 0.00,
                "rechargeCurrency": "NGN",
                "buyingType": "FIXED"
        }, {
                "id": 935,
                "productCode": "m_topup",
                "countryCode": "NG",
                "operatorCode": "NG_AIRTEL",
                "goodsId": "NG10207846781",
                "rechargeAmount": 200.00,
                "rechargeMinAmount": 0.00,
                "rechargeMaxAmount": 0.00,
                "rechargeCurrency": "NGN",
                "buyingType": "FIXED"
        }, {
                "id": 936,
                "productCode": "m_topup",
                "countryCode": "NG",
                "operatorCode": "NG_GLOMOBILE",
                "goodsId": "NG10207855858",
                "rechargeAmount": 200.00,
                "rechargeMinAmount": 0.00,
                "rechargeMaxAmount": 0.00,
                "rechargeCurrency": "NGN",
                "buyingType": "FIXED"
        }, {
                "id": 937,
                "productCode": "m_topup",
                "countryCode": "NG",
                "operatorCode": "NG_MTN",
                "goodsId": "NG10207861851",
                "rechargeAmount": 200.00,
                "rechargeMinAmount": 0.00,
                "rechargeMaxAmount": 0.00,
                "rechargeCurrency": "NGN",
                "buyingType": "FIXED"
        }, {
                "id": 938,
                "productCode": "m_topup",
                "countryCode": "NG",
                "operatorCode": "NG_9MOBILE",
                "goodsId": "NG10207885019",
                "rechargeAmount": 1000.00,
                "rechargeMinAmount": 0.00,
                "rechargeMaxAmount": 0.00,
                "rechargeCurrency": "NGN",
                "buyingType": "FIXED"
        }, {
                "id": 939,
                "productCode": "m_topup",
                "countryCode": "NG",
                "operatorCode": "NG_AIRTEL",
                "goodsId": "NG10207889471",
                "rechargeAmount": 1000.00,
                "rechargeMinAmount": 0.00,
                "rechargeMaxAmount": 0.00,
                "rechargeCurrency": "NGN",
                "buyingType": "FIXED"
        }, {
                "id": 940,
                "productCode": "m_topup",
                "countryCode": "NG",
                "operatorCode": "NG_GLOMOBILE",
                "goodsId": "NG10207893411",
                "rechargeAmount": 1000.00,
                "rechargeMinAmount": 0.00,
                "rechargeMaxAmount": 0.00,
                "rechargeCurrency": "NGN",
                "buyingType": "FIXED"
        }, {
                "id": 941,
                "productCode": "m_topup",
                "countryCode": "NG",
                "operatorCode": "NG_MTN",
                "goodsId": "NG10207897749",
                "rechargeAmount": 1000.00,
                "rechargeMinAmount": 0.00,
                "rechargeMaxAmount": 0.00,
                "rechargeCurrency": "NGN",
                "buyingType": "FIXED"
        }]
}

充值异步通知（recharge_callback）

接口说明

充值系统完成充值流程后，会回调商户在后台配置的商户回调接口，通知商户充值结果以及充值详情。

请注意：

回调接口URL须为外部可正常访问，且不带后缀参数的URL地址，接收请求类型为 POST 。
本接口只对成功的话费充值交易发起回调通知，其余状态的交易需要商户主动查询交易结果。

接口地址

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

请求参数

响应参数

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

充值完成后，充值后台会把充值相关信息发送给商户，商户需要接收处理该回调通知请求，并返回正确应答。 HttpsStatus=200代表接受到通知并返回字符串success，其他代表通知失败。

针对通知失败的订单，没有重试机制。商户可主动通过充值交易查询接口查询最终结果。

报文示例

{
        "deductionAmount": 0.2400,
        "deductionCurrency": "USD",
        "orderNo": "12428686363427123",
        "originOrderNo": "9242868607189027501",
        "status": 1, //0: 充值处理中，1: 充值成功，2：充值失败
        "timestamp": 1717745928,
        "verified": false
}

上一篇：付款产品

下一篇：流量充值

话费充值

话费充值 #

话费充值接口 #

接口说明 #

接口地址 #

请求方式：post #

请求参数 #

响应参数 #

报文示例 #

充值交易查询接口 #

接口说明 #

接口地址 #

请求方法：post #

请求参数 #

响应参数 #

报文示例 #

手机号查询充值运营商 #

接口说明 #

接口地址 #

请求方法：post #

请求参数 #

响应参数 #

报文示例 #

查询话费充值产品接口 #

接口说明 #

接口地址 #

方法: POST #

描述: 查询话费产品 #

请求参数 #

响应参数 #

报文示例 #

充值异步通知（recharge_callback） #

接口说明 #

接口地址 #

请求参数 #

响应参数 #

报文示例 #

话费充值

话费充值接口

接口说明

接口地址

请求方式：post

请求参数

响应参数

报文示例

充值交易查询接口

接口说明

接口地址

请求方法：post

请求参数

响应参数

报文示例

手机号查询充值运营商

接口说明

接口地址

请求方法：post

请求参数

响应参数

报文示例

查询话费充值产品接口

接口说明

接口地址

方法: POST

描述: 查询话费产品

请求参数

响应参数

报文示例

充值异步通知（recharge_callback）

接口说明

接口地址

请求参数

响应参数

报文示例