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

決済APIはビジネスプランでのみご利用いただけます。決済APIを利用する場合、1取引ごとに35円の手数料がかかります。この手数料は、あなたのBukzaアカウント残高から差し引かれます。

決済APIを利用して、任意の決済サービスをBukzaに接続できます。そのためには、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つのオプションのいずれかを実装できます:

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

この連携オプションでは、後から手動で資金をキャプチャできます。あなた自身で予約を確認し、資金をキャプチャするか、事前承認をキャンセルできます。
「簡易モード」 — このオプションでは事前承認を使用しません。この場合、注文完了時に即座に資金がキャプチャされます。注文の有効性や金額は引き続き確認され、問題があれば「新規注文」メッセージでマネージャーに警告が追加されます。

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

署名ハッシュはどのように生成しますか？

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

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/

重要な注意点:

amount値を文字列に変換する際、小数点以下がある場合はドット（.）を小数点区切りとして使用してください。
リクエスト受信時、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）で応答してください。