自分の決済サービスをAPI経由で接続する方法は？

決済APIはビジネスプランでのみご利用いただけます。また、決済APIを通じた取引ごとに$0.25の手数料が発生します。この手数料は、Bukzaアカウントの残高から差し引かれます。

Bukzaには決済APIを通じて、任意の決済サービスを接続できます。接続するには、ご自身のサーバー（Bukzaと決済サービスの仲介役）が必要です。プログラミングのスキルも必要となります。

このAPIは今後変更される可能性があります。

APIを有効にするには？

決済APIの有効化をご希望の場合は、support@bukza.com までご連絡ください。メッセージ内に、Bukzaがリクエストを送信するサーバーのURLをご記載ください。こちらからユーザーIDと署名ハッシュ生成用のキーをお送りします。

連携済みのサンプル例

オンラインコードエディターサービスのこちらで、JavaScriptのソースコード例をご覧いただけます。

このサンプルを自身のアカウントでテストするには、以下の手順に従ってください:

Glitchでアカウント作成を行います。
こちらの「Remix」ボタンをクリックして、連携サンプルのリミックスを作成します。これにより、同じソースコードのご自身のアプリケーションが作成されます。
その後、GlitchでTERMINALを開き、コマンド npm ci を実行することを推奨します。必要な依存関係がインストールされます。
作成したアプリケーションのアドレスをsupport@bukza.comまでメールでお知らせください。その後、サーバーのURLアドレスとして設定し、bukza_user_idとbukza_keyをお送りします。
アプリケーションの.envファイルを開き、bukza_user_idとbukza_keyの値を挿入してください。このファイルは他のGlitchユーザーからは見えません。
Bukzaアカウントにログインし、決済処理フォームで「自動決済処理付き注文」を有効にし、必要な前払金額を設定してください。
ウィジェットを使って注文を完了し、ご自身のアカウントのメールアドレスを使用してください。注文時にアカウントのメールアドレスを使用すると、決済API利用料は発生しません。
テスト中はGlitchの「Logs」タブを確認してください。受信・送信リクエストのログが表示されます。
server.jsおよびindex.hbsファイルで、決済フォームの表示や決済システムからのレスポンス処理を実装してください。 .envファイル以外のファイルにキーやパスワードを記載しないでください。プロジェクトファイルおよびその変更履歴は他のGlitchユーザーにも公開されています。

連携オプション

以下の2つのオプションのいずれかを実装できます:

「事前承認あり」 — オーバーブックを防ぐオプションです。注文完了時に、まずカードで金額が事前承認され、その後、注文がまだ有効で価格が変わっていないか追加で確認します。注文がすでに無効な場合、事前承認は即座にキャンセルされます。

この連携オプションでは、後から手動で資金をキャプチャできます。ご自身で予約内容を確認し、資金をキャプチャまたは事前承認をキャンセルできます。ただし、3日以内に資金がキャプチャされない場合、Bukzaは事前承認のキャンセルリクエストを送信します。
「簡易モード」 — 事前承認なしのオプションです。つまり、注文完了時点で資金がすでにキャプチャされています。ただし、注文の有効性や金額は引き続き確認され、問題があれば「新規注文」メッセージでマネージャーに警告が追加されます。

決済サービスが事前承認に対応していない場合は、このオプションをご利用ください。

署名ハッシュの生成方法

リクエストには常に以下のパラメータが含まれます:

userId — BukzaシステムでのあなたのID。例: 11223。
orderNumber — Bukzaでの注文番号。例: "574285869"。
command — 実行するコマンド名。値の例: "GetPaymentData", "CaptureCallback", "AuthorizeCallback", "Cancel", "Capture", "Refund"。
data — 追加コマンドデータ（例: 決済システムでの取引番号: "18493853499"）。
amount — 支払い金額。例: 99.75。
timestamp — Unixタイムの秒数。例: 1596706182。各言語での取得例: https://www.epochconverter.com。

リクエスト署名の作成・検証には、これらすべてのパラメータを1つの文字列に連結（スペースやプラス記号なし）し、キーを使ってhmac sha256を計算し、結果をbase64文字列に変換します:

hash = base64(hmacSha256(userId + orderNumber + command + data + amount + timestamp), key);

各プログラミング言語での実装例: https://www.jokecamp.com/blog/examples-of-creating-base64-hashes-using-hmac-sha256-in-different-languages/

計算の確認はこちら: http://jsfiddle.net/dwyrk513/1/

重要なポイント:

金額を文字列に変換する際、小数点がある場合は区切りにドットを使用してください。
リクエスト受信時、Bukzaはtimestampがサーバーの現在時刻と5分以上ずれていないか確認します。
Bukzaからのリクエスト受信時も、同様にハッシュとtimestampを確認することを推奨します。

オプション1「事前承認あり」

1.1. 注文完了時、Bukzaは以下の内容でサーバーURLにPOSTリクエストを送信します:

