stable · guide · 0.1.0

Sandbox payment lifecycle

準備 Project Credential

Project Backend 需要具 payments:write 與 payments:read scopes 的 sandbox Project Credential。Credential 只能保存在後端或核准的 secret manager，不得放進瀏覽器。

建立 Payment Transaction

每次業務請求使用新的 Idempotency-Key。網路結果不明時，以相同 key 重試，不要產生第二筆 Project Order reference。

Shell example

: "${MINICENTER_PROJECT_CREDENTIAL:?set the sandbox Project Credential}"
: "${MINICENTER_URL:=https://sandbox.minicenter.otus.tw}"
curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer ${MINICENTER_PROJECT_CREDENTIAL}" \
  --header "Idempotency-Key: docs-payment-1" \
  --header "Content-Type: application/json" \
  --data '{"project_order_reference":"sandbox-order-1001","amount":100,"item_name":"Sandbox item","trade_description":"MiniCenter sandbox payment"}' \
  "${MINICENTER_URL}/api/v1/payment-transactions"

回應包含 checkout_url 與簽署過的 checkout_fields。Project Backend 應以 HTML form 把使用者導向該 URL；不要修改欄位，也不要讓瀏覽器持有 Project Credential。

確認結果

瀏覽器返回頁只代表導頁完成。以 payments.transaction.settled Domain Event 或 Payment Transaction read API 確認 settled 狀態，再讓 Project Backend 履行 Project Order。事件採 at-least-once delivery，consumer 必須以事件 ID 去重。