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撤銷請求和答覆。