決済の作成
お客様の決済情報を弊社に直接送信する方法を説明します
PCI-DSS 警告
このガイドを使用してクレジットカードを処理する場合は、PCI-DSSに準拠していることを証明する書類を提出するようお願いすることがあります。クライアント側でトークン情報を収集し、トークンを使用することで、この要件を軽減できる場合があります。詳細については、カスタマーサクセス担当者にお問い合わせください。
このガイドでは、KOMOJUを通じて直接決済を行う方法を説明します。直接とは、お客様のサーバが決済の詳細(クレジットカード番号など)をKOMOJUに送信し、KOMOJUがすぐに処理することを意味します。
このスタイルの統合には、次のようなユースケースが考えられます。
- 顧客の決済の詳細を収集するための完全にカスタマイズされたUIがあり、KOMOJUを裏で使いたいと思っている。
- KOMOJUを含む複数の決済サービスプロバイダと契約しており、それらの間で多重化したいと考えている。
弊社のAPIを使用して決済を作成する場合、2つのオプションがあります。最初にセッションを作成してから「決済」するか、または直接決済を作成することができます。通常は最初の方法が最も汎用性がありますが、完全性を確保するために両方の方法を順を追って説明します。
方法1: セッションに対する決済
この決済を作成する方法では、少なくとも2つのAPI呼び出しが必要です。1つはセッションオブジェクトを作成し、もう1つは決済を作成します。
 利点 |  短所 |
