{
  "openapi": "3.1.0",
  "info": {
    "title": "應援金流 Payment API",
    "version": "10.3.1.1",
    "description": "應援金流 Payment API（不含需要傳送完整卡號的端點）。完整說明見 https://developer.oen.tw 。"
  },
  "servers": [
    {
      "url": "https://payment-api.testing.oen.tw",
      "description": "測試環境"
    },
    {
      "url": "https://payment-api.oen.tw",
      "description": "正式環境（需申請 IP 開通）"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "在 CRM 產生的 API token"
      }
    }
  },
  "paths": {
    "/checkout": {
      "post": {
        "operationId": "checkout",
        "summary": "建立單次付款",
        "description": "建立一筆單次付款，回傳交易的 `id`。把消費者導到 `https://{merchantId}.oen.tw/checkout/{id}`（測試環境是 `{merchantId}.testing.oen.tw`）付款。**結帳頁從呼叫這支 API 起 5 分鐘內有效**，請在消費者按下付款時才建立。",
        "parameters": [],
        "responses": {
          "200": {
            "description": "建立成功。`data.id` 用來組結帳頁網址，`data.transactionHid` 用來退款與對帳",
            "content": {
              "application/json": {
                "example": {
                  "code": "S0000",
                  "data": {
                    "id": "2HhndgEquCbDzC5OyVxWSGZmd2l",
                    "transactionHid": "P20260928AB12CD34"
                  },
                  "message": ""
                }
              }
            }
          },
          "400": {
            "description": "參數錯誤、金流未開通或風控拒絕，見下方錯誤表"
          },
          "401": {
            "description": "token 錯誤，回 `A0001`"
          },
          "403": {
            "description": "正式環境的 IP 還沒綁定，見[固定 IP 白名單](/developers/ip-allowlist/)"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "merchantId": {
                    "type": "string",
                    "description": "你的網域名稱。例如應援頁是 `https://ming.oen.tw`，就填 `ming`。必須與 token 所屬的網域相同，不同會回 400 `V0001`。",
                    "examples": [
                      "ming"
                    ]
                  },
                  "amount": {
                    "type": "integer",
                    "description": "金額（新台幣元）。必須等於 `productDetails` 各品項「數量 × 單價」的合計。\n限制：1 以上的整數",
                    "examples": [
                      1200
                    ]
                  },
                  "currency": {
                    "type": "string",
                    "description": "幣別。目前只支援新台幣。",
                    "enum": [
                      "TWD"
                    ],
                    "default": "TWD"
                  },
                  "orderId": {
                    "type": "string",
                    "description": "你的訂單編號。之後可以用[用訂單編號查詢](/api/list-order-transactions/)找到這筆訂單的所有交易。\n限制：不檢查重複。同一個 `orderId` 可以建立多筆交易",
                    "examples": [
                      "A20260928001"
                    ]
                  },
                  "successUrl": {
                    "type": "string",
                    "description": "付款成功後把消費者導回的網址。**導回時不帶任何參數**，請在網址裡放自己的訂單編號，例如 `https://shop.example.com/thanks?order=A001`。導回不代表付款成功，請以付款通知或查詢結果為準。\n限制：要寫完整網址（含 `https://`）；可以是 `null`，但欄位一定要有"
                  },
                  "failureUrl": {
                    "type": "string",
                    "description": "付款失敗或逾時後導回的網址，會加上 `payment_error` 參數，可能的值見[錯誤碼一覽](/api/error-codes/#結帳頁導回的-payment_error)。\n限制：同 `successUrl`。建議不要自帶 `?` 參數與 `#` 片段"
                  },
                  "productDetails": {
                    "type": "array",
                    "description": "商品明細，用來開立電子發票與顯示在 CRM。**所有品項「數量 × 單價」的合計必須等於 `amount`**，否則回 400 `V0001`（`PRODUCT_AMOUNT_NOT_MATCH`）。",
                    "items": {
                      "type": "object",
                      "properties": {
                        "productionCode": {
                          "type": "string",
                          "description": "商品代碼"
                        },
                        "description": {
                          "type": "string",
                          "description": "商品名稱。第一個品項的名稱也會當成交易的商品描述"
                        },
                        "quantity": {
                          "type": "integer",
                          "description": "數量\n限制：1 以上的整數"
                        },
                        "unit": {
                          "type": "string",
                          "description": "單位，例如「個」「份」"
                        },
                        "unitPrice": {
                          "type": "integer",
                          "description": "單價（新台幣元）"
                        }
                      },
                      "required": [
                        "productionCode",
                        "description",
                        "quantity",
                        "unit",
                        "unitPrice"
                      ]
                    }
                  },
                  "allowedPaymentMethods": {
                    "type": "array",
                    "description": "結帳頁可以選的付款方式。**信用卡一定會出現**，這裡是「加開」其他方式：`['cvs']` 會顯示信用卡與超商。沒帶就只有信用卡。Apple Pay 不用指定，條件符合時自動出現。詳見[付款方式](/developers/payment-methods/)。",
                    "enum": [
                      "card",
                      "cvs",
                      "linePay",
                      "atm"
                    ],
                    "examples": [
                      [
                        "cvs"
                      ]
                    ],
                    "items": {
                      "type": "string"
                    }
                  },
                  "userId": {
                    "type": "string",
                    "description": "你系統裡的會員編號。"
                  },
                  "userName": {
                    "type": "string",
                    "description": "消費者姓名。網域有開通電子發票時必填。"
                  },
                  "userEmail": {
                    "type": "string",
                    "description": "消費者 Email。網域有開通電子發票時必填，發票通知會寄到這裡。"
                  },
                  "invoiceInfo": {
                    "type": "object",
                    "description": "電子發票資訊。網域有開通電子發票時才有作用；沒帶時開立雲端發票。",
                    "properties": {
                      "invoiceType": {
                        "type": "string",
                        "description": "`cloud`：雲端發票；`company`：公司戶（打統編）",
                        "enum": [
                          "cloud",
                          "company"
                        ]
                      },
                      "carrierType": {
                        "type": "string",
                        "description": "載具類型：`3J0002` 手機條碼、`CQ0001` 自然人憑證、空字串為會員載具",
                        "enum": [
                          "3J0002",
                          "CQ0001",
                          ""
                        ]
                      },
                      "carrierId": {
                        "type": "string",
                        "description": "載具號碼。手機條碼格式為 `/` 加 7 碼，會即時向財政部驗證；自然人憑證為 2 個英文字母加 14 碼數字"
                      },
                      "buyerIdentifier": {
                        "type": "string",
                        "description": "買受人統一編號，8 碼，會檢查檢查碼"
                      },
                      "buyerName": {
                        "type": "string",
                        "description": "買受人名稱"
                      },
                      "email": {
                        "type": "string",
                        "description": "發票通知 Email"
                      }
                    },
                    "required": [
                      "invoiceType"
                    ]
                  },
                  "customId": {
                    "type": "string",
                    "description": "你自訂的資料，會原樣出現在付款通知與查詢結果中。"
                  },
                  "note": {
                    "type": "string",
                    "description": "備註。"
                  },
                  "use3d": {
                    "type": "boolean",
                    "description": "是否走 3D 驗證。網域被設定為一律 3D 時會強制開啟。",
                    "default": false
                  },
                  "expectedPayoutDate": {
                    "type": "string",
                    "description": "期望撥款日期（台北日期），會顯示在 CRM 金流明細。\n限制：`yyyy/MM/dd`"
                  }
                },
                "required": [
                  "merchantId",
                  "amount",
                  "orderId",
                  "successUrl",
                  "failureUrl",
                  "productDetails"
                ]
              },
              "example": {
                "merchantId": "ming",
                "amount": 1200,
                "currency": "TWD",
                "orderId": "A20260928001",
                "successUrl": "https://shop.example.com/payment/success?order=A20260928001",
                "failureUrl": "https://shop.example.com/payment/failure/A20260928001",
                "userName": "王小明",
                "userEmail": "ming@example.com",
                "productDetails": [
                  {
                    "productionCode": "SKU-001",
                    "description": "手沖咖啡豆 200g",
                    "quantity": 2,
                    "unit": "包",
                    "unitPrice": 600
                  }
                ],
                "allowedPaymentMethods": [
                  "cvs"
                ],
                "customId": "cart-8812"
              }
            }
          }
        }
      }
    },
    "/checkout-subscription": {
      "post": {
        "operationId": "checkout-subscription",
        "summary": "建立定期定額",
        "description": "建立每月扣款的定期定額，回傳交易的 `id`。把消費者導到 `https://{merchantId}.oen.tw/checkout/subscription/{id}`。消費者在結帳頁付款時扣第一期，之後每個月同一天由應援自動扣款。只支援信用卡。結帳頁 5 分鐘內有效。",
        "parameters": [],
        "responses": {
          "200": {
            "description": "建立成功",
            "content": {
              "application/json": {
                "example": {
                  "code": "S0000",
                  "data": {
                    "id": "2HhndgEquCbDzC5OyVxWSGZmd2l",
                    "transactionHid": "P20260928AB12CD34"
                  },
                  "message": ""
                }
              }
            }
          },
          "400": {
            "description": "參數錯誤或金流未開通"
          },
          "401": {
            "description": "token 錯誤"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "merchantId": {
                    "type": "string",
                    "description": "你的網域名稱。例如應援頁是 `https://ming.oen.tw`，就填 `ming`。必須與 token 所屬的網域相同，不同會回 400 `V0001`。",
                    "examples": [
                      "ming"
                    ]
                  },
                  "amount": {
                    "type": "integer",
                    "description": "每期金額（新台幣元）。必須等於 `productDetails` 的合計。\n限制：1 以上的整數",
                    "examples": [
                      1200
                    ]
                  },
                  "currency": {
                    "type": "string",
                    "description": "幣別。目前只支援新台幣。",
                    "enum": [
                      "TWD"
                    ],
                    "default": "TWD"
                  },
                  "numberOfPeriods": {
                    "type": "integer",
                    "description": "總期數。不帶就是不限期，直到取消。\n限制：2 以上"
                  },
                  "orderId": {
                    "type": "string",
                    "description": "你的訂單編號。之後可以用[用訂單編號查詢](/api/list-order-transactions/)找到這筆訂單的所有交易。\n限制：不檢查重複。同一個 `orderId` 可以建立多筆交易",
                    "examples": [
                      "A20260928001"
                    ]
                  },
                  "successUrl": {
                    "type": "string",
                    "description": "付款成功後把消費者導回的網址。**導回時不帶任何參數**，請在網址裡放自己的訂單編號，例如 `https://shop.example.com/thanks?order=A001`。導回不代表付款成功，請以付款通知或查詢結果為準。\n限制：要寫完整網址（含 `https://`）；可以是 `null`，但欄位一定要有"
                  },
                  "failureUrl": {
                    "type": "string",
                    "description": "付款失敗或逾時後導回的網址，會加上 `payment_error` 參數，可能的值見[錯誤碼一覽](/api/error-codes/#結帳頁導回的-payment_error)。\n限制：同 `successUrl`。建議不要自帶 `?` 參數與 `#` 片段"
                  },
                  "productDetails": {
                    "type": "array",
                    "description": "商品明細，用來開立電子發票與顯示在 CRM。**所有品項「數量 × 單價」的合計必須等於 `amount`**，否則回 400 `V0001`（`PRODUCT_AMOUNT_NOT_MATCH`）。",
                    "items": {
                      "type": "object",
                      "properties": {
                        "productionCode": {
                          "type": "string",
                          "description": "商品代碼"
                        },
                        "description": {
                          "type": "string",
                          "description": "商品名稱。第一個品項的名稱也會當成交易的商品描述"
                        },
                        "quantity": {
                          "type": "integer",
                          "description": "數量\n限制：1 以上的整數"
                        },
                        "unit": {
                          "type": "string",
                          "description": "單位，例如「個」「份」"
                        },
                        "unitPrice": {
                          "type": "integer",
                          "description": "單價（新台幣元）"
                        }
                      },
                      "required": [
                        "productionCode",
                        "description",
                        "quantity",
                        "unit",
                        "unitPrice"
                      ]
                    }
                  },
                  "userId": {
                    "type": "string",
                    "description": "你系統裡的會員編號。"
                  },
                  "userName": {
                    "type": "string",
                    "description": "消費者姓名。網域有開通電子發票時必填。"
                  },
                  "userEmail": {
                    "type": "string",
                    "description": "消費者 Email。網域有開通電子發票時必填，發票通知會寄到這裡。"
                  },
                  "invoiceInfo": {
                    "type": "object",
                    "description": "電子發票資訊。網域有開通電子發票時才有作用；沒帶時開立雲端發票。",
                    "properties": {
                      "invoiceType": {
                        "type": "string",
                        "description": "`cloud`：雲端發票；`company`：公司戶（打統編）",
                        "enum": [
                          "cloud",
                          "company"
                        ]
                      },
                      "carrierType": {
                        "type": "string",
                        "description": "載具類型：`3J0002` 手機條碼、`CQ0001` 自然人憑證、空字串為會員載具",
                        "enum": [
                          "3J0002",
                          "CQ0001",
                          ""
                        ]
                      },
                      "carrierId": {
                        "type": "string",
                        "description": "載具號碼。手機條碼格式為 `/` 加 7 碼，會即時向財政部驗證；自然人憑證為 2 個英文字母加 14 碼數字"
                      },
                      "buyerIdentifier": {
                        "type": "string",
                        "description": "買受人統一編號，8 碼，會檢查檢查碼"
                      },
                      "buyerName": {
                        "type": "string",
                        "description": "買受人名稱"
                      },
                      "email": {
                        "type": "string",
                        "description": "發票通知 Email"
                      }
                    },
                    "required": [
                      "invoiceType"
                    ]
                  },
                  "customId": {
                    "type": "string",
                    "description": "你自訂的資料，會原樣出現在付款通知與查詢結果中。"
                  },
                  "note": {
                    "type": "string",
                    "description": "備註。"
                  },
                  "use3d": {
                    "type": "boolean",
                    "description": "是否走 3D 驗證。網域被設定為一律 3D 時會強制開啟。",
                    "default": false
                  }
                },
                "required": [
                  "merchantId",
                  "amount",
                  "orderId",
                  "successUrl",
                  "failureUrl",
                  "productDetails"
                ]
              },
              "example": {
                "merchantId": "ming",
                "amount": 299,
                "numberOfPeriods": 12,
                "orderId": "SUB20260928001",
                "successUrl": "https://shop.example.com/subscribe/success?order=SUB20260928001",
                "failureUrl": "https://shop.example.com/subscribe/failure/SUB20260928001",
                "userName": "王小明",
                "userEmail": "ming@example.com",
                "productDetails": [
                  {
                    "productionCode": "PLAN-M",
                    "description": "月費會員",
                    "quantity": 1,
                    "unit": "月",
                    "unitPrice": 299
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/checkout-schedule": {
      "post": {
        "operationId": "checkout-schedule",
        "summary": "建立預約定期定額",
        "description": "建立可以指定首期扣款日與扣款間隔的定期定額，回傳 `id` 與定期定額編號 `subscriptionHid`。把消費者導到 `https://{merchantId}.oen.tw/checkout/schedule/{id}`。首期日是今天時，消費者付款當下扣第一期；是未來日期時，消費者只綁卡，到期由應援扣款。結帳頁 5 分鐘內有效。",
        "parameters": [],
        "responses": {
          "200": {
            "description": "建立成功",
            "content": {
              "application/json": {
                "example": {
                  "code": "S0000",
                  "data": {
                    "id": "2HhnfZ1kqRmA7cX0TQwq8vBn3Ls",
                    "subscriptionHid": "S20260928EF56GH78"
                  },
                  "message": ""
                }
              }
            }
          },
          "400": {
            "description": "參數錯誤"
          },
          "401": {
            "description": "token 錯誤"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "merchantId": {
                    "type": "string",
                    "description": "你的網域名稱。例如應援頁是 `https://ming.oen.tw`，就填 `ming`。必須與 token 所屬的網域相同，不同會回 400 `V0001`。",
                    "examples": [
                      "ming"
                    ]
                  },
                  "amount": {
                    "type": "integer",
                    "description": "每期金額（新台幣元）。必須等於 `productDetails` 的合計。\n限制：1 以上的整數",
                    "examples": [
                      1200
                    ]
                  },
                  "currency": {
                    "type": "string",
                    "description": "幣別。目前只支援新台幣。",
                    "enum": [
                      "TWD"
                    ],
                    "default": "TWD"
                  },
                  "numberOfPeriods": {
                    "type": "integer",
                    "description": "總期數。不帶就是不限期，直到取消。\n限制：2 以上"
                  },
                  "paymentInterval": {
                    "type": "integer",
                    "description": "每幾個月扣款一次。\n限制：1 到 12",
                    "default": 1
                  },
                  "startDate": {
                    "type": "string",
                    "description": "首期扣款日（台北日期）。不帶就是今天。\n限制：`yyyy/MM/dd`；今天到 12 個月內",
                    "examples": [
                      "2026/10/15"
                    ]
                  },
                  "orderId": {
                    "type": "string",
                    "description": "你的訂單編號。之後可以用[用訂單編號查詢](/api/list-order-transactions/)找到這筆訂單的所有交易。\n限制：不檢查重複。同一個 `orderId` 可以建立多筆交易",
                    "examples": [
                      "A20260928001"
                    ]
                  },
                  "successUrl": {
                    "type": "string",
                    "description": "付款成功後把消費者導回的網址。**導回時不帶任何參數**，請在網址裡放自己的訂單編號，例如 `https://shop.example.com/thanks?order=A001`。導回不代表付款成功，請以付款通知或查詢結果為準。\n限制：要寫完整網址（含 `https://`）；可以是 `null`，但欄位一定要有"
                  },
                  "failureUrl": {
                    "type": "string",
                    "description": "付款失敗或逾時後導回的網址，會加上 `payment_error` 參數，可能的值見[錯誤碼一覽](/api/error-codes/#結帳頁導回的-payment_error)。\n限制：同 `successUrl`。建議不要自帶 `?` 參數與 `#` 片段"
                  },
                  "productDetails": {
                    "type": "array",
                    "description": "商品明細，用來開立電子發票與顯示在 CRM。**所有品項「數量 × 單價」的合計必須等於 `amount`**，否則回 400 `V0001`（`PRODUCT_AMOUNT_NOT_MATCH`）。",
                    "items": {
                      "type": "object",
                      "properties": {
                        "productionCode": {
                          "type": "string",
                          "description": "商品代碼"
                        },
                        "description": {
                          "type": "string",
                          "description": "商品名稱。第一個品項的名稱也會當成交易的商品描述"
                        },
                        "quantity": {
                          "type": "integer",
                          "description": "數量\n限制：1 以上的整數"
                        },
                        "unit": {
                          "type": "string",
                          "description": "單位，例如「個」「份」"
                        },
                        "unitPrice": {
                          "type": "integer",
                          "description": "單價（新台幣元）"
                        }
                      },
                      "required": [
                        "productionCode",
                        "description",
                        "quantity",
                        "unit",
                        "unitPrice"
                      ]
                    }
                  },
                  "userId": {
                    "type": "string",
                    "description": "你系統裡的會員編號。"
                  },
                  "userName": {
                    "type": "string",
                    "description": "消費者姓名。網域有開通電子發票時必填。"
                  },
                  "userEmail": {
                    "type": "string",
                    "description": "消費者 Email。網域有開通電子發票時必填，發票通知會寄到這裡。"
                  },
                  "invoiceInfo": {
                    "type": "object",
                    "description": "電子發票資訊。網域有開通電子發票時才有作用；沒帶時開立雲端發票。",
                    "properties": {
                      "invoiceType": {
                        "type": "string",
                        "description": "`cloud`：雲端發票；`company`：公司戶（打統編）",
                        "enum": [
                          "cloud",
                          "company"
                        ]
                      },
                      "carrierType": {
                        "type": "string",
                        "description": "載具類型：`3J0002` 手機條碼、`CQ0001` 自然人憑證、空字串為會員載具",
                        "enum": [
                          "3J0002",
                          "CQ0001",
                          ""
                        ]
                      },
                      "carrierId": {
                        "type": "string",
                        "description": "載具號碼。手機條碼格式為 `/` 加 7 碼，會即時向財政部驗證；自然人憑證為 2 個英文字母加 14 碼數字"
                      },
                      "buyerIdentifier": {
                        "type": "string",
                        "description": "買受人統一編號，8 碼，會檢查檢查碼"
                      },
                      "buyerName": {
                        "type": "string",
                        "description": "買受人名稱"
                      },
                      "email": {
                        "type": "string",
                        "description": "發票通知 Email"
                      }
                    },
                    "required": [
                      "invoiceType"
                    ]
                  },
                  "customId": {
                    "type": "string",
                    "description": "你自訂的資料，會原樣出現在付款通知與查詢結果中。"
                  },
                  "note": {
                    "type": "string",
                    "description": "備註。"
                  },
                  "use3d": {
                    "type": "boolean",
                    "description": "是否走 3D 驗證。網域被設定為一律 3D 時會強制開啟。",
                    "default": false
                  }
                },
                "required": [
                  "merchantId",
                  "amount",
                  "orderId",
                  "successUrl",
                  "failureUrl",
                  "productDetails"
                ]
              },
              "example": {
                "merchantId": "ming",
                "amount": 1500,
                "numberOfPeriods": 4,
                "paymentInterval": 3,
                "startDate": "2026/10/15",
                "orderId": "SUB20260928002",
                "successUrl": "https://shop.example.com/subscribe/success?order=SUB20260928002",
                "failureUrl": "https://shop.example.com/subscribe/failure/SUB20260928002",
                "userName": "王小明",
                "userEmail": "ming@example.com",
                "productDetails": [
                  {
                    "productionCode": "BOX-Q",
                    "description": "季訂閱禮盒",
                    "quantity": 1,
                    "unit": "盒",
                    "unitPrice": 1500
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/checkout-token": {
      "post": {
        "operationId": "checkout-token",
        "summary": "建立綁卡頁",
        "description": "建立綁卡頁，回傳 `id`。把消費者導到 `https://{merchantId}.oen.tw/checkout/subscription/create/{id}` 完成 3D 驗證並綁卡。**綁卡頁 10 分鐘內有效。token 只會透過付款通知（`purpose` 為 `token`）送給你**，導回網址不帶 token，也沒有查詢 API。",
        "parameters": [],
        "responses": {
          "200": {
            "description": "建立成功",
            "content": {
              "application/json": {
                "example": {
                  "code": "S0000",
                  "data": {
                    "id": "2HhngP9sVb3mK1xYdQe7Wc0RtUi"
                  },
                  "message": ""
                }
              }
            }
          },
          "400": {
            "description": "參數錯誤或金流未開通"
          },
          "401": {
            "description": "token 錯誤"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "merchantId": {
                    "type": "string",
                    "description": "你的網域名稱。例如應援頁是 `https://ming.oen.tw`，就填 `ming`。必須與 token 所屬的網域相同，不同會回 400 `V0001`。",
                    "examples": [
                      "ming"
                    ]
                  },
                  "successUrl": {
                    "type": "string",
                    "description": "綁卡成功後導回的網址。**不帶 token**。\n限制：要寫完整網址（含 `https://`）；可以是 `null`，但欄位一定要有"
                  },
                  "failureUrl": {
                    "type": "string",
                    "description": "綁卡失敗或逾時後導回的網址，會加上 `payment_error`。\n限制：同 `successUrl`。建議不要自帶 `?` 參數與 `#` 片段"
                  },
                  "customId": {
                    "type": "string",
                    "description": "你自訂的資料，會出現在 token 通知裡，方便你對應是哪一位會員。"
                  },
                  "note": {
                    "type": "string",
                    "description": "備註。"
                  },
                  "payerEmail": {
                    "type": "string",
                    "description": "持卡人 Email。沒帶時消費者要在綁卡頁自行填寫。"
                  }
                },
                "required": [
                  "merchantId",
                  "successUrl",
                  "failureUrl"
                ]
              },
              "example": {
                "merchantId": "ming",
                "successUrl": "https://shop.example.com/cards/added?member=M001",
                "failureUrl": "https://shop.example.com/cards/failed/M001",
                "customId": "M001",
                "payerEmail": "ming@example.com"
              }
            }
          }
        }
      }
    },
    "/token/transactions": {
      "post": {
        "operationId": "token-transactions",
        "summary": "用 token 扣款",
        "description": "用綁卡取得的 token 直接扣款，消費者不需要在場，也不走 3D 驗證。**結果以這支 API 的回應為準，不會送付款通知**。沒有防重複扣款的機制：逾時或收到 5xx 時，請先用[訂單編號查詢](/api/list-order-transactions/)確認，不要直接重送。",
        "parameters": [],
        "responses": {
          "200": {
            "description": "扣款成功",
            "content": {
              "application/json": {
                "example": {
                  "code": "S0000",
                  "data": {
                    "id": "P20260928IJ90KL12",
                    "authCode": "831000"
                  },
                  "message": ""
                }
              }
            }
          },
          "400": {
            "description": "扣款失敗（`T0001`～`T0005`）或參數錯誤。失敗的交易仍會建立，可以用訂單編號查到"
          },
          "401": {
            "description": "token 錯誤"
          },
          "409": {
            "description": "付款結果不明（`C026`）。**不要重試**，先查詢交易狀態"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "merchantId": {
                    "type": "string",
                    "description": "你的網域名稱。例如應援頁是 `https://ming.oen.tw`，就填 `ming`。必須與 token 所屬的網域相同，不同會回 400 `V0001`。",
                    "examples": [
                      "ming"
                    ]
                  },
                  "amount": {
                    "type": "integer",
                    "description": "金額（新台幣元）。必須等於 `productDetails` 各品項「數量 × 單價」的合計。\n限制：1 以上的整數",
                    "examples": [
                      1200
                    ]
                  },
                  "currency": {
                    "type": "string",
                    "description": "幣別，只能是 `TWD`。",
                    "enum": [
                      "TWD"
                    ],
                    "default": "TWD"
                  },
                  "token": {
                    "type": "string",
                    "description": "綁卡通知裡的 `token`。"
                  },
                  "orderId": {
                    "type": "string",
                    "description": "你的訂單編號。之後可以用[用訂單編號查詢](/api/list-order-transactions/)找到這筆訂單的所有交易。\n限制：不檢查重複。同一個 `orderId` 可以建立多筆交易",
                    "examples": [
                      "A20260928001"
                    ]
                  },
                  "productDetails": {
                    "type": "array",
                    "description": "商品明細，用來開立電子發票與顯示在 CRM。**所有品項「數量 × 單價」的合計必須等於 `amount`**，否則回 400 `V0001`（`PRODUCT_AMOUNT_NOT_MATCH`）。",
                    "items": {
                      "type": "object",
                      "properties": {
                        "productionCode": {
                          "type": "string",
                          "description": "商品代碼"
                        },
                        "description": {
                          "type": "string",
                          "description": "商品名稱。第一個品項的名稱也會當成交易的商品描述"
                        },
                        "quantity": {
                          "type": "integer",
                          "description": "數量\n限制：1 以上的整數"
                        },
                        "unit": {
                          "type": "string",
                          "description": "單位，例如「個」「份」"
                        },
                        "unitPrice": {
                          "type": "integer",
                          "description": "單價（新台幣元）"
                        }
                      },
                      "required": [
                        "productionCode",
                        "description",
                        "quantity",
                        "unit",
                        "unitPrice"
                      ]
                    }
                  },
                  "userId": {
                    "type": "string",
                    "description": "你系統裡的會員編號。"
                  },
                  "userName": {
                    "type": "string",
                    "description": "消費者姓名。網域有開通電子發票時必填。"
                  },
                  "userEmail": {
                    "type": "string",
                    "description": "消費者 Email。網域有開通電子發票時必填，發票通知會寄到這裡。"
                  },
                  "userPhone": {
                    "type": "string",
                    "description": "消費者手機號碼。網域設定為手機必填時，必須是有效的電話號碼。"
                  },
                  "invoiceInfo": {
                    "type": "object",
                    "description": "電子發票資訊。網域有開通電子發票時才有作用；沒帶時開立雲端發票。",
                    "properties": {
                      "invoiceType": {
                        "type": "string",
                        "description": "`cloud`：雲端發票；`company`：公司戶（打統編）",
                        "enum": [
                          "cloud",
                          "company"
                        ]
                      },
                      "carrierType": {
                        "type": "string",
                        "description": "載具類型：`3J0002` 手機條碼、`CQ0001` 自然人憑證、空字串為會員載具",
                        "enum": [
                          "3J0002",
                          "CQ0001",
                          ""
                        ]
                      },
                      "carrierId": {
                        "type": "string",
                        "description": "載具號碼。手機條碼格式為 `/` 加 7 碼，會即時向財政部驗證；自然人憑證為 2 個英文字母加 14 碼數字"
                      },
                      "buyerIdentifier": {
                        "type": "string",
                        "description": "買受人統一編號，8 碼，會檢查檢查碼"
                      },
                      "buyerName": {
                        "type": "string",
                        "description": "買受人名稱"
                      },
                      "email": {
                        "type": "string",
                        "description": "發票通知 Email"
                      }
                    },
                    "required": [
                      "invoiceType"
                    ]
                  },
                  "note": {
                    "type": "string",
                    "description": "備註。"
                  },
                  "expectedPayoutDate": {
                    "type": "string",
                    "description": "期望撥款日期（台北日期），會顯示在 CRM 金流明細。\n限制：`yyyy/MM/dd`"
                  }
                },
                "required": [
                  "merchantId",
                  "amount",
                  "token",
                  "orderId",
                  "productDetails"
                ]
              },
              "example": {
                "merchantId": "ming",
                "amount": 1200,
                "token": "2HhnhWm8Qe0sPz4LbXv9KdYt1Ra",
                "orderId": "A20260928003",
                "userName": "王小明",
                "userEmail": "ming@example.com",
                "productDetails": [
                  {
                    "productionCode": "SKU-001",
                    "description": "手沖咖啡豆 200g",
                    "quantity": 2,
                    "unit": "包",
                    "unitPrice": 600
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/token/subscriptions": {
      "post": {
        "operationId": "token-subscriptions",
        "summary": "用 token 建立定期定額",
        "description": "用綁卡取得的 token 建立定期定額。不帶 `startDate` 時當下扣第一期，結果以回應為準（第一期不送付款通知，之後每期會送）；帶未來日期時只建立排程，到期才扣款。",
        "parameters": [],
        "responses": {
          "200": {
            "description": "建立成功",
            "content": {
              "application/json": {
                "example": {
                  "code": "S0000",
                  "data": {
                    "subscriptionId": "S20260928MN34OP56",
                    "transactionId": "P20260928QR78ST90",
                    "authCode": "831000"
                  },
                  "message": ""
                }
              }
            }
          },
          "400": {
            "description": "第一期扣款失敗（`T0001`～`T0005`）或參數錯誤"
          },
          "401": {
            "description": "token 錯誤"
          },
          "409": {
            "description": "第一期付款結果不明（`C026`），不要重試"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "merchantId": {
                    "type": "string",
                    "description": "你的網域名稱。例如應援頁是 `https://ming.oen.tw`，就填 `ming`。必須與 token 所屬的網域相同，不同會回 400 `V0001`。",
                    "examples": [
                      "ming"
                    ]
                  },
                  "amount": {
                    "type": "integer",
                    "description": "每期金額（新台幣元）。必須等於 `productDetails` 的合計。\n限制：1 以上的整數",
                    "examples": [
                      1200
                    ]
                  },
                  "currency": {
                    "type": "string",
                    "description": "幣別，只能是 `TWD`。",
                    "enum": [
                      "TWD"
                    ],
                    "default": "TWD"
                  },
                  "token": {
                    "type": "string",
                    "description": "綁卡通知裡的 `token`。"
                  },
                  "numberOfPeriods": {
                    "type": "integer",
                    "description": "總期數。不帶就是不限期，直到取消。\n限制：2 以上"
                  },
                  "paymentInterval": {
                    "type": "integer",
                    "description": "每幾個月扣款一次。\n限制：1 到 12",
                    "default": 1
                  },
                  "startDate": {
                    "type": "string",
                    "description": "首期扣款日（台北日期）。不帶就立即扣第一期。\n限制：`yyyy/MM/dd`；**必須晚於今天**，最晚 12 個月內"
                  },
                  "orderId": {
                    "type": "string",
                    "description": "你的訂單編號。之後可以用[用訂單編號查詢](/api/list-order-transactions/)找到這筆訂單的所有交易。\n限制：不檢查重複。同一個 `orderId` 可以建立多筆交易",
                    "examples": [
                      "A20260928001"
                    ]
                  },
                  "productDetails": {
                    "type": "array",
                    "description": "商品明細，用來開立電子發票與顯示在 CRM。**所有品項「數量 × 單價」的合計必須等於 `amount`**，否則回 400 `V0001`（`PRODUCT_AMOUNT_NOT_MATCH`）。",
                    "items": {
                      "type": "object",
                      "properties": {
                        "productionCode": {
                          "type": "string",
                          "description": "商品代碼"
                        },
                        "description": {
                          "type": "string",
                          "description": "商品名稱。第一個品項的名稱也會當成交易的商品描述"
                        },
                        "quantity": {
                          "type": "integer",
                          "description": "數量\n限制：1 以上的整數"
                        },
                        "unit": {
                          "type": "string",
                          "description": "單位，例如「個」「份」"
                        },
                        "unitPrice": {
                          "type": "integer",
                          "description": "單價（新台幣元）"
                        }
                      },
                      "required": [
                        "productionCode",
                        "description",
                        "quantity",
                        "unit",
                        "unitPrice"
                      ]
                    }
                  },
                  "userId": {
                    "type": "string",
                    "description": "你系統裡的會員編號。"
                  },
                  "userName": {
                    "type": "string",
                    "description": "消費者姓名。網域有開通電子發票時必填。"
                  },
                  "userEmail": {
                    "type": "string",
                    "description": "消費者 Email。網域有開通電子發票時必填，發票通知會寄到這裡。"
                  },
                  "userPhone": {
                    "type": "string",
                    "description": "消費者手機號碼。網域設定為手機必填時，必須是有效的電話號碼。"
                  },
                  "invoiceInfo": {
                    "type": "object",
                    "description": "電子發票資訊。網域有開通電子發票時才有作用；沒帶時開立雲端發票。",
                    "properties": {
                      "invoiceType": {
                        "type": "string",
                        "description": "`cloud`：雲端發票；`company`：公司戶（打統編）",
                        "enum": [
                          "cloud",
                          "company"
                        ]
                      },
                      "carrierType": {
                        "type": "string",
                        "description": "載具類型：`3J0002` 手機條碼、`CQ0001` 自然人憑證、空字串為會員載具",
                        "enum": [
                          "3J0002",
                          "CQ0001",
                          ""
                        ]
                      },
                      "carrierId": {
                        "type": "string",
                        "description": "載具號碼。手機條碼格式為 `/` 加 7 碼，會即時向財政部驗證；自然人憑證為 2 個英文字母加 14 碼數字"
                      },
                      "buyerIdentifier": {
                        "type": "string",
                        "description": "買受人統一編號，8 碼，會檢查檢查碼"
                      },
                      "buyerName": {
                        "type": "string",
                        "description": "買受人名稱"
                      },
                      "email": {
                        "type": "string",
                        "description": "發票通知 Email"
                      }
                    },
                    "required": [
                      "invoiceType"
                    ]
                  },
                  "note": {
                    "type": "string",
                    "description": "備註。"
                  }
                },
                "required": [
                  "merchantId",
                  "amount",
                  "token",
                  "orderId",
                  "productDetails"
                ]
              },
              "example": {
                "merchantId": "ming",
                "amount": 299,
                "token": "2HhnhWm8Qe0sPz4LbXv9KdYt1Ra",
                "numberOfPeriods": 12,
                "paymentInterval": 1,
                "orderId": "SUB20260928003",
                "userName": "王小明",
                "userEmail": "ming@example.com",
                "productDetails": [
                  {
                    "productionCode": "PLAN-M",
                    "description": "月費會員",
                    "quantity": 1,
                    "unit": "月",
                    "unitPrice": 299
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/transactions/{id}": {
      "get": {
        "operationId": "get-transaction",
        "summary": "查詢交易明細",
        "description": "查詢一筆交易的最新狀態。收到付款通知後，請用這支回查確認結果再出貨。**請用 27 字元的 `id` 查詢**；用 `P` 開頭的交易編號也查得到，但回應不會有 `productDetails` 與 `numberOfPeriods`。",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "交易的內部 id（建立交易時回傳的 `id`，或付款通知裡的 `id`），也可以是 `P` 開頭的交易編號。",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "回傳 [Transaction 物件](/api/objects/transaction/)",
            "content": {
              "application/json": {
                "example": {
                  "code": "S0000",
                  "data": {
                    "id": "P20260928AB12CD34",
                    "transactionId": "2HhndgEquCbDzC5OyVxWSGZmd2l",
                    "action": "onetime",
                    "amount": 1200,
                    "paymentMethod": "card",
                    "paymentInfo": {
                      "method": "card",
                      "cardNum": "424242******4242",
                      "cardName": "WANG XIAO MING",
                      "cardType": "Visa",
                      "cardIssuerCountry": "TW"
                    },
                    "status": "charged",
                    "userName": "王小明",
                    "userEmail": "ming@example.com",
                    "orderId": "A20260928001",
                    "createdAt": "2026-09-28T02:40:25.502Z",
                    "paidAt": "2026-09-28T02:41:03.118Z",
                    "refundAmount": 0,
                    "authCode": "831000",
                    "customId": "cart-8812",
                    "use3d": false,
                    "productDetails": [
                      {
                        "productionCode": "SKU-001",
                        "description": "手沖咖啡豆 200g",
                        "quantity": 2,
                        "unit": "包",
                        "unitPrice": 600
                      }
                    ]
                  },
                  "message": ""
                }
              }
            }
          },
          "400": {
            "description": "找不到交易，或交易不屬於你的網域（`V0001`）"
          },
          "401": {
            "description": "token 錯誤"
          }
        }
      }
    },
    "/transactions": {
      "get": {
        "operationId": "list-transactions",
        "summary": "查詢交易列表",
        "description": "依建立時間由新到舊列出交易，每頁 50 筆。**列出的是網域的所有款項**，除了 API 建立的交易，也包含商店訂單、捐款等其他收款，以及撥款後退款產生的負數調整款項。只要 API 交易時，請用 `orderId` 比對，或改用[用訂單編號查詢](/api/list-order-transactions/)。",
        "parameters": [
          {
            "name": "start",
            "in": "query",
            "required": false,
            "description": "起始日期，以台北時間的當天 00:00 起算。可以寫 `2026-09-01`，或 Unix 毫秒時間戳。\n限制：要和 `end` 一起帶；只帶一個會回 500 `F0001`（`Invalid date`）",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "end",
            "in": "query",
            "required": false,
            "description": "結束日期，算到台北時間的當天 23:59:59。",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "下一頁的分頁標記。把上一頁回應的 `page` 原封不動帶入。",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "回傳交易列表與下一頁代碼",
            "content": {
              "application/json": {
                "example": {
                  "code": "S0000",
                  "data": {
                    "transactions": [
                      {
                        "id": "P20260928AB12CD34",
                        "transactionId": "2HhndgEquCbDzC5OyVxWSGZmd2l",
                        "action": "onetime",
                        "amount": 1200,
                        "paymentMethod": "card",
                        "status": "charged",
                        "orderId": "A20260928001",
                        "createdAt": "2026-09-28T02:40:25.502Z",
                        "paidAt": "2026-09-28T02:41:03.118Z",
                        "refundAmount": 0
                      }
                    ],
                    "page": "eyJMaW1pdCI6NTAsIkxhc3RFdmFsdWF0ZWRLZXkiOnt9fQ=="
                  },
                  "message": ""
                }
              }
            }
          },
          "401": {
            "description": "token 錯誤"
          },
          "500": {
            "description": "日期格式錯誤或 `page` 分頁標記無效（`F0001`）"
          }
        }
      }
    },
    "/order/{orderId}/transactions": {
      "get": {
        "operationId": "list-order-transactions",
        "summary": "用訂單編號查詢交易",
        "description": "列出同一個 `orderId` 的所有 API 交易，包含失敗的交易與定期定額每一期。一次回傳全部，不分頁，也不保證順序。消費者重試付款、或結帳頁過期後重新建立時，一個訂單可能有多筆交易，請用這支確認有沒有成功的那一筆。",
        "parameters": [
          {
            "name": "orderId",
            "in": "path",
            "required": true,
            "description": "建立交易時帶的 `orderId`。",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "回傳交易陣列。查無資料時是空陣列",
            "content": {
              "application/json": {
                "example": {
                  "code": "S0000",
                  "data": {
                    "transactions": [
                      {
                        "id": "P20260928AB12CD34",
                        "transactionId": "2HhndgEquCbDzC5OyVxWSGZmd2l",
                        "action": "onetime",
                        "amount": 1200,
                        "paymentMethod": "card",
                        "status": "charged",
                        "orderId": "A20260928001",
                        "createdAt": "2026-09-28T02:40:25.502Z",
                        "paidAt": "2026-09-28T02:41:03.118Z",
                        "refundAmount": 0
                      }
                    ]
                  },
                  "message": ""
                }
              }
            }
          },
          "401": {
            "description": "token 錯誤"
          }
        }
      }
    },
    "/refunds/{transactionHid}": {
      "post": {
        "operationId": "refund",
        "summary": "退款",
        "description": "為一筆交易退款。**每筆交易只能用 API 成功退款一次**，部分退款後剩下的金額不能再退，請一次決定好金額。信用卡、Apple Pay、LINE Pay 即時退款；已付款的超商代碼與 ATM 要帶退款帳戶，由應援匯款；尚未繳費的超商代碼會直接取消代碼。",
        "parameters": [
          {
            "name": "transactionHid",
            "in": "path",
            "required": true,
            "description": "`P` 開頭的交易編號（17 字元）。不接受 27 字元的內部 id。",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "退款已受理。回傳更新後的 [Transaction 物件](/api/objects/transaction/)，另加 `success: true`",
            "content": {
              "application/json": {
                "example": {
                  "code": "S0000",
                  "data": {
                    "success": true,
                    "id": "P20260928AB12CD34",
                    "transactionId": "2HhndgEquCbDzC5OyVxWSGZmd2l",
                    "action": "onetime",
                    "amount": 1200,
                    "paymentMethod": "card",
                    "status": "refunded",
                    "orderId": "A20260928001",
                    "createdAt": "2026-09-28T02:40:25.502Z",
                    "paidAt": "2026-09-28T02:41:03.118Z",
                    "refundAmount": 600,
                    "refundedAt": "2026-09-28T03:00:00.000Z",
                    "authCode": "831000"
                  },
                  "message": ""
                }
              }
            }
          },
          "400": {
            "description": "參數錯誤、交易狀態不能退款，或收單機構退款失敗"
          },
          "401": {
            "description": "token 錯誤"
          },
          "500": {
            "description": "系統錯誤，或網域待撥款金額不足（見下方錯誤表）"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "merchantId": {
                    "type": "string",
                    "description": "你的網域名稱。例如應援頁是 `https://ming.oen.tw`，就填 `ming`。必須與 token 所屬的網域相同，不同會回 400 `V0001`。",
                    "examples": [
                      "ming"
                    ]
                  },
                  "amount": {
                    "type": "integer",
                    "description": "退款金額。不帶就是全額退款。\n限制：1 以上，不能大於原交易金額"
                  },
                  "reason": {
                    "type": "string",
                    "description": "退款原因。"
                  },
                  "productDetails": {
                    "type": "array",
                    "description": "原交易有開立電子發票時必填，用來開立折讓。品項合計必須等於退款金額。欄位同建立交易時的 `productDetails`。",
                    "items": {
                      "type": "string"
                    }
                  },
                  "remitInfo": {
                    "type": "object",
                    "description": "退款匯款帳戶。**已付款的超商代碼或 ATM 交易**必填；信用卡類與尚未繳費的超商代碼不用帶。",
                    "properties": {
                      "bankCode": {
                        "type": "string",
                        "description": "銀行代碼"
                      },
                      "bankName": {
                        "type": "string",
                        "description": "銀行名稱"
                      },
                      "branchCode": {
                        "type": "string",
                        "description": "分行代碼"
                      },
                      "branchName": {
                        "type": "string",
                        "description": "分行名稱"
                      },
                      "account": {
                        "type": "string",
                        "description": "帳號\n限制：8 到 14 字元"
                      },
                      "accountName": {
                        "type": "string",
                        "description": "戶名"
                      }
                    },
                    "required": [
                      "bankCode",
                      "bankName",
                      "branchCode",
                      "branchName",
                      "account",
                      "accountName"
                    ]
                  }
                },
                "required": [
                  "merchantId"
                ]
              },
              "example": {
                "merchantId": "ming",
                "amount": 600,
                "reason": "消費者取消一包",
                "productDetails": [
                  {
                    "productionCode": "SKU-001",
                    "description": "手沖咖啡豆 200g",
                    "quantity": 1,
                    "unit": "包",
                    "unitPrice": 600
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/subscriptions/{id}": {
      "get": {
        "operationId": "get-subscription",
        "summary": "查詢定期定額明細",
        "description": "查詢一筆 Payment API 定期定額的狀態、期數與下次扣款時間。",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "`S` 開頭的定期定額編號，或定期定額的內部 id。",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "回傳 [Subscription 物件](/api/objects/subscription/)",
            "content": {
              "application/json": {
                "example": {
                  "code": "S0000",
                  "data": {
                    "id": "S20260928EF56GH78",
                    "status": "ongoing",
                    "period": 1,
                    "numberOfPeriods": 12,
                    "paymentInterval": 1,
                    "startedAt": "2026-09-28T02:44:35.592Z",
                    "endedAt": "2027-08-28T02:44:35.592Z",
                    "nextChargeAt": "2026-10-28T01:00:00.000Z",
                    "createdAt": "2026-09-28T02:44:35.592Z",
                    "amount": 299,
                    "userName": "王小明",
                    "orderId": "SUB20260928001"
                  },
                  "message": ""
                }
              }
            }
          },
          "400": {
            "description": "找不到，或不屬於你的網域（`V0001`）"
          },
          "401": {
            "description": "token 錯誤"
          }
        }
      }
    },
    "/subscriptions": {
      "get": {
        "operationId": "list-subscriptions",
        "summary": "查詢商店定期購訂單列表",
        "description": "**列出的是應援商店的「定期購」訂單**，不是用 Payment API 建立的定期定額。只有在應援商店販售訂閱制商品的商家才需要。Payment API 定期定額請用[查詢定期定額明細](/api/get-subscription/)。依建立時間由新到舊，每頁最多 50 筆；用 `status` 篩選時，一頁可能少於 50 筆但仍有下一頁。",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "用逗號分隔的狀態。不帶就是全部。",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "下一頁的分頁標記。把上一頁回應的 `page` 原封不動帶入。",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "回傳定期購訂單列表與下一頁代碼"
          },
          "401": {
            "description": "token 錯誤"
          }
        }
      }
    },
    "/subscriptions/{subscriptionHid}": {
      "put": {
        "operationId": "cancel-subscription",
        "summary": "取消定期定額",
        "description": "取消一筆 Payment API 定期定額，之後不會再扣款。只能取消進行中、已排程、扣款失敗待重扣的定期定額。**請一定要送 body**，至少帶 `merchantId`。",
        "parameters": [
          {
            "name": "subscriptionHid",
            "in": "path",
            "required": true,
            "description": "`S` 開頭的定期定額編號（17 字元）。不接受內部 id。",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "取消成功，回傳更新後的定期定額",
            "content": {
              "application/json": {
                "example": {
                  "code": "S0000",
                  "data": {
                    "id": "S20260928EF56GH78",
                    "status": "cancelled",
                    "period": 1,
                    "paymentInterval": 1,
                    "startedAt": "2026-09-28T02:31:46.640Z",
                    "cancelledAt": "2026-09-28T02:35:00.000Z",
                    "reason": "會員申請取消",
                    "createdAt": "2026-09-28T02:31:46.640Z"
                  },
                  "message": ""
                }
              }
            }
          },
          "400": {
            "description": "找不到，或目前狀態不能取消"
          },
          "401": {
            "description": "token 錯誤"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "merchantId": {
                    "type": "string",
                    "description": "你的網域名稱。例如應援頁是 `https://ming.oen.tw`，就填 `ming`。必須與 token 所屬的網域相同，不同會回 400 `V0001`。",
                    "examples": [
                      "ming"
                    ]
                  },
                  "reason": {
                    "type": "string",
                    "description": "取消原因。"
                  }
                },
                "required": [
                  "merchantId"
                ]
              },
              "example": {
                "merchantId": "ming",
                "reason": "會員申請取消"
              }
            }
          }
        }
      }
    }
  }
}