Get Payments

Description

取得付款方式。

Resource

GET /v1/payments

Authorization

採用 OAuth 2.0 Bearer Token，詳細使用流程請參考 Auth Login。

Query Parameters

Name	Type	Description
shop_id	string	門市代碼
source_type	string(enum)	來源種類 ALLOWED VALUES: MOBILE_APP KIOSK SCAN_ORDER PWA
method_type	string(enum)	銷售方式（選填）。當與 `source_type` 一同帶入，且該門市已針對此銷售方式設定可用付款方式時，僅回傳該銷售方式所設定的付款方式；若查無對應設定，則回傳該門市的完整付款方式。 ALLOWED VALUES: DINE_IN PICK_UP DELIVERY PHONE_PICK_UP SCHEDULED_PICK_UP
vip_group_id	string	晶新會員 VIP 群組代碼（選填）。當帶入且該門市會員來源為晶新會員時，回傳清單會額外附加一筆該 VIP 群組的優惠付款方式（含折扣與折抵上限）；若門市非晶新會員或查無對應的有效優惠，則不附加，回傳結果不受影響。

Request Example

GET /v1/payments?shop_id=test01&source_type=KIOSK&method_type=DINE_IN&vip_group_id=VG01

Response

{
  "payment_methods": [
    {
      "id": "LINE_PAY",
      "name": "LINE Pay"
    },
    {
      "id": "CREDIT_CARD",
      "name": "信用卡"
    },
    {
      "id": "VG01_P1",
      "type": "JINGXIN",
      "name": "晶新VIP優惠",
      "discount": 90,
      "discount_max": null
    }
  ]
}

Response Example（門市啟用 DDPay 時）

門市啟用 DDPay 的付款服務時，會回傳合併後的單一付款方式，id 直接代表該服務的呼叫方式，icons 列出實際可用的子服務供前端顯示對應圖示：

{
  "payment_methods": [
    {
      "id": "DD_PAY_SD",
      "name": "線上支付",
      "icons": ["linepay", "credit"]
    },
    {
      "id": "DD_PAY_CPM",
      "name": "被掃支付",
      "icons": ["linepay", "jko"]
    },
    {
      "id": "DD_PAY_TTP",
      "name": "感應支付",
      "icons": ["credit", "apple"]
    }
  ]
}

Response Body Parameters

Name	Type	Description
payment_methods	PaymentMethods	付款方式

Response Body Parameters - PaymentMethods

Name	Type	Description
id	string	付款方式編號。門市啟用 DDPay 服務時，`id` 會是 ALLOWED VALUES: DD_PAY_SD：線上付款，前端改呼叫 DDPay Create Online Order DD_PAY_CPM：被掃付款，前端改以 `id` 呼叫 Unified Payment Gateway DD_PAY_TTP：感應付款，前端改以 `id` 呼叫 Unified Payment Gateway
name	string	付款方式名稱
line_pay_product_name	string	LINE Pay品名，只有付款方式為LINE Pay會回傳 (option)
type	string	付款方式類型，僅晶新會員 VIP 優惠付款方式會回傳，固定值 `JINGXIN` (option)
discount	integer	折扣（如 90 表示 9 折），僅晶新會員 VIP 優惠付款方式會回傳 (option)
discount_max	number	折抵上限金額，`null` 代表折抵無上限，僅晶新會員 VIP 優惠付款方式會回傳 (option)
icons	array(string)	僅 `id` 為 DD_PAY_SD/DD_PAY_CPM/DD_PAY_TTP 時回傳。列出該付款方式實際可用的子服務，供前端顯示對應圖示；同一 `id` 底下可能同時包含多個值。信用卡類（信用卡／Apple Pay／Google Pay）以 `credit`/`apple`/`google` 區分，其餘直接對應各支付服務。ALLOWED VALUES 依 `id`而不同： `id` 為 DD_PAY_CPM 時：　`linepay`、`jko`、`pxpayplus` `id` 為 DD_PAY_TTP 時：　`credit`、`apple`、`google` `id` 為 DD_PAY_SD 時：　`credit`、`linepay`、`jko`、`pxpayplus`、`apple`、`google`、`easywallet`、`icashpay`、`pluspay`、`twqr` (option)

當付款方式為 GOOGLE_PAY 或 APPLE_PAY 時，該付款方式物件會額外回傳前端串接所需的設定欄位（見下方）。其中 merchant 相關識別資料會依該門市實際生效的金鑰設定回傳。

GOOGLE_PAY 額外回傳欄位（僅付款方式為 GOOGLE_PAY 時）

Name	Type	Description
google_pay_gpay_merchant_id	string	Google Pay 商戶識別碼
google_pay_merchant_name	string	Google Pay 商戶名稱
allowedPaymentMethod	array(string)	支援的卡片驗證方式，固定為 `["PAN_ONLY", "CRYPTOGRAM_3DS"]`
allowedPrepaidCards	boolean	是否支援預付卡，固定為 `true`
billingAddressFormat	string	帳單地址格式，固定為 `FULL`
phoneNumberRequired	boolean	是否需要電話號碼，固定為 `true`
billingAddressRequired	boolean	是否需要帳單地址，固定為 `true`
emailRequired	boolean	是否需要電子郵件，固定為 `true`
shippingAddressRequired	boolean	是否需要收件地址，固定為 `true`
allowedCountryCodes	array(string)	支援的國家代碼，固定為 `["TW"]`

APPLE_PAY 額外回傳欄位（僅付款方式為 APPLE_PAY 時）

Name	Type	Description
apple_developer_merchant_id	string	Apple Developer 商戶識別碼
countryCode	string	國家代碼，固定為 `TW`
supportedCountries	array(string)	支援的國家，固定為 `["TW"]`
supportedNetworks	array(string)	支援的卡別，固定為 `["visa", "masterCard"]`
merchantCapabilities	array(string)	商戶支援能力，固定為 `["supports3DS", "supportsEMV", "supportsCredit", "supportsDebit"]`
billingContact	object	帳單聯絡資訊需求，含 `required` / `phoneNumberRequired` / `emailAddressRequired`，固定皆為 `true`
shippingContact	object	收件聯絡資訊需求，含 `required`，固定為 `false`

Response Example（含 GOOGLE_PAY / APPLE_PAY）

{
  "payment_methods": [
    {
      "id": "GOOGLE_PAY",
      "name": "Google Pay",
      "google_pay_gpay_merchant_id": "BCR2DN...",
      "google_pay_merchant_name": "示範商店",
      "allowedPaymentMethod": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
      "allowedPrepaidCards": true,
      "billingAddressFormat": "FULL",
      "phoneNumberRequired": true,
      "billingAddressRequired": true,
      "emailRequired": true,
      "shippingAddressRequired": true,
      "allowedCountryCodes": ["TW"]
    },
    {
      "id": "APPLE_PAY",
      "name": "Apple Pay",
      "apple_developer_merchant_id": "merchant.com.example",
      "countryCode": "TW",
      "supportedCountries": ["TW"],
      "supportedNetworks": ["visa", "masterCard"],
      "merchantCapabilities": ["supports3DS", "supportsEMV", "supportsCredit", "supportsDebit"],
      "billingContact": {
        "required": true,
        "phoneNumberRequired": true,
        "emailAddressRequired": true
      },
      "shippingContact": {
        "required": false
      }
    }
  ]
}