公開されている一覧にないステータスはありますか？
2 つあります。どちらも、対処すべきものというより、紛らわしい観察結果を説明するものとして知っておく価値があります。
2 つ目はマーチャントからよく尋ねられる質問への答えなので、はっきり述べる価値があります。
AUTHORIZATION_REQUIRED は*「決済手段がユーザーの承認を待っている」と「この注文ではまだ何も起きていない」*の
両方をカバーします。ステータスだけでこれらを区別することはできません。
注文が AUTHORIZATION_REQUIRED で止まっています。ユーザーが WebView を閉じたのですか？
そうかもしれませんが、ステータスはそれを教えてくれませんし、それが唯一の説明でもありません。
AUTHORIZATION_REQUIRED は結果が返ってきていないことを意味し、次のすべてと矛盾しません。
- ユーザーが決済ページをまったく開かなかった。
- ユーザーが開いて放棄した — WebView を閉じた、アプリを終了した、離れた。
- ユーザーがまだそのページにいて、認証の途中である。
- 決済の試行がまだ行われていない。
どのステータスが最終で、自社の結果として保存できますか？
最終のステータスは 2 つです：PAY_SUCCESS と ORDER_CLOSE。それ以外はすべて遷移中であり、
遷移中のステータスの注文はまだ動きえます。
PAY_SUCCESS と ORDER_CLOSE が互いに入れ替わることはありません。注文が一度クローズされると、後から決済手段の
成功報告が届いても再オープンされず、PAY_SUCCESS に書き換えられることもありません。一度成功すれば、
成功のままです。したがって、最終ステータスを業務上の結果として永続化できます。
永続化して安全でない唯一のものは、最終ステータスが資金に関してそれ以上何も起こりえないことを意味するという
思い込みです。成功した注文でも後から返金や異議申し立てが起こりえますが、そのどちらも orderStatus を変更しません。
下記の返金の質問を参照してください。
各ステータスの注文に対して何ができますか？
2 つの境界は注意して読んでください。連携が誤りやすいのはここです。
- 返金は
PAY_SUCCESSからのみ可能です。「保留中の注文を返金する」ことはできません。資金が着金していないなら、 必要なアクションはキャンセルです。 - キャプチャしないオーソリを解放する方法はキャンセルです。 オーソリ、キャプチャ、その後の返金という流れよりも 実質的に優れています。
キャンセルを呼び出したら拒否されました。各エラーの意味は何ですか？
それぞれへの対処：
A0013はリトライすべきエラーではありません。 ユーザーは支払っています。履行したくない場合のアクションは キャンセルではなく返金です。A0015はリクエストではなく決済手段についての事実です。 キャンセル操作をまったく持たない決済手段もあります。 その場合、未払いの注文が終わる方法は期限切れです。「キャンセルは利用できないかもしれない」前提で設計し、 期限切れに任せてください。A0016は決済手段側から返ってきたものです。 1 回のリトライは試す価値がありますが、繰り返すようなら止めて、 注文を期限切れにさせてください。- すでにクローズされた注文のキャンセルは成功し、何もしません。そのため、ステータスを先に確認しなくても クリーンアップジョブから安全に呼び出せます。
paymentRequestId または acquiringOrderId のいずれかに加えて merchantId を送信できます。
どちらの ID も送らないとバリデーションエラーになります。
キャンセル後、ユーザーは決済手段のページでまだ支払えますか？
キャンセルは注文をORDER_CLOSE（最終ステータス）にし、決済手段側にもキャンセルを要求します。その時点から注文は
完了できません。後から届く成功報告は適用されないため、注文が知らないうちに支払済みに変わることはありません。
キャンセルが保証できないのは、ユーザーの目の前ですでに開いているサードパーティの決済ページが入力の受け付けを
止めることです。決済手段がキャンセルをまったくサポートしていない場合（A0015）、定義上、相手側では何もキャンセル
されていません。したがって「ユーザーはまだ支払えるか」への正直な答えは、資金を渡すことはできるかもしれないが、
それが完了した注文になることはない、です。その期間に動いた資金は履行のケースではなく回収のケースであり、
対処方法はタイムアウトと結果が確定するタイミングに記載されています。
実務上のルール：販売しないと決めたときにキャンセルしてください。ユーザーがまだ見ているチェックアウトを閉じる手段として
キャンセルを使わないでください。
「短い期限を設定し、過ぎたらキャンセルする」は良い設計ですか？
妥当な設計ですが、1 つの訂正と 1 つの注意点があります。- 訂正： キャンセルの呼び出しは不要です。支払われないまま期限に達した注文は自動的にクローズされ、貴社に通知されます。 その後に自前のキャンセルを追加しても無害ですが（クローズ済み注文では何もしません）、注文を終わらせているのは それではありません。
- 注意点： 短い期限は決済手段自身の期間を短くしませんし、相手側で遅れて支払いが行われるのを止めません。したがって 3 分の期限は 3 分のチェックアウトをもたらすものであり、その後に資金が動かないという 3 分の保証ではありません。
注文は設定した期限ちょうどにクローズされますか？
それに近いですが、秒単位ではありません。クローズは定期的なスイープで行われるため、注文は名目上の期限の後も 短い間は技術的に開いたままになることがあり、大量の場合は期限を迎えた注文のまとまりが次のパスに持ち越されることがあります。 クローズ前に決済手段が確認され、すでに決済が進行中の注文は、決済の下でクローズされるのではなくそのまま残されます。 これが意味すること：- 「注文がクローズされたこと」を時計として使わないでください。 履行ロジックに期限が必要なら、送信した期限に対して 自前のタイマーを使ってください。注文ステータスは時刻ではなく結果を知るために使ってください。
- わずかに遅れたクローズをインシデントとして扱わないでください。 それが設計です。
- 過去の期限は拒否されず、破棄されます。 注文作成時に
orderExpiredAtがすでに過去である場合、その値は破棄され、 注文には決済手段のデフォルト期限が適用されます。つまり、貴社側の時計のバグは大きな音を立てて失敗するのではなく、 意図より長く開いたままの注文を生みます。送信前にタイムスタンプを確認してください。
orderExpiredAt をまったく送信しない場合でも注文は最終的にクローズされますが、その時刻は貴社が設定した値ではなく、
依存すべき値でもありません。期間が業務上重要な場合は常に明示的な期限を送信してください。
タイムアウトで注文がクローズされたときに通知は届きますか？
はい。クローズされた注文は通常の決済通知PAYMENT_NOTIFICATION を生成します。Order Inquiry と同じ注文構造を持ち、
orderStatus は ORDER_CLOSE、理由は orderFailedReason に入ります。購読すべき別の「注文期限切れ」イベントタイプは
なく、追加で有効化するものもありません。
したがって、PAYMENT_NOTIFICATION を処理し orderStatus で分岐する連携は、すでにタイムアウトによるクローズを
処理できています。受信できていない場合は Webhook の配信の問題です。
Portal の Webhook ログと
Webhook リトライを参照してください。
orderFailedReason.orderFailedCode をエラーコード表で調べられますか？
いいえ。別のコード体系です。 Axxxx コードは、貴社のリクエストが誤っているか拒否されたときに API 呼び出しが
同期的に返すものです。orderFailedReason の中のコードは、注文がなぜそのように終わったかを説明するもので、
理由指向の別の名前空間です。一方を他方の表で調べることが、マーチャントがそのコードは「存在しない」と結論づける
原因になっています。
これを使って自動化できますか？ 部分的に、慎重に行えます。
- 頼りにできる大まかな区別で分岐してください — タイムアウトによるクローズは決済の拒否とは異なる業務イベントであり、 どちらもキャンセルとは異なります。
- コードの隣に
orderFailedDescriptionを必ず保存してください。見たことのないコードが届いたときに、読める形で 残るのはその部分です。 - 認識できない理由を自社コードの不具合として扱う網羅的な switch を作らないでください。この集合はテストで目にする 数個よりも大きく、決済手段の変化に伴って新しい理由が現れます。「クローズ、未払い、理由は記録済み」を既定とし、 推測するのではなく人に通知してください。
オーソリした金額より少ない金額をキャプチャできますか？
はい。キャプチャ金額はゼロより大きく、オーソリ金額以下であれば何でも構いません。オーソリの残りは保持されるのではなく 解放されます。オーソリ額を超えるキャプチャは拒否されます。
最後の行が人々を驚かせます。キャプチャは手動キャプチャモードで作成された注文にのみ存在します。注文作成時に
paymentInfo.captureMode でオプトインし、そこで受け付けられる値は manualCapture のみです。通常の注文は自動的に
キャプチャされ、貴社が呼び出すものはありません。
最も重要な点について、公開されているプロダクトの動作はコードと一致しています。キャプチャは実質的に1 回限りです。
一度キャプチャすると、たとえ一部でもオーソリの残りは解放されるため、オーソリを分割して引き出すことはできません。
従量課金には、繰り返しのキャプチャではなく、保存したトークンと定期的な請求のパターンを使用してください。
Auth-Captureとトークナイゼーションを参照してください。
キャプチャの期限はどのくらいですか？
期間は、オーソリに気付いた時点ではなく、注文が作成された時点から丸一日単位で数えます。これはプラットフォーム全体の 単一の設定であり、すべてのマーチャントに一律に適用されます。アカウントごとに交渉されるものではなく、拒否メッセージの 文言は現在の数値を知る信頼できる手がかりではありません。これを前提に履行プロセスを設計する前に、サポートに期間を 確認してください。 期間が経過すると 2 つのことが起こり、どちらにも備えるべきです。- キャプチャ呼び出しが失敗し始めます。 キューに入るのではなく、サポート対象外として拒否されます。
- オーソリは自動的に解放されます。 期限切れのオーソリは能動的にキャンセルされるため、貴社が忘れたために顧客の 資金が保持され続けることはありません。
一部の注文で refundExpiryAt が空なのはなぜですか？
refundExpiryAt は、それ以降その注文を返金できなくなる時点です。その決済手段に対する契約上の返金期間から導出され、
決済が成功した時点ではなく注文の作成日から起算し、その日の終わりに到達します。
2 つの結果：
- 日数で表される期間は暦日の期間です。その日の遅い時間に作成された注文は、早い時間に作成された注文より 実質的に使える期間がやや短くなります。境界はいずれにせよ 1 日の終わりだからです。
- 決済が成功しても時計は再スタートしません。作成からかなり後に支払われた注文は、すでに返金期間の一部を消費しています。
null）です。
したがって、
refundExpiryAt がないことを「永久に返金可能」と読まないでください。「この注文について期限が公開されていない」
と読み、適用されるものは
決済手段別の返金制限で確認し、まだ返金できる金額は返金 API の
remainingRefundAmount で判断してください。
返金は元の注文のステータスを変えますか？
いいえ。これはこのエンドポイントで最も多い誤報です。返金がorderStatus を書き換えることはありません。
全額返金された注文でも PAY_SUCCESS を報告し続けます。返金の進捗は返金記録と、注文の別の返金ステータスフィールドに
あり、決済ステータスにはありません。
貴社の帳簿が orderStatus をキーに返金状態を管理していると、永久に止まっているように見えます。代わりに返金記録を
キーにしてください。どの質問をどこで確認するかは
決済手段別の返金制限にまとめられています。
動かないステータスで行き詰まっていますか？
acquiringOrderId と表示されているステータスを添えて
サポートにお問い合わせください。