{
    userId:11223,
    orderNumber:"574285869",
    command: "GetPaymentData",
    data: "",
    amount: 99.75,
    timestamp: 1596706182,
    hash: "p2t1xcpBiXLPPDdB129vUctRAgGbzQgRcnX4IiZ0bNE="
    email: "john@example.com",
    phone: "+11111111111",
    culture = "en",
    checkStateToken = "eyJVc2VySWQiOjIsIk9yZGVyS...Ws9In0%3D"
}

このリクエストへのレスポンスは以下のように返してください:

{
url: "https://yoursite.ru/amount=99.75&orderNumber=574285869&bukzaCulture=ru&bukzaUser=11223&bukzaCheckStateToken=eyJVc2VySWQiOjIsIk9yZ",
redirect: false
}

url — 決済ページの生成アドレスです。このページはご自身のサーバーまたは決済ゲートウェイのサーバー上に設置できます。
redirect — ユーザーを指定URLに完全リダイレクトするかどうかを決めるパラメータです。 falseの場合、決済フォームはウィジェット内のiframeで表示されます。 iframeのサイズはウィジェット設定のcssで変更できます。
checkStateTokenは、urlのパラメータ名bukzaCheckStateTokenとして追加されています。このパラメータは、決済ページで注文状態を確認するのに役立ちます。詳細はこちらをご覧ください。

1.2 お客様は決済フォームを確認し、支払いを行います。その後、決済ゲートウェイからサーバーに通知が届くはずです。この通知を受け取ったら、直ちに https://public.bukza.com/api/pay にPOSTリクエストを送信してください。リクエスト本文:

{
    userId:11223,
    orderNumber:"574285869",
    command: "AuthorizeCallback",
    data: "18493853499",
    amount: 99.75,
    timestamp: 1596706182,
    hash: "2kkjjx/grcar6B9yknqUMP6eOdMw4yJwa60Uc8fisNA=",
    comment: "支払いに関する任意のコメント。マネージャー画面で表示されます。リクエスト署名計算には使用されません。"
}

1.3 その後、注文の有効性や注文処理パラメータに応じて、Bukzaは事前承認のキャンセル、即時キャプチャ、または事前承認のまま注文を確定するいずれかを行います。後者の場合、マネージャー画面でご自身で支払いのキャンセルやキャプチャが可能です。いずれの場合も、Bukzaは決済ゲートウェイに転送すべきリクエストをサーバーに送信します。

事前承認をキャンセルする場合、Bukzaは以下の内容でリクエストを送信します:

{
    userId:11223,
    orderNumber:"574285869",
    command: "Cancel",
    data: "18493853499",
    amount: 99.75,
    timestamp: 1596706182,
    hash: "ejIS+AiPRSH9qXV/bBcAf7OSViCVUtj/hYPsL4aYpNM="
    email: "john@example.com",
    phone: "+11111111111",
}

事前承認済み資金をキャプチャする場合、Bukzaは以下の内容でリクエストを送信します:

{
    userId:11223,
    orderNumber:"574285869",
    command: "Capture",
    data: "18493853499",
    amount: 99.75,
    timestamp: 1596706182,
    hash: "JE4fRRLObEzCYk7aRFaW81DZw3sTXTOXsEcq3r8zm+Y="
    email: "john@example.com",
    phone: "+11111111111",
}

レスポンスはHTTPステータス200（SUCCESS）で返してください。

オプション2「簡易モード」

2.1 注文完了時、Bukzaは1.1と同様にサーバーURLにPOSTリクエストを送信します。

2.2 お客様は決済フォームを確認し、支払いを行います。その後、決済ゲートウェイからサーバーに通知が届くはずです。この通知を受け取ったら、直ちに https://public.bukza.com/api/pay にPOSTリクエストを送信してください。リクエスト本文:

{
    userId:11223,
    orderNumber:"574285869",
    command: "CaptureCallback",
    data: "18493853499",
    amount: 99.75,
    timestamp: 1596706182,
    hash: "eUKOwld1sEK3axhF9ZAy0WugXMJW+9nrs4BRlvnCeb0=",
    comment: "支払いに関する任意のコメント。マネージャー画面で表示されます。リクエスト署名計算には使用されません。"
}

返金

マネージャー画面から特定の支払いに対して返金処理が可能です。返金は全額または一部でも行えます。返金時、Bukzaはサーバーにリクエストを送信します。決済ゲートウェイにも対応するリクエストを送信してください。 Bukzaからのリクエスト本文:

{
    userId:11223,
    orderNumber:"574285869",
    command: "Refund",
    data: "18493853499",
    amount: 50.75,
    timestamp: 1596706182,
    hash: "E62WH04cKUjAvQ0dmirYMc16mCGN96YyQfrft8vLj0A="
    email: "john@example.com",
    phone: "+11111111111",
}

レスポンスはHTTPステータス200（SUCCESS）で返してください。