此篇文章將會介紹 Webhook（又稱 reverse APIs）發送出去資料的欄位說明，如果您尚未理解 Webhooks 的操作，可以參考關於 Webhooks 文章說明。

一、範例

webhook 將會以 HTTP POST 的方式傳送，內含說明此次交易的 JSON 資料，例如：消費者透過結帳流程完成交易後不久，就可以收到類似如下的通知。

{
  "transaction": {
    "trade_no": "REG2700041623747762",
    "money": "200.0",
    "created_at": "2021-06-15T17:02:42.266+08:00",
    "updated_at": "2021-06-15T17:02:42.266+08:00",
    "quantity": 1,
    "flag": "yourflag",
    "render_status": "wait",
    "type": "normal",
    "parent_trade_no": "REG2700041623747011",
    "items": {
      "id": 3149618,
      "reward_id": 11219,
      "reward_name": "backme 賣賣",
      "quantity": 1,
      "money": "200.0",
      "note": "買買買",
      "custom_fields": [
        {
          "id": 18,
          "field_type": "text",
          "name": "選項一",
          "is_required": true,
          "value": "選項一"
        },
        {
          "id": 19,
          "field_type": "select_box",
          "name": "下拉選單",
          "is_required": true,
          "value": "選項一"
        }
      ]
    }
  },
  "payment": {
    "type": "credit",
    "paid_at": "2021-06-15T17:02:42.266+08:00",
    "next_paid_time": "",
    "next_paid_amount": "",
    "log": "",
    "refund_at": null
  },
  "user": {
    "id": 270004,
    "email": "foo@backer-founder.com",
    "name": "foo",
    "cellphone": "+452464910786"
  },
  "recipient": {
    "recipient_name": "foo",
    "recipient_contact_email": "foo@backer-founder.com",
    "recipient_cellphone": "+452464910786",
    "recipient_address": "dsadsadsa",
    "recipient_postal_code": "100",
    "recipient_country": "TW",
    "recipient_subdivision": "TPE",
    "recipient_cityarea": "中正區"
  }
}

二、參數說明

1. transaction

屬性	型別	說明
transaction	物件	transaction 訂單物件。
trade_no	字串	訂單交易編號，每一筆交易會產生唯一的交易編號。
money	字串	訂單的交易總金額，因為有其他幣別交易功能，所以會帶有小數點。包含： - 訂單交易商品的金額。 - 集資專案的額外贊助金額／直接贊助金額。 - 客製化選項的金額。
created_at	字串	訂單建立時間，ISO 8601 UTC 格式。
updated_at	字串	訂單更新時間，ISO 8601 UTC 格式。
quantity	整數	訂單（商品x數量）總和。
flag	字串	flag功能僅在貝殼集器Backme上使用，挖貝Wabay目前不提供flag功能。
render_status	字串	訂單當下的狀態，對應後台贊助紀錄管理的訂單狀態。 wait_code：等待取號（一般訂單的 ATM、CVS） failed_code：取號失敗（一般訂單的 ATM、CVS） wait：等待繳款（一般訂單、子單，發動付款到信用卡刷卡完成之前的狀態） failed：付款失敗 success：完成繳款（一般訂單、子單付款成功，以及主單全期繳款完成時） refund_applying：退款申請中（一般訂單、子單） partial_refund：已部分退款（一般訂單、子單） refund：已全額退款（一般訂單、子單） cancel：已取消（一般訂單：零元訂單被取消時會出現的狀態） recurring：每期付款中（主單） suspend：已暫停（主單：人工暫停或被系統自動暫停） cancelled：取消訂閱（主單：人工取消訂閱或被系統自動取消訂閱）
type	字串	訂單的交易類別，有一般交易，定期定額主單，定期定額子單。 normal：一般訂單 parent：定期定額主單 * child：定期定額子單
parent_trade_no	字串	訂單對應的主單編號，如果為定期定額子單，則此欄位有值且為主單編號。如果為定期定額主單，該欄位為 null。

＊定期定額成立時，由於「子單」是實際付款成功的訂單，因此會先進行子單的資料傳輸，而後才傳輸「主單」的資料。子單跟主單的關係可參考：定期定額的主單跟子單是什麼意思？

2. items

屬性	型別	說明
items	物件或陣列	該訂單交易的商品資訊。如果是單一商品則為陣列，多商品結帳時才會是陣列。
id	整數	訂單項目的唯一 ID。
reward_id	整數	商品的唯一 ID。
reward_name	字串	商品名稱。
quantity	整數	商品購買數量。
money	字串	商品單價。
note	字串	消費者結帳時對商品的備註。

3. custom_fields

屬性	型別	說明
custom_fields	陣列	商品的客製化選項資訊。
id	整數	商品客製化選項的唯一 ID。（見：圖1 ）
field_type	字串	客製化選項的類別。 text：文字輸入 select_box：下拉選單 number_field：加購商品數量 checkbox：核取方塊
name	字串	結帳時，消費者會看到的客製化選項名稱。
is_required	布林值	此客製化選項在結帳時是否必填
value	字串	此客製化選項的內容

圖1：商品客製化選項的唯一 ID

4. payment

屬性	型別	說明
payment	物件	訂單結帳相關資訊。
type	字串	該筆訂單的結帳方式。 credit：信用卡 atm：ATM 繳費 cvs：超商代碼繳費
paid_at	字串	訂單從金流商回傳的付款時間，ISO 8601 UTC 格式。
next_paid_time	字串	如果是定期定額，會顯示下筆子單收款的時間。如果是一般訂單，則為空值。
next_paid_amount	字串	如果是定期定額，會顯示下筆子單收款的金額。如果是一般訂單，則為空值。
log	字串	訂單如果交易失敗，或管理員退款的原因。
refund_at	字串	訂單退款時間，ISO 8601 UTC 格式。

5. user

屬性	型別	說明
user	物件	訂單訂購人的相關資料。
id	整數	訂購人使用者唯一 ID。
email	字串	訂購人註冊 email。
name	字串	訂購人姓名。
cellphone	字串	訂購人手機號碼。

6. recipient

屬性	型別	說明
recipient	物件	收件人資料。
recipient_name	字串	收件人姓名。
recipient_contact_email	字串	收件人 email。
recipient_cellphone	字串	收件人手機號碼。
recipient_address	字串	收件人地址。
recipient_postal_code	字串	收件人郵遞區號。
recipient_country	字串	收件人國家 / 地區。
recipient_subdivision	字串	收件人城市 / 州 / 區。
recipient_cityarea	字串	收件人鄉 / 鎮 / 市 / 區。

7. receipt

屬性	型別	說明
receipt	物件	消費憑證 (收據/發票)。
receipt_type	字串	消費憑證類型。
choice	字串	消費憑證選項。
corporate_name	字串	公司抬頭。
contact_name	字串	稅捐收據抬頭。
tax_number	字串	統一編號。
identity_card_number	字串	報稅憑證。
citizen_digital_certificate_code	字串	自然人憑證載具。
email	字串	電子信箱。
mobile_code	字串	手機載具。
country	字串	國家 / 地區。
subdivision	字串	城市 / 州 / 區。
city_area	字串	鄉 / 鎮 / 市 / 區。
postal_code	字串	郵遞區號。
address	字串	地址。

一、範例

二、參數說明

相關文章