> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# 支付 AceDataCloud 平台訂單

> Platform 整合指南 - Ace Data Cloud

為 `Pending` 訂單建立或重新整理支付工作階段。支付動作會存取支付管道並可能改變訂單狀態，呼叫前必須確認訂單 ID、金額和支付方式。

## 介面概覽

| 項 | 內容 |
| - | - |
| 方法 | `POST` |
| URL | `https://platform.acedata.cloud/api/v1/orders/{order_id}/pay/` |
| 驗證 | 託管跳轉類支付可匿名；其他方式需要登入狀態或 Account Token |
| Body | JSON，未支付訂單必須提供 `pay_way` |

## 匿名支付的邊界

匿名存取用於開啟複製的支付連結後登入狀態遺失的情境，不需要也不應攜帶長期 Account Token。匿名呼叫：

* 僅允許伺服器設定的託管跳轉支付方式；
* 固定使用桌面支付頁面；
* 不能領取零價訂單；
* 受 IP 和單一訂單限流；
* 傳回最小訂單投影，不包含帳戶、Application 或內部 metadata。

已驗證呼叫者必須是訂單擁有者或超級管理員。X402、獎勵兌換等需要使用者上下文的方式不能匿名呼叫。

## 請求範例

```shell theme={null}
export ORDER_ID='你的 Pending 訂單 ID'

curl -X POST \
  "https://platform.acedata.cloud/api/v1/orders/${ORDER_ID}/pay/" \
  -H 'Content-Type: application/json' \
  -d '{"pay_way":"Stripe"}'
```

需要驗證的支付方式：

```shell theme={null}
export PLATFORM_TOKEN='你的帳戶權杖'

curl -X POST \
  "https://platform.acedata.cloud/api/v1/orders/${ORDER_ID}/pay/" \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"pay_way":"X402"}'
```

`pay_way` 使用訂單模型支援的真實值，例如 `WechatPay`、`AliPay`、`Stripe`、`Card`、`Airwallex`、`X402`、`PayPal`、`AppleIAP`、`Reward`、`BankTransfer`。並非每個值都對匿名請求或每個站點開放。

## 回應說明

成功回應是更新後的訂單物件，通常透過 `pay_url` 提供下一步入口；不同支付方式還可能在受控欄位中傳回用戶端繼續支付所需的資訊。匿名回應使用最小欄位白名單，已驗證的擁有者取得完整詳情。

不要依賴 `payment_url`、`qr_code_url` 或 `payment_method` 等舊欄位名稱；目前 Order 契約使用 `pay_url` 和 `pay_way`。

## iOS 內購

已登入的訂單擁有者可傳入 `pay_way: "AppleIAP"`。此請求依所選套餐的 `metadata.apple_price` 更新待付款訂單並清除折扣，不產生扣款、不發放點數，也不傳回支付連結。舊待付款訂單應先完成這一步，再發起 Apple 原生付款。僅支援一個已設定 Apple 商品和價格的 Usage 套餐；不支援的套餐或批次訂單傳回 `400`。

Apple 原生付款後透過 `/api/v1/orders/{id}/apple-verify/` 提交 `transaction_id` 完成伺服器端驗證和點數發放。點數數量來自套餐；金額使用 Apple 獨立美元預設價格，不疊加會員折扣或站點加價，其他地區的本幣扣款金額以 Apple 確認頁為準。

## 錯誤與重試

* 訂單不是 `Pending`：傳回 `400`；不要重複建立支付工作階段。
* 未提供 `pay_way`：非零金額訂單傳回 `400`。
* 匿名呼叫使用了不允許的方式或零價訂單：傳回 `403`，登入後由擁有者重試。
* 已驗證但不是訂單擁有者：傳回 `403`。
* 支付管道失敗：不要盲目重複提交；先查詢訂單詳情，確認仍是 `Pending` 後再重試。

## 相關介面

* [建立儲值訂單](https://platform.acedata.cloud/documents/platform-order-create)
* [取得訂單詳情](https://platform.acedata.cloud/documents/platform-order-detail)
* [重新整理訂單狀態](https://platform.acedata.cloud/documents/platform-order-refresh)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.