PG 定期支付¶

“PG 经常付款”是指用户一旦在PG 付款框中登记了付款方法,应用程序服务器将在适合他们时要求从该付款方法付款。它用来定期支付同样的产品,例如每月的金额产品。

此文档描述了“ PG 经常支付” 的集成过程, 以及如何使用 API 从应用程序服务器调用。主要API列表如下.

查看支付方法列表: 查看经常性付款的支付方法
订阅登记: 第一次付款的付款方法登记和付款页
经常性费用: 下一个使用文件上的支付方法的支付请求
终止: 终止经常性付款

概述¶

计费周期和间隔由应用服务器管理. app服务器必须在产品持续期间要求付款,Hive不会在指定日期自动付款.

支持的PG和支付方法如下。未列出的PG和支付方法在连接蜂巢控制台时将不列入经常性支付列表.

Kakao Pay: Kakao Pay Easy Pay
达纳尔:信用卡
支付墙:国际信用卡;登记所需的买方电子邮件
NHN KCP:信用卡

对接流程¶

应用程序服务器检查并注册您的支付方法。一旦支付完毕,蜂巢服务器将向应用服务器发出支付通知,告知支付结果. 应用程序服务器存储order_id从第一次付款通知起作为发出订单号,然后用于经常性收费和注销请求。

在应用服务器上完成的PG支付整合流程如下.

请用户使用付款方法清单从应用程序服务器。
请求经常性付款登记使用用户选择的产品和支付方法。
在您的网页视图或浏览器中显示作为注册回复收到的HTML支付页面。
节省order_id会议日程和议程付款通知当用户登记支付方法并完成第一次支付时,从蜂巢服务器中获取。
请使用order_id您在下次结账时保存了重新支付与你的计费周期号。
根据一次性付款通知处理产品付款。
索取取消当你结束你的经常性支付。

第二轮投票结束后,您的订单号码将转至您的经常性收费答复和付款通知。在应用程序服务器中连接并管理您的初始订单ID和订单号.

如果用户关闭支付页面或未能注册,蜂巢服务器将不会发送支付通知.

准备工作¶

在蜂巢控制台设置您的支付方式和支付通知 URL,然后拨打API 。如果您在您的应用程序中设置了安全密钥, 您还需要准备认证符。

关联支付方式¶

从蜂巢控制台连接您的经常性支付方式到应用程序。见PG 设置说明如何设置它。

设置支付通知URL¶

注册应用程序服务器的 URL 以在蜂窝控制台 > 计费 > 付款设置 > PG 设置 > 附加设置。使用与普通 PG 付款相同的设置。见PG 支付通知设置需要更多信息,说明如何设置。

准备认证令牌¶

如果你已经设置安全密钥在应用程序中,您可以通过发行 OAuth 托肯.)中包含此符号。X-Access-Token在请求标题中调用API时。

通用请求和响应¶

所有API都使用POSTJSON格式中的方法和请求正文。不支持发送表单。通过将每个API的路径与您想要使用的环境的主机前缀来请求.

生产主机:https://hiveiap.qpyou.cn
沙盒主机:https://sandbox-hiveiap.qpyou.cn

Request header¶

格式化请求正文为Content-Type编辑X-Access-Token只有您在应用程序中设置了安全密钥, 才会验证。

字段	类型	需要吗?	说明
`Content-Type`	字符串	要求数	`application/json`
`X-Access-Token`	字符串	附加条件	OAuth 2.0 访问如果您在应用程序中设置了安全密钥, 需要键入

用户识别¶

在要求经常性收费或注销时,必须告知登记经常性付款的用户的信息。蜂巢服务器使用player_type和player_id一起确认你的身份

若为player_type这是v4通过蜂巢玩家身份vid改为:player_id如果v0,转发蜂巢成员UIDuid. player_type与vid_type在付款通知中。

player_id必须是数值为1或以上的数字字符串。如果一个非数字值被传递,10010002返回一个错误。

