curl --request POST \
--url https://api.zangsho.com/v1/orders \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"order_no": "ORD-20260109-001",
"amount": "990.00",
"status": "paid",
"customer_email": "customer@example.com",
"customer_name": "王小明",
"currency": "TWD",
"payment_method": "credit_card",
"billing_cycle": "monthly",
"paid_at": "2026-01-09T08:00:00Z"
}
'{
"data": {
"id": 123,
"order_no": "<string>",
"amount": "<string>",
"currency": "TWD",
"status": "pending",
"payment_method": "credit_card",
"source": "api",
"billing_cycle": "<string>",
"paid_at": "2023-11-07T05:31:56Z",
"refunded_at": "2023-11-07T05:31:56Z",
"failed_at": "2023-11-07T05:31:56Z",
"metadata": {},
"customer_email": "<string>",
"customer_name": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}
}{
"message": "Unauthenticated."
}{
"message": "The given data was invalid.",
"errors": {
"email": [
"The email field is required.",
"The email must be a valid email address."
]
}
}訂單 Orders
建立訂單
建立單一訂單。
Webhook 觸發
- 建立成功時觸發
order.created事件 - 若 status 為
paid，同時觸發order.paid事件
時間戳記自動填入
若建立訂單時指定了 status 但未提供對應的時間欄位，系統會自動填入當前時間：
status: paid→ 自動填入paid_atstatus: refunded→ 自動填入refunded_atstatus: failed→ 自動填入failed_at
如果你已提供時間欄位（例如匯入歷史資料時），系統不會覆蓋你提供的值。
冪等處理
可透過 X-Idempotency-Key header 實現冪等，重複請求會回傳相同結果。
POST
/
orders
curl --request POST \
--url https://api.zangsho.com/v1/orders \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"order_no": "ORD-20260109-001",
"amount": "990.00",
"status": "paid",
"customer_email": "customer@example.com",
"customer_name": "王小明",
"currency": "TWD",
"payment_method": "credit_card",
"billing_cycle": "monthly",
"paid_at": "2026-01-09T08:00:00Z"
}
'{
"data": {
"id": 123,
"order_no": "<string>",
"amount": "<string>",
"currency": "TWD",
"status": "pending",
"payment_method": "credit_card",
"source": "api",
"billing_cycle": "<string>",
"paid_at": "2023-11-07T05:31:56Z",
"refunded_at": "2023-11-07T05:31:56Z",
"failed_at": "2023-11-07T05:31:56Z",
"metadata": {},
"customer_email": "<string>",
"customer_name": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}
}{
"message": "Unauthenticated."
}{
"message": "The given data was invalid.",
"errors": {
"email": [
"The email field is required.",
"The email must be a valid email address."
]
}
}Authorizations
使用 Laravel Sanctum Token 進行認證。
Token 可在商家後台的「API 設定」頁面取得。
Headers
冪等鍵（24 小時內有效）
Body
application/json
訂單編號（商家內唯一）
Example:
"ORD-20260109-001"
訂單金額
Example:
"990.00"
客戶 Email（不存在會自動建立客戶）
訂單狀態
Available options:
pending, paid, failed, refunded, cancelled 客戶姓名（建立新客戶時使用）
幣別，使用 ISO 4217 貨幣代碼。預設為 TWD（新台幣）。
常見幣別：
| 代碼 | 說明 |
|---|---|
TWD | 新台幣 |
USD | 美元 |
JPY | 日圓 |
HKD | 港幣 |
SGD | 新加坡幣 |
CNY | 人民幣 |
KRW | 韓元 |
MYR | 馬來西亞令吉 |
THB | 泰銖 |
EUR | 歐元 |
GBP | 英鎊 |
Example:
"TWD"
付款方式。支援以下選項：
| 值 | 說明 |
|---|---|
credit_card | 信用卡 |
atm | ATM 轉帳 |
cvs | 超商繳費（代碼繳費） |
line_pay | LINE Pay |
jkopay | 街口支付 |
apple_pay | Apple Pay |
Available options:
credit_card, atm, cvs, line_pay, jkopay, apple_pay Example:
"credit_card"
訂閱週期（影響 MRR 計算）
Available options:
monthly, quarterly, semi-annual, yearly, one-time 付款時間（若未提供且 status 為 paid，系統自動填入當前時間）
退款時間（若未提供且 status 為 refunded，系統自動填入當前時間）
付款失敗時間（若未提供且 status 為 failed，系統自動填入當前時間）
自訂欄位
Response
訂單建立成功
Show child attributes
Show child attributes