決済の作成
お客様の決済情報を弊社に直接送信する方法を説明します
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を継承します。 |
作成されるセッションオブジェクトは非常に大きくなる可能性があります。セッションの使用方法によって使用するレスポンスの属性は異なります。この例では、単にセッションを決済の手段として使用しているだけなので、レスポンスの属性のうち気にする必要があるのは次の3つのみです。
| 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にリダイレクトします。または、「ご注文ありがとうございました」と表示することもできます。 その後、行われる決済でペイメント キャプチャを呼び出します。 |
| "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コールだけで決済を完了できます。貴社ユースケースでは、より簡潔な可能性があります。。 | クレジットカードの場合、デフォルトで3DSをスキップします。「セッションなしの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. その他すべての決済方法について、「承認された(authorized)」とは、2段階キャプチャをいいます。ここでは、資金は貴社の管理下にありますが、まだその資金はお客様のアカウントからは徴収されていません。これらの承認された決済は、業者の行動を待っています(例えば、商品が出荷されるときに業者が手動でキャプチャを行う)。この状態の時、ペイメント: キャプチャをコールして承認済資金をキャプチャするか、ペイメント: キャンセルをコールして承認を無効にできます。 |
| captured | 決済に成功しました。次回の決済時に貴社の銀行口座にお金が振り込まれます。 |
| refunded | 決済は完了したが、全額返金されました。一部返金された支払いはキャプチャされたままであることに留意してください。ペイメント: 作成の応答では、このステータスは表示されません。 |
| cancelled | お客様が決済のキャンセルを決定したか、ペイメント: キャンセルがコールされました。 |
| expired | 決済は保留されていたか、承認されていたが、あまりにも長い間何の行動も起きませんでした。 |
これをどのように処理するかは、貴社固有のユースケースと貴社が選択した決済方法によって異なります。特定の決済方法の取り扱いに関するアドバイスは、「決済の詳細」ページに記載されています。
コンビニの支払いの取り扱いに関する注意
コンビニ決済のレスポンスには、以下のフィールドが含まれる場合があります：
instructions_url（全てのコンビニ決済）：コンビニ店頭でのお支払いに必要な情報とそれに関する詳細な説明を提供するページへのURLが含まれます。お客様が正しく支払いを行うための情報となりますので通知が必要となります。receipt：コンビニ決済で使用できる決済コードです。- セブン-イレブンの場合は無効のため、お客様にこのコードは提供しないようお願いします。セブンイレブンでのお支払いの場合、instructions_url フィールドで提供されるURLにお客様がアクセスし支払いに必要な情報をご自身で確認いただく必要があります。
- レスポンスで利用可能であれば、confirmation_code とともにお客様に提供することができますが、instructions_url のURLだけをお客様に提供することをおすすめいたします。
confirmation_code：セブンイレブン以外のコンビニ決済で利用可能であり、receipt と組み合わせることでお客様がコンビニでお支払いができるようになります。ですが、receipt、instructions_url のURLのみをお客様に提供することをおすすめいたします。
ステップ3: Webhook
決済がいつキャプチャされたかを知るための最も確実な方法は、payment.capturedWebhookをリッスンすることです。payment.capturedまたはpayment.authorizedのwebhookハンドラに注文処理ロジックを組み込むことをお勧めします。
return_urlについて補足
ダイレクト決済の場合、顧客がreturn_urlにリダイレクトされると、KOMOJUはHMACを含むクエリパラメータをurlに追加します。
HMACはKOMOJUからのリダイレクトであることを確認するための値で、HMACはURLの最後の部分、つまりパスと、HMACを除くすべてのクエリパラメータを使って計算され、非公開鍵を使って署名されます。
例えば、設定されたリターンURLが
https://example.com/return
の場合、支払いが完了すると以下のURLにリダイレクトされます:
https://example.com/return?hmac=examplehmac¶m1=a¶m2=b
messageはHMACを取り除いたパス＋パラメータなので、この場合は
message = "/return?param1=a¶m2=b"
となります。
hmac-sha256を使用してHMACを計算することで、KOMOJUで生成されたHMACと一致することを確認できます。
以下はRubyコードの例です。
OpenSSL::HMAC.hexdigest('sha256', your_private_key, message) => "examplehmac"
Updated 8 months ago