Skip to Content
概念注文

注文

CheckoutSession がバイヤーが目にするものなら、 Order は あなた が気にするものです。次の永続的レコードです:

  • 何が買われていたか (行明細)
  • いくら未払いで、実際にいくら支払われたか
  • 未処理 / 適用済みの返金
  • あなたの外部参照 (external_ref) — 通常は独自の注文 ID で、 Order に保存され GET /b2b/v1/orders/{id} で返されます (Webhook ペイロードにはエコーされません — 下記参照)

CheckoutSession は PaymentIntent の 1 つが精算するか TTL が切れると 死にます。Order は永遠に残ります。

Order が作成されるタイミング

POST /b2b/v1/checkout-sessions/quick を呼ぶと、payment-service は 新しい Order と 新しい CheckoutSession を 両方 1 つのトランザクション で作成します。既に Order があってチェックアウトをリトライしたい場合 (例: バイヤーが放棄した後) は、代わりに POST /b2b/v1/checkout-sessions を使って既存の注文に新しいセッションを 紐付けてください — 監査トレイルを保持します。

ライフサイクル

状態意味
DRAFT将来のドラフトフローのために予約済み。現時点でこの状態を作成するコードパスはありません — すべての注文は PENDING で作成されるため、この状態が観測されることはありません。
PENDINGCheckoutSession が live で未解決。
PAID全額が精算。Webhook payment.settled がここで発火。 フルフィルメント可。
PARTIAL_PAID資金は届いたが合計より少ない。下記「過少支払い」を参照。
CANCELEDセッション期限切れ、またはマーチャントがキャンセル。metadata.canceled_reason で理由 (payment_timeout, merchant_canceled, …) を説明。
REFUNDED支払い額がすべて返金された。
PARTIALLY_REFUNDED一部の返金が実行されたが、残りは支払い済みのまま。

フルフィルメントロジックを切り替える対象状態は PAID で、 CheckoutSession の COMPLETED ではありません。payment.settled Webhook が正式なシグナルです。

external_ref フィールド

セッション作成時に external_ref を含められます (最大 255 文字までの 任意の文字列 — 通常は独自の注文 ID)。これはパイプライン全体を通じて スレッドされます:

  • Order に保存
  • マーチャントダッシュボードでサポート検索用に表示
  • GET /b2b/v1/orders/{id} で返却されるので、Webhook ハンドラが payment.settled 受信後に取得可能

Webhook ペイロードは現状 external_ref を直接エコー しません — 本ドキュメントの以前のドラフトでは data.external_ref がすべての イベントを通って流れると主張していましたが、それは誤りでした。 payment.* Webhook を DB 行にマップし戻すには、ペイロードから order_id を取り、GET /b2b/v1/orders/{id} で注文を取得してください。 Webhook ペイロード上のネイティブな external_ref フィールドは ロードマップ上にあります。

過少支払い

バイヤーのオンチェーン送金が注文合計に届かずに確定すると、Order は PARTIAL_PAID に移ります。3 つの選択肢があります:

  1. 受け入れて解決。 注文を PAID に遷移させ、order.resolved を 発火。これは 公開 REST エンドポイントではありません — 解決は 現状内部 / 運用アクションなので、セルフサーブフローではオプション 2 (残額を回収) を推奨します。
  2. 残額を待つ。 同じ Order に対して amount_due = 残額の新しい CheckoutSession を作成します。バイヤーが差額を支払うと、それが 精算したときに Order は PAID に移ります。
  3. キャンセルして返金。 部分額を返金して Order をキャンセル。 チェーン手数料はバイヤーの責任です。

製品はここで推奨を示していません — マーチャントによってポリシーが 異なります。1 つを選んで管理画面に組み込んでください。

返金

返金は別の API サーフェスで、別のコンセプトページです。 コンセプト → 返金 を参照してください。

API エンドポイント

メソッドパス備考
POST/b2b/v1/ordersセッションなしで Order を作成 (レア)
GET/b2b/v1/orders/:order_id行明細 + 支払い履歴付きで注文を読み取り
PATCH/b2b/v1/orders/:order_id/cancel未払い注文をキャンセル
PATCH/b2b/v1/orders/:order_id/reopen自動キャンセル済み (payment_timeout) 注文を再オープン

次に

セッション返金