|---|---|
| 3DSですぐに使用できます。 | 少なくとも2つのAPI呼び出しが必要です。 |
| 1つの注文番号に対して複数の決済を試みることができます。 | |
| 品目をKOMOJUに送信して、不正の検出と記録を向上できます。 | |
| 配送先住所と請求先住所を提供して、不正検出を改善できます。 | |
| フロントエンドで「決済」を呼び出すことにより、PCI-DSSの負担を簡単に回避できます。 |
このレシピは完全な例ですここでは、各ステップについて詳しく説明します。
ステップ1:セッションを作成する
次の属性を使用してセッション: 作成APIを呼び出します。
| 認証 | 方法 | エンドポイント |
|---|---|---|
| Secret key | POST | https://komoju.com/api/v1/sessions |
| Request Attribute | タイプ | 説明 |
|---|---|---|
amount * | integer | 金額の整数値。これは常に、所定の通貨に対して可能な最低額面金額となります。たとえば、1というamountは1円または1 USセントを意味します。 |
currency * | string | 3文字の通貨識別子。たとえば、「USD」や「JPY」などです。 |
return_url | string | お客様を貴社サイトまたはアプリケーションにリダイレクトするためのURL。厳密には必須ではありませんが、強く推奨します。 |
payment_data[external_order_num] | string | 貴社システムの注文番号。セッションごとに一意である必要があります。 |
payment_data[capture] | enum | 「auto」（自動）または「manual」（手動）。デフォルトは「auto」です。「manual」に設定すると、2段階キャプチャが開始されます。 |
email | string | お客様のEメールアドレス。これがセッションに存在する場合、payment_details[email]は任意になります。 |
name | string | お客様の名前。 |
line_items | array of object | 品目のリスト。厳密な形式については、「セッション: 作成」を参照してください。 |
metadata | object | 貴社内部で使用するためのキーと値のペア。たとえば、注文番号の一意性検証が気に入らない場合は、ここに貴社の注文番号を入力できます。このセッションで作成された決済は、metadataを継承します。 |
作成されるセッションオブジェクトは非常に大きくなる可能性があります。考慮する属性は、セッションの使用方法によって異なります。この例では、単にセッションを決済のキャリアとして使用しているだけなので、対象の応答属性は次のとおりです。
| Response Attribute | タイプ | 説明 |
|---|---|---|
id | string | セッションの一意の識別子。これは、後続のAPI呼び出しで必要になります。 |
payment_methods | array of object | セッションでサポートされている決済方法のリスト。 |
payment_methods[i].type | string | 「決済の詳細」の決済タイプに対応するスラッグを入力します。 |
ステップ2:セッションに対する決済
次に、セッション: 決済エンドポイントを呼び出します。
| 認証 | 方法 | エンドポイント |
|---|---|---|
| Secret or publishable key | POST | https://komoju.com/api/v1/sessions/{id}/pay |
ステップ3:決済結果の処理
セッション: 決済からの応答は次のようになります。
statusが「error」でない場合は、お客様をredirect_urlにリダイレクトすることでいつでも対処できます。
ここでは、ここで遭遇する可能性のあるいくつかの異なるシナリオの詳細な内訳を示します。不明な場合は、redirect_urlにリダイレクトしてください。
status | capture | payment.status | 意味 | 対応 |
|---|---|---|---|---|
| "error" | * | N/A | 入力が無効である可能性。クレジットカード番号が間違っているなど。 | もう一度試してみるようお客様に指示します。 同じセッションでセッション: 決済を再度呼び出すこともできます。 |
| "completed" | "auto" | "captured" | 決済が成功しました。 | redirect_urlにリダイレクトします。または、単に「ご注文ありがとうございました」と表示しても構いません。 |
| "completed" | "auto" | "authorized" | 送信に成功して、お客様のアクションを待っています。 | redirect_urlにリダイレクトします。決済の手順が表示されます。または、手順を手動で表示します(「決済の詳細」を参照)。 |
| "completed" | "manual" | "authorized" | 決済が問題なく承認されました（2段階キャプチャ) | redirect_urlにリダイレクトします。または、「ご注文ありがとうございました」と表示することもできます。 \nその後、行われる決済でペイメント キャプチャを呼び出します。 |
| "pending" | * | "pending" | ユーザーは決済を行うには外部サービスにログインする必要があります。 | redirect_urlにリダイレクトします。決済アプリ(PayPayなど)か、クレジットカードの3Dセキュアログインページにつながります。クレジットカードの場合は、iframeでredirect_urlをレンダリングできます。 |
上記のいずれの場合もredirect_urlにリダイレクトしないことを選択した場合は、「決済の詳細」ドキュメントを参照して、貴社固有の決済方法がどのように機能するかを理解することをお勧めします。
ステップ4:リターンURLとwebhookを処理する
セッションを作成したときに指定したreturn_urlは、お客様が決済情報の送信を完了したとき、またはお客様が決済アプリでキャンセルを決定したときにお客様がリダイレクトされる場所です。
お客様がreturn_urlにリダイレクトされると、session_idというクエリパラメータが追加されます。バックエンドはこのsession_idを使用してセッション: 表示を呼び出し、セッションのstatusをチェックします。
次に例を示します。
オリジナル return_url | お客様がリダイレクトされるURL |
|---|---|
| https://example.com/order/abc | https://example.com/order/abc?session_id=63r9bjkqklasnofxttq7z9abc |
このreturn_urlのチェックに加えて、Webhookをセットアップすることをお勧めします(特にpayment.capturedとpayment.authorized用)。ペイメントのexternal_order_num、metadata、またはsession属性を使用して、注文に関連付けることができます。
方法2: 決済の直接作成
以下は、関連するセッションなしで決済を作成する方法です。
| 利点 | 短所 |
|---|---|
| 場合によっては、1回のAPIコールだけで決済を完了できます。貴社ユースケースでは、もっと簡単かもしれません。 | クレジットカードの場合、デフォルトで3 DSをスキップします。「セッションなしの3Dセキュア」を参照してください。 |
| 注文番号は決済ごとに一意である必要があります。1つの注文に対して複数の試行を表すのは不自然です。 | |
| 決済タイプごとに特別なケースコードが必要です。多くの決済方法で機能する汎用的な統合を構築するのは難しいです。 |
ステップ1:決済の作成
| 認証 | 方法 | エンドポイント |
|---|---|---|
| Secret key | POST | https://komoju.com/api/v1/payments |
| Request Attribute | タイプ | 説明 |
|---|---|---|
amount * | integer | 金額の整数値。これは常に、所定の通貨に対して可能な最低額面金額となります。たとえば、1というamountは1円または1 USセントを意味します。 |
currency * | string | 3文字の通貨識別子。たとえば、「USD」や「JPY」などです。 |
return_url | string | お客様が決済を完了した後に戻るURL。クレジットカード決済の場合は任意です。 |
capture | boolean | 2段階キャプチャを実行する場合は、falseに設定します。 |
tax | integer | 0に設定します。デフォルトは「auto」（自動）で、常にamountの10%です。 |
external_order_num | string | 貴社システムの注文番号。これを使用して、KOMOJUの決済を貴社社内の発注に関連付けることができます。これは一意でなければなりません。 |
metadata | object | 貴社内部で使用する任意のキーと値のペア。例えば、external_order_numに対する弊社の一意性検証が問題を引き起こした場合、貴社の注文番号をここに入れることができます。 |
payment_details | object | 決済方法固有の属性を含むオブジェクト(「決済の詳細」を参照)。 |
すべての一覧については、「ペイメント: 作成」のリファレンスを参照してください。ほとんどの場合、必要な属性はここに表示される属性だけです。
ステップ2:応答の処理
ペイメント: 作成エンドポイントは、次の属性を持つペイメントオブジェクトを返します(完全ではありません)。
| Response Attribute | タイプ | 説明 |
|---|---|---|
id | string | 一意の決済ID。ペイメント: キャプチャなどの追加アクションの実行に使用されます。 |
status | string | 決済が行われたかどうかを示します。この件については近く詳しく説明します。 |
以下に、発生する可能性のあるさまざまなペイメントstatus値の内訳を示します。
| 決済のステータス | 意味 |
|---|---|
| pending | 決済は開始されたが、確定されていません。応答にはpayment_details.redirect_urlが必要です。そのURLにお客様をリダイレクトし、payment.capturedWebhookをリッスンします。 |
| authorized | 決済の種類に応じて2つの意味が考えられます。 1. 長い形式の非同期決済方法(konbini、bank_transfer、payeasy)では、承認された決済は予約されますが、顧客のアクション(例えば、顧客が店に行って現金で決済するのを待つ)を待っています。これには数日かかることがあります。 payment.capturedWebhookは、お客様が決済を行ったときに取得します。それ以外の場合は、payment.expiredwebhookを取得します。2. その他すべての決済方法について、「承認された」とは、2段階キャプチャをいいます。ここでは、資金は貴社の管理下にありますが、まだお客様のアカウントから離れていません。これらの承認された決済は、業者の行動を待っています(例えば、商品が出荷されるときに業者が手動でキャプチャを行う)。ペイメント: キャプチャをコールして承認済資金をキャプチャするか、ペイメント: キャンセルをコールして承認を無効にできます。 |
| captured | 決済に成功しました。次回の決済時に貴社の銀行口座にお金が振り込まれます。 |
| refunded | 決済は完了したが、全額返金されました。一部返金された支払いはキャプチャされたままであることに留意してください。ペイメント: 作成の応答では、このステータスは表示されません。 |
| cancelled | お客様が決済のキャンセルを決定したか、ペイメント: キャンセルがコールされました。 |
| expired | 決済は保留されていたか、承認されていたが、あまりにも長い間何の行動も起きませんでした。 |
これをどのように処理するかは、貴社固有のユースケースと貴社が選択した決済方法によって異なります。特定の決済方法の取り扱いに関するアドバイスは、「決済の詳細」ページに記載されています。
ステップ3: Webhook
決済がいつキャプチャされたかを知るための最も確実な方法は、payment.capturedWebhookをリッスンすることです。payment.capturedまたはpayment.authorizedのwebhookハンドラに注文処理ロジックを組み込むことをお勧めします。
Updated 5 months ago