{
    "openapi": "3.0.3",
    "info": {
        "title": "沃特嚴選 Merchant API",
        "version": "2.7.0",
        "description": "商戶收單、代付、付款通道跳轉連結、商戶固定 / 自訂金額、查詢、餘額、銀行列表與回調重送 API。sign 請由商戶後端以 API Secret 計算。"
    },
    "servers": [
        {
            "url": "https://api-test.wattt.asia",
            "description": "正式商戶 API Host"
        }
    ],
    "tags": [
        {
            "name": "Payment Link",
            "description": "取得付款通道與天空交易所跳轉連結"
        },
        {
            "name": "Collection",
            "description": "收單"
        },
        {
            "name": "Payout",
            "description": "代付"
        },
        {
            "name": "Query",
            "description": "查詢與輔助資料"
        }
    ],
    "paths": {
        "/api/v1/merchant/payment-channels": {
            "post": {
                "tags": [
                    "Payment Link"
                ],
                "summary": "取得可用付款通道",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/SignedUidRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/BasicResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation or signature error"
                    }
                }
            }
        },
        "/api/v1/merchant/payment-amounts": {
            "post": {
                "tags": [
                    "Payment Link"
                ],
                "summary": "取得商戶可選固定金額與自訂金額範圍",
                "description": "商戶前端顯示儲值金額前，先由商戶後端呼叫此 API 取得後台設定的 fixed_amounts、allow_custom、custom_min、custom_max。",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/SignedUidRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PaymentAmountsResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation or signature error"
                    }
                }
            }
        },
        "/api/v1/merchant/payment-links/amount": {
            "post": {
                "tags": [
                    "Payment Link"
                ],
                "summary": "使用商戶端已選金額產生待付款短網址",
                "description": "商戶會員在商戶端已選定固定金額或自訂金額後，由商戶後端帶 amount 呼叫此 API。系統會驗證 amount 是否符合後台設定，並由後端直接建立天空交易所待付款頁，成功後只回傳 /sky/purchase/wait/{token} 短網址；商戶不需要也不會收到一大串 query_params。",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/PaymentLinkAmountRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PaymentLinkResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation or signature error"
                    }
                }
            }
        },
        "/api/v1/merchant/payment-links": {
            "post": {
                "tags": [
                    "Payment Link"
                ],
                "summary": "取得天空交易所儲值跳轉連結",
                "description": "商戶後端取得 data.redirect_url / redirect_url 後，直接讓會員前往該 URL；商戶不需要自行組 query_params。建議一併帶入付款會員銀行資料 payer_bank_name / payer_account_no，供 APP 代理核對入款。",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/PaymentLinkRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PaymentLinkResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation or signature error"
                    }
                }
            }
        },
        "/api/v1/merchant/collections": {
            "post": {
                "tags": [
                    "Collection"
                ],
                "summary": "建立收單",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CollectionRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/BasicResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation or signature error"
                    }
                }
            }
        },
        "/api/v1/merchant/collections/status": {
            "post": {
                "tags": [
                    "Collection"
                ],
                "summary": "收單查詢",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CollectionStatusRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/BasicResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation or signature error"
                    }
                }
            }
        },
        "/api/v1/merchant/payouts": {
            "post": {
                "tags": [
                    "Payout"
                ],
                "summary": "建立代付",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/PayoutRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/BasicResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation or signature error"
                    }
                }
            }
        },
        "/api/v1/merchant/payouts/status": {
            "post": {
                "tags": [
                    "Payout"
                ],
                "summary": "代付查詢",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/PayoutStatusRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/BasicResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation or signature error"
                    }
                }
            }
        },
        "/api/v1/merchant/balance": {
            "post": {
                "tags": [
                    "Query"
                ],
                "summary": "商戶餘額",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/SignedUidRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/BasicResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation or signature error"
                    }
                }
            }
        },
        "/api/v1/merchant/banks": {
            "get": {
                "tags": [
                    "Query"
                ],
                "summary": "銀行列表",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "description": "銀行代碼或名稱關鍵字"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/BasicResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation or signature error"
                    }
                }
            }
        },
        "/api/v1/merchant/callbacks/retry": {
            "post": {
                "tags": [
                    "Query"
                ],
                "summary": "回調重送",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CallbackRetryRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/BasicResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation or signature error"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "SignedUidRequest": {
                "type": "object",
                "required": [
                    "uid",
                    "timestamp",
                    "sign"
                ],
                "properties": {
                    "uid": {
                        "type": "string",
                        "example": "ABCDE"
                    },
                    "timestamp": {
                        "type": "integer",
                        "example": 1782347899
                    },
                    "sign": {
                        "type": "string",
                        "example": "PLEASE_CALCULATE_SIGN_BY_SECRET"
                    }
                }
            },
            "PaymentLinkRequest": {
                "type": "object",
                "required": [
                    "uid",
                    "merchant_order_no",
                    "member_no",
                    "member_name",
                    "notify_url",
                    "timestamp",
                    "sign"
                ],
                "properties": {
                    "uid": {
                        "type": "string",
                        "example": "ABCDE"
                    },
                    "timestamp": {
                        "type": "integer",
                        "example": 1782347899
                    },
                    "sign": {
                        "type": "string",
                        "example": "PLEASE_CALCULATE_SIGN_BY_SECRET"
                    },
                    "channel": {
                        "type": "string",
                        "example": "sky_coin"
                    },
                    "merchant_order_no": {
                        "type": "string",
                        "example": "TP202605230001"
                    },
                    "member_no": {
                        "type": "string",
                        "example": "U10001"
                    },
                    "member_account": {
                        "type": "string",
                        "example": "xinlun_user_10001"
                    },
                    "member_name": {
                        "type": "string",
                        "example": "測試會員"
                    },
                    "member_phone": {
                        "type": "string",
                        "example": "0912345678"
                    },
                    "member_email": {
                        "type": "string",
                        "example": "member10001@example.com"
                    },
                    "payer_name": {
                        "type": "string",
                        "example": "測試會員",
                        "description": "付款人姓名；未填時可等於 member_name"
                    },
                    "payer_bank_name": {
                        "type": "string",
                        "example": "華南銀行",
                        "description": "付款會員銀行名稱，會帶到付款頁與 APP 代理核對資訊"
                    },
                    "payer_bank_code": {
                        "type": "string",
                        "example": "008"
                    },
                    "payer_account_no": {
                        "type": "string",
                        "example": "008123456789",
                        "description": "付款會員完整銀行帳號；系統會轉成 customer_bank_account / member_bank_account"
                    },
                    "payer_account_last5": {
                        "type": "string",
                        "example": "56789"
                    },
                    "payerAccountNumber": {
                        "type": "string",
                        "example": "008123456789",
                        "description": "camelCase 相容欄位"
                    },
                    "payeeAccountNumber": {
                        "type": "string",
                        "example": "56789",
                        "description": "既有核帳欄位相容，放付款帳號末五碼"
                    },
                    "member_bank_name": {
                        "type": "string",
                        "example": "華南銀行",
                        "description": "舊相容欄位"
                    },
                    "member_bank_account": {
                        "type": "string",
                        "example": "008123456789",
                        "description": "舊相容欄位；新商戶建議送 payer_account_no"
                    },
                    "notify_url": {
                        "type": "string",
                        "example": "https://merchant.example.com/notify/collection"
                    },
                    "return_url": {
                        "type": "string",
                        "example": "https://merchant.example.com/return"
                    },
                    "extra": {
                        "type": "object",
                        "additionalProperties": true
                    }
                }
            },
            "PaymentLinkAmountRequest": {
                "type": "object",
                "required": [
                    "uid",
                    "merchant_order_no",
                    "amount",
                    "member_no",
                    "member_name",
                    "notify_url",
                    "timestamp",
                    "sign"
                ],
                "properties": {
                    "uid": {
                        "type": "string",
                        "example": "ABCDE"
                    },
                    "timestamp": {
                        "type": "integer",
                        "example": 1782347899
                    },
                    "sign": {
                        "type": "string",
                        "example": "PLEASE_CALCULATE_SIGN_BY_SECRET"
                    },
                    "channel": {
                        "type": "string",
                        "example": "sky_coin"
                    },
                    "merchant_order_no": {
                        "type": "string",
                        "example": "TP202605270001"
                    },
                    "amount": {
                        "type": "integer",
                        "example": 5000,
                        "description": "商戶端已選定的固定或自訂金額；需符合 /payment-amounts 回傳設定。"
                    },
                    "member_no": {
                        "type": "string",
                        "example": "U10001"
                    },
                    "member_account": {
                        "type": "string",
                        "example": "xinlun_user_10001"
                    },
                    "member_name": {
                        "type": "string",
                        "example": "測試會員"
                    },
                    "member_phone": {
                        "type": "string",
                        "example": "0912345678"
                    },
                    "payer_bank_name": {
                        "type": "string",
                        "example": "華南銀行"
                    },
                    "payer_bank_code": {
                        "type": "string",
                        "example": "008"
                    },
                    "payer_account_no": {
                        "type": "string",
                        "example": "008123456789"
                    },
                    "payer_account_last5": {
                        "type": "string",
                        "example": "56789"
                    },
                    "notify_url": {
                        "type": "string",
                        "example": "https://merchant.example.com/notify/collection"
                    },
                    "return_url": {
                        "type": "string",
                        "example": "https://merchant.example.com/return"
                    },
                    "extra": {
                        "type": "object",
                        "additionalProperties": true
                    }
                }
            },
            "PaymentAmountsResponse": {
                "type": "object",
                "properties": {
                    "ok": {
                        "type": "integer",
                        "example": 1
                    },
                    "message": {
                        "type": "string",
                        "example": "success"
                    },
                    "data": {
                        "type": "object",
                        "properties": {
                            "currency": {
                                "type": "string",
                                "example": "TWD"
                            },
                            "fixed_amounts": {
                                "type": "array",
                                "items": {
                                    "type": "integer"
                                },
                                "example": [
                                    1000,
                                    2000,
                                    3000,
                                    5000,
                                    8000,
                                    10000
                                ]
                            },
                            "allow_custom": {
                                "type": "boolean",
                                "example": true
                            },
                            "custom_min": {
                                "type": "number",
                                "example": 1000
                            },
                            "custom_max": {
                                "type": "number",
                                "example": 30000
                            },
                            "payment_link_endpoint": {
                                "type": "string",
                                "example": "/api/v1/merchant/payment-links/amount"
                            }
                        }
                    }
                }
            },
            "CollectionRequest": {
                "type": "object",
                "required": [
                    "uid",
                    "orderid",
                    "amount",
                    "timestamp",
                    "sign"
                ],
                "properties": {
                    "uid": {
                        "type": "string",
                        "example": "ABCDE"
                    },
                    "timestamp": {
                        "type": "integer",
                        "example": 1782347899
                    },
                    "sign": {
                        "type": "string",
                        "example": "PLEASE_CALCULATE_SIGN_BY_SECRET"
                    },
                    "orderid": {
                        "type": "string",
                        "example": "COL202605230001"
                    },
                    "merchant_order_no": {
                        "type": "string",
                        "example": "M-COL202605230001"
                    },
                    "amount": {
                        "type": "number",
                        "example": 2500
                    },
                    "notify_url": {
                        "type": "string",
                        "example": "https://merchant.example.com/notify/collection"
                    }
                }
            },
            "CollectionStatusRequest": {
                "type": "object",
                "required": [
                    "uid",
                    "timestamp",
                    "sign"
                ],
                "properties": {
                    "uid": {
                        "type": "string",
                        "example": "ABCDE"
                    },
                    "timestamp": {
                        "type": "integer",
                        "example": 1782347899
                    },
                    "sign": {
                        "type": "string",
                        "example": "PLEASE_CALCULATE_SIGN_BY_SECRET"
                    },
                    "orderid": {
                        "type": "string",
                        "example": "COL202605230001"
                    },
                    "merchant_order_no": {
                        "type": "string",
                        "example": "M-COL202605230001"
                    }
                }
            },
            "PayoutRequest": {
                "type": "object",
                "required": [
                    "uid",
                    "serial_no",
                    "amount",
                    "payee_name",
                    "timestamp",
                    "sign"
                ],
                "properties": {
                    "uid": {
                        "type": "string",
                        "example": "ABCDE"
                    },
                    "timestamp": {
                        "type": "integer",
                        "example": 1782347899
                    },
                    "sign": {
                        "type": "string",
                        "example": "PLEASE_CALCULATE_SIGN_BY_SECRET"
                    },
                    "serial_no": {
                        "type": "string",
                        "example": "PO202605230001"
                    },
                    "amount": {
                        "type": "number",
                        "example": 3000
                    },
                    "payee_name": {
                        "type": "string",
                        "example": "王小明"
                    },
                    "payee_bank": {
                        "type": "string",
                        "example": "中國信託"
                    },
                    "payee_account": {
                        "type": "string",
                        "example": "822123456789012"
                    },
                    "notify_url": {
                        "type": "string",
                        "example": "https://merchant.example.com/notify/payout"
                    },
                    "reverse_url": {
                        "type": "string",
                        "example": "https://merchant.example.com/notify/payout-failed"
                    }
                }
            },
            "PayoutStatusRequest": {
                "type": "object",
                "required": [
                    "uid",
                    "timestamp",
                    "sign"
                ],
                "properties": {
                    "uid": {
                        "type": "string",
                        "example": "ABCDE"
                    },
                    "timestamp": {
                        "type": "integer",
                        "example": 1782347899
                    },
                    "sign": {
                        "type": "string",
                        "example": "PLEASE_CALCULATE_SIGN_BY_SECRET"
                    },
                    "serial_no": {
                        "type": "string",
                        "example": "PO202605230001"
                    },
                    "merchant_order_no": {
                        "type": "string",
                        "example": "M-PO202605230001"
                    }
                }
            },
            "CallbackRetryRequest": {
                "type": "object",
                "required": [
                    "uid",
                    "type",
                    "timestamp",
                    "sign"
                ],
                "properties": {
                    "uid": {
                        "type": "string",
                        "example": "ABCDE"
                    },
                    "timestamp": {
                        "type": "integer",
                        "example": 1782347899
                    },
                    "sign": {
                        "type": "string",
                        "example": "PLEASE_CALCULATE_SIGN_BY_SECRET"
                    },
                    "type": {
                        "type": "string",
                        "enum": [
                            "collection",
                            "payout"
                        ],
                        "example": "collection"
                    },
                    "orderid": {
                        "type": "string",
                        "example": "COL202605230001"
                    },
                    "serial_no": {
                        "type": "string",
                        "example": "PO202605230001"
                    }
                }
            },
            "BasicResponse": {
                "type": "object",
                "properties": {
                    "ok": {
                        "type": "integer",
                        "example": 1
                    },
                    "message": {
                        "type": "string",
                        "example": "success"
                    },
                    "data": {
                        "type": "object",
                        "additionalProperties": true
                    }
                }
            },
            "PaymentLinkResponse": {
                "type": "object",
                "properties": {
                    "ok": {
                        "type": "integer",
                        "example": 1
                    },
                    "message": {
                        "type": "string",
                        "example": "success"
                    },
                    "url": {
                        "type": "string",
                        "example": "https://coin.mpglobal.asia/sky/purchase/wait/07lcAEjhukIcS8BnRem3e1m4LMpRJ562zBR2Mouv8nHa8x8T",
                        "description": "可直接導向的付款 URL；payment-links/amount 會回傳 wait 短網址。"
                    },
                    "redirect_url": {
                        "type": "string",
                        "example": "https://coin.mpglobal.asia/sky/purchase/wait/07lcAEjhukIcS8BnRem3e1m4LMpRJ562zBR2Mouv8nHa8x8T",
                        "description": "同 url，商戶前端直接跳轉此欄位即可。"
                    },
                    "payment_url": {
                        "type": "string",
                        "example": "https://coin.mpglobal.asia/sky/purchase/wait/07lcAEjhukIcS8BnRem3e1m4LMpRJ562zBR2Mouv8nHa8x8T",
                        "description": "同 url / redirect_url。"
                    },
                    "method": {
                        "type": "string",
                        "example": "GET"
                    },
                    "amount": {
                        "type": "integer",
                        "example": 5000,
                        "nullable": true
                    },
                    "amount_mode": {
                        "type": "string",
                        "example": "fixed",
                        "nullable": true
                    },
                    "data": {
                        "type": "object",
                        "properties": {
                            "url": {
                                "type": "string",
                                "example": "https://coin.mpglobal.asia/sky/purchase/wait/07lcAEjhukIcS8BnRem3e1m4LMpRJ562zBR2Mouv8nHa8x8T"
                            },
                            "redirect_url": {
                                "type": "string",
                                "example": "https://coin.mpglobal.asia/sky/purchase/wait/07lcAEjhukIcS8BnRem3e1m4LMpRJ562zBR2Mouv8nHa8x8T"
                            },
                            "payment_url": {
                                "type": "string",
                                "example": "https://coin.mpglobal.asia/sky/purchase/wait/07lcAEjhukIcS8BnRem3e1m4LMpRJ562zBR2Mouv8nHa8x8T"
                            },
                            "method": {
                                "type": "string",
                                "example": "GET"
                            },
                            "merchant_order_no": {
                                "type": "string",
                                "example": "TP202605230001"
                            },
                            "third_party_session": {
                                "type": "string",
                                "example": "abc123def456ghi789jkl012"
                            },
                            "expires_at": {
                                "type": "string",
                                "example": "2026-05-23 12:30:00"
                            },
                            "wait_url": {
                                "type": "string",
                                "example": "https://coin.mpglobal.asia/sky/purchase/wait/07lcAEjhukIcS8BnRem3e1m4LMpRJ562zBR2Mouv8nHa8x8T"
                            }
                        }
                    }
                }
            }
        }
    }
}