Response body¶

如果成功的话codeJSON 响应中的字符串"0"。该错误也响应 HTTP 状态代码200检查code在体内。 Token 认证失败响应 HTTP 状态代码401.

如果反复支付注册成功,则会返回支付页面HTML而不是JSON. 见登记册答复.

字段	类型	包含响应	说明
`code`	字符串	JSON的回应	结果码.`"0"`成功,见错误代码其他数值
`message`	字符串	JSON的回应	结果消息,包括发生错误的原因,内部错误消息是`Internal server error`

共同成功对策的例子包括:

"杰森"("Json")

```json
{ "code": "0", "message": "SUCCESS" }
```

支付方式列表查询API¶

查看您的经常性支付方法。显示列表中按数组排列的付款方法,并将用户所选项目的标识符传递给经常性的付款登记请求。

Request info¶

请求路径是/v2/payment/recurring/methods。请求方法和授权标题遵循共同请求和答复.

生产 URL:https://hiveiap.qpyou.cn/v2/payment/recurring/methods
沙盒 URL :https://sandbox-hiveiap.qpyou.cn/v2/payment/recurring/methods

Request body¶

水平价格是您为产品设定的货币价格。如果您指定market_pid,它只返回能够以该货币支付的支付方法,并按产品定出分级价格。

若为country省略,国家由请求服务器的IP决定,因此建议通过用户的国别代码.

字段	类型	需要吗?	说明
`appid`	字符串	要求数	应用程序标识
`market_pid`	字符串	选择	产品标识. 用于按照产品分级价格所在的货币过滤支付方法
`country`	字符串	选择、建议	用户国家代码. ISO 3166-1 α-2格式
`language`	字符串	选择	支付方法显示名称语言. 默认为`en`

下面是要求检查产品支付方法的正文item08用于韩国用户。

"杰森"("Json")

```json
{ "appid": "com.com2us.example.normal.freefull.google.global.android.common", "market_pid": "item08", "country": "KR", "language": "ko" }
```

Response body¶

成功对策包括:共同反应领域和数组payment_methods。数组中的每个项目都是PG和支付方法信息。

字段	类型	包含位置	说明
`payment_methods`	矩阵	反应机构	经常性支付方法清单. 序列是显示顺序
`agency_id`	整数	`payment_methods[]`	PG 标识符. 照原样转发经常性入学申请
`agency_code`	字符串	`payment_methods[]`	PG码.`kakaopay`, `danal_tpay`, `paymentwall`, `kcp_billing`
`agency_name`	字符串	`payment_methods[]`	PG 名称
`pay_method`	字符串	`payment_methods[]`	支付方法代码.`kakaopay`, `card`
`payment_method_id`	整数	`payment_methods[]`	付款方法标识符。按原样转发经常性付款登记申请
`payment_method_name`	字符串	`payment_methods[]`	基于`language`
`icon_url`	字符串	`payment_methods[]`	支付方法图标 URL
`currency`	字符串	`payment_methods[]`	支付货币

下面是回复KakaoPay支付方法的例子。https://…输入icon_url是一个略去实际 URL 的标记。

"杰森"("Json")

```json
{
  "code": "0",
  "message": "SUCCESS",
  "payment_methods": [
    { "agency_id": 3, "agency_code": "kakaopay", "agency_name": "카카오페이", "pay_method": "kakaopay",
      "payment_method_id": 472, "payment_method_name": "카카오페이", "icon_url": "https://…", "currency": "KRW" }
  ]
}
```

回返情况10010003如果找不到应用程序或物品,或者检查了出售的物品。如果没有符合国家和产品货币标准的经常性付款方法,10010005将返回。

定期支付注册API¶

它请求支付页面HTML,以便用户可以注册支付方法,进而进行第一次支付. 应用程序服务器仍然会在您的网页视图或浏览器中显示收到的 HTML 。

在支付页面上完成注册后,您将会看到蜂巢结果屏幕. 第一次付款的结果将作为付款通知转交应用服务器。

Request info¶

请求路径是/v2/payment/recurring/register。请求方法和授权标题遵循共同请求和答复.

生产 URL:https://hiveiap.qpyou.cn/v2/payment/recurring/register
沙盒 URL :https://sandbox-hiveiap.qpyou.cn/v2/payment/recurring/register

Request body¶

查看支付方法清单,包括market_pid,并转发agency_id和payment_method_id列入答复。country还应传递与查阅清单时相同的值。

字段	类型	需要吗?	说明
`appid`	字符串	要求数	应用程序标识
`market_pid`	字符串	要求数	要订阅的产品标识。在所有计费周期使用相同的商品
`server_id`	字符串	要求数	App 服务器 ID, 在所有时间的付款通知中发送
`player_id`	字符串	要求数	用户编号. 见识别用户
`player_type`	字符串	要求数	用户类型.`v4`或`v0`
`agency_id`	整数	要求数	支付方法的 PG 标识符列表查询回复
`payment_method_id`	整数	要求数	付款方法识别符付款方法清单查询答复
`email`	字符串	附加条件	买家邮件. 需要支付墙壁,没有使用其他 PG
`iap_payload`	字符串	选择	需要转发到应用程序服务器的更多信息。将在付款通知中通报所有计费周期,不得改为经常性收费请求
`country`	字符串	选择、建议	用户的国家代码. 它应该与查询列表时传递的值相同,如果省略,则由请求服务器的IP确定
`language`	字符串	选择	支付页面的语言和结果屏幕. 默认为`en`

下面是您要求与Kakao Pay登记经常性付款的正文。

"杰森"("Json")

```json
{
  "appid": "com.com2us.example.normal.freefull.google.global.android.common",
  "market_pid": "item08", "server_id": "kr",
  "player_id": "20000032552", "player_type": "v4",
  "agency_id": 3, "payment_method_id": 472,
  "iap_payload": "{\"character\":\"abc\"}",
  "country": "KR", "language": "ko"
}
```

Response body¶

请检查一下Content-Type在答复标题中,由于答复格式因登记请求的成功而异。应用程序决定当请求失败时, 文本用户会看到什么。

结果	HTTP 状态代码	内容类型	反应处理
成绩	`200`	`text/html`	显示已收付款页 HTML 。
失败	`200`	`application/json`	确认`code`和`message`常见答案

以下是支付月份入学申请中邮件缺失时的回复.

"杰森"("Json")

```json
{ "code": "10010003", "message": "email is required for paymentwall" }
```

注册处理¶

第一次支付是登记时的产品等级价格。应用选定支付方法的货币价格。

您每次申请注册时都会创建新的经常性付款。如果用户关闭付款页,经常性付款将仍然不完整,他们将无法要求经常性收费。

第一次付款后,蜂巢服务器将发出付款通知。type改为:paid保存order_id通知编号。

如果你收到一个10010005错误, 请重温您的支付方法列表, 包括market_pid,并使用答复中包含的付款方法提出请求。见错误代码用于了解如何处理错误的进一步信息。

再次支付API¶

在第二次付款之后我们会请求付款以你的支付方法存档。成功的对策是收到付款。晚期的PG批准与支付墙一样,在成功回应后可能会导致批准,一旦批准,蜂巢服务器会发出支付通知.

Request info¶

请求路径是/v2/payment/recurring/charge。请求方法和认证头遵循共同请求和答复.

生产 URL:https://hiveiap.qpyou.cn/v2/payment/recurring/charge
沙盒 URL :https://sandbox-hiveiap.qpyou.cn/v2/payment/recurring/charge

Request body¶

order_id将发送第一份付款通知的签发命令号。sequence是一个一元键,在同一经常性付款范围内将计费周期分开,并在重试同一计费周期时防止重复收费。

字段	类型	需要吗?	说明
`appid`	字符串	要求数	您注册的应用程序的应用标识
`order_id`	字符串	要求数	发布命令编号`order_id`第一次付款通知
`sequence`	整数	要求数	计费周期号. 它的值为 2 以上, 当重试同一计费周期时使用相同的值
`player_id`	字符串	要求数	注册用户的身份
`player_type`	字符串	要求数	注册用户的类型

下面是请求第二次付款的文本,并附有签发订单号。

"杰森"("Json")

```json
{ "appid": "com.com2us.example.normal.freefull.google.global.android.common",
  "order_id": "H4179125520850787386", "sequence": 2,
  "player_id": "20000032552", "player_type": "v4" }
```

Response body¶

成功的响应将包括这个计费周期的共同响应字段和订单号. 请将此数字与此计费周期关联保存。

字段	类型	包含响应	说明
`order_id`	字符串	成功重试响应	此计费周期的顺序号, 如`order_id`相应的计费周期的付款通知和退款通知

下面是返回第二顺序号的成功响应.

"杰森"("Json")

```json
{ "code": "0", "message": "SUCCESS", "order_id": "H5179125523990923210" }
```

再次支付条件和重试¶

您将随时使用重复支付注册时指定的产品付费。一个计费周期号由应用服务器管理,Hive不检查连续计费周期.

如果你停止出售某物品,我们将处理已登记的经常性付款的经常性收费请求。停止只出售块新的注册, 所以不要要求重复收费停止计费。

当再次要求使用相同的sequence,处理如下。

重复状态	回应	额外费用	App 服务器处理
已支付	`10010007`	无	忽略重复请求, 因为这些请求已经支付过时间
待核准	以同样方式成功回应`order_id`	无	根据付款通知支付产品
传输请求失败	付款重试结果	重试付款	用同样的方法重试`sequence`

返回 PG 失败的原因message与10010024在PG批准失败的情况下。请建议用户确认支付方法, 并再次尝试同样的方法sequence。内部错误10010001, 10010004,以及10010022也经过同样的重审sequence.

解约API¶

当您取消了经常性付款时,蜂巢服务器会删除与经常性付款一起注册的支付方法.10010023返回取消后请求重复收费时的错误。

Request info¶

请求路径是/v2/payment/recurring/cancel。请求方法和认证头遵循共同请求和答复.

生产 URL:https://hiveiap.qpyou.cn/v2/payment/recurring/cancel
沙盒 URL :https://sandbox-hiveiap.qpyou.cn/v2/payment/recurring/cancel

Request body¶

提供您想要终止的经常性付款的发单编号, 以及您注册的应用程序和用户信息。命令编号在第二轮之后无法取消。

字段	类型	需要吗?	说明
`appid`	字符串	要求数	您注册的应用程序的应用标识
`order_id`	字符串	要求数	发布命令编号`order_id`第一次付款通知
`player_id`	字符串	要求数	注册用户的身份
`player_type`	字符串	要求数	注册用户的类型

下面是您要求取消重复付款的正文与签发的订单号。

"杰森"("Json")

```json
{ "appid": "com.com2us.example.normal.freefull.google.global.android.common",
  "order_id": "H4179125520850787386",
  "player_id": "20000032552", "player_type": "v4" }
```

Response body¶

成功对策包括共同对策领域code和message。下面是撤销成功的回应。

"杰森"("Json")

```json
{ "code": "0", "message": "SUCCESS" }
```

返回时10010003如果找不到经常性付款,或10010023如果它已经被撤销或没有活动。请重试10010004错误, 无法删除 PG 支付方法。

支付通知和结果处理¶

蜂巢服务器以与普通PG支付相同的格式,将经常性支付结果发送给相同的支付通知URL. 请参看PG 付款结果通知服务用于请求格式和发送字段。

关联订单号和支付期次¶

付款通知不包括经常性付款和计费周期号。应用程序服务器应当使用您保存的已发布的订单号和order_id在经常性收费答复中确定哪些经常性付款通知对应哪些经常性付款。

何时发送	`type`	`order_id`	App 服务器处理
完成第一笔付款	`paid`	发布命令编号	保存初始订单ID并处理首轮付款
二局后还钱	`paid`	适用时间`order_id`经常性收费答复	与节省的计费周期挂钩后处理产品付款
从蜂巢控制台或 PG 偿还计费周期	`cancelled`	重用时间顺序号	由于这一计费周期而处理退款

server_id, iap_payload, market_pid,在登记时发出的价值将始终在付款通知中告知。

发放商品和退款¶

使用purchase_bypass_info在付款通知中,type这是paid核实收据并支付物品。请参看PG 付款结果通知服务用于转发字段。

重新供资的计费周期将遵守退还用户经常性费用根据正常付款情况。

错误代码¶

即使HTTP状态代码是200你必须检查code在JSON体内。识别错误代码和请求状态 :

代码	相关 API	原因	处理方法
`0`	JSON 常见反应	成绩	处理每个API的成功答复
`10010001`	常见	内部错误	重试. 使用相同的重试`sequence`
`10010002`	常见	缺少所需值、印刷错误、非JSON体、非`POST`方法。包含如果`sequence`经常性费用少于或等于1或等于`player_type`错误	修改请求值和格式
`10010003`	查看和登记支付方法	APP或产品未找到,产品中止. 失踪`email`登记时在支付墙上	检查应用和产品. 要求它作为一个销售项目,并在输入电子邮件后重新要求支付墙壁
`10010003`	偿还、注销	没有发现经常性付款。非初始命令 ID 或另一个应用程序或用户的经常性付款	确认第一个初始订单 ID 和注册的应用程序和用户信息
`10010004`	常见	PG 互锁错误, 包括取消时未删除 PG 支付方法	重试. 使用相同的重试`sequence`
`10010005`	查看和登记支付方法	没有符合国家和产品货币的经常性付款方法	重审清单,包括`market_pid`,并在答复中包含的支付方法中登记
`10010007`	经常性费用	我已经付过钱了	忽略此为重复
`10010022`	常见	内部错误	重试. 使用相同的重试`sequence`
`10010023`	偿还、注销	因取消,招生失败,招生不全等原因未启用订阅.	提醒用户重新列出
`10010024`	经常性费用	未批准超过限额,停牌等PG. 包含 PG 失败的原因。`message`	在用户被告知支付方法后,再使用同样的方法`sequence`
HTTP 软件`401`	常见	Token 认证失败	校验`X-Access-Token`证书

对接注意事项¶

连接PG经常性支付时,检查订单号与订单号的使用方式,支付项目时,价格依据,取消范围.

使用签发订单号¶

重复收费和取消申请必须附有签发命令号order_id在第一次付款通知中。回返a10010003如果请求使用中学后命令编号,则出错。见一体化流动如何管理订单号。

期次编号和重试¶

使用sequence从2开始。你必须照样前进sequence重试同一轮付款时,避免双重计费。参见经常性收费通过计费周期状态和重试方法进行响应。

根据支付通知发放商品¶

根据type paid付款通知。付款不应仅仅针对成功的经常性费用。参见付款通知和结果处理 API学习如何验证收款并链接账单周期。

应用支付时的商品价格¶

每次付款的数额是要求付款时的产品等级价格。变更项目价格的,在下期分期支付更新后的金额. 参见经常性收费如果停薪,将如何处理。

Paymentwall购买者电子邮件¶

在用支付墙壁登记经常性付款时,请输入买方给用户的电子邮件并转发给email请参考经常性付款登记 API请求字段和进入条件。

区分解约与退款¶

如果你取消了你的经常性付款,你不会被退任何你已经支付的时间。如果你想要退款这些计费周期, 你需要处理一个单独的退款。参见撤销 API撤销请求和答复。