開発者向け
3つの呼び出しとWebhook。
Gateway はホスト型チェックアウトのため、連携は意図的に最小限です。注文を作成し、顧客をそのページへ誘導し、署名付きの結果を検証するだけ。以下がすべてです。決済UI、決済手段のロジック、3Dセキュア、ウォレット、領収書は当社が構築し、常に最新の状態に保ちます。
概要
連携するAPIの全体像。
- HTTPS上のREST
- JSONで入出力
- Bearer APIキー
- 冪等性キー
- 署名付きWebhook
- リプレイ攻撃対策
- テストモードと本番モード
- iOS・Android SDK
- ストア向けプラグイン
- 埋め込みフィールド
クイックスタート
ゼロから支払い済み注文まで。
正常系の全工程です。金額は最小通貨単位、リファレンスは御社側で採番し、チェックアウトURLは顧客のリダイレクト先として使います。APIのベースURLはサンドボックスキーと一緒に発行されます。PROTOCORE_API_BASE として export すれば、以下の呼び出しはそのまま実行できます。
注文を作成する
金額、通貨、御社独自のリファレンスを指定して1回呼び出すだけです。冪等性キーは御社側で生成してください。リトライしたリクエストには、新しい注文ではなく元の注文が返ります。
curl -X POST "$PROTOCORE_API_BASE/v1/orders" \
-H "Authorization: Bearer $PROTOCORE_API_KEY" \
-H "Idempotency-Key: 9F21-0716" \
-H "Content-Type: application/json" \
-d '{
"amount": 4900,
"currency": "EUR",
"reference": "9F21-0716",
"line_items": [
{ "name": "Brand identity sprint", "amount": 3850 },
{ "name": "Typeface licensing", "amount": 600 },
{ "name": "Rush delivery", "amount": 400 }
],
"return_url": "https://arcstudio.ro/thanks"
}'顧客をチェックアウトへ誘導する
レスポンスには、御社専用のチェックアウトホスト上のチェックアウトURLが含まれます。サンドボックスで発行されたホスト、または当社に向けた御社自身のドメインです。そこへリダイレクトするか、SDKで開いてください。決済手段、ウォレット、3Dセキュアはすべてそのページ上にあり、御社側で実装するものはありません。
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}署名付きの結果を検証する
決済が完了すると、署名付きイベントが御社のエンドポイントに届きます。何かを信頼する前に、Webhookシークレットで署名を検証し、そのうえで既知のリファレンスに基づいて履行処理を行ってください。
{
"type": "order.paid",
"id": "evt_7Ka2Lm",
"created": "2026-07-23T09:41:02Z",
"data": {
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"method": "usdc",
"settlement": { "currency": "EUR", "amount": 4900, "rate": "0.9184" }
}
}リファレンス
実際に使うエンドポイント。
ドキュメントにはさらに多くの情報がありますが、ほとんどの連携はここにある範囲で完結します。
Webhook
バックエンドに届く通知。
すべてのイベントには、御社が作成した注文のリファレンスが含まれます。ハンドラーは、タイプによる分岐と自社側での検索だけで実装できます。
本文を信頼する前に、署名を確認する。
すべての通知には、タイムスタンプと、生のボディに対するHMAC署名が含まれます。比較は定数時間で行い、許容時間を超えて古いものは拒否し、イベントIDが重複している場合は処理済みとして扱ってください。2xx以外のレスポンスには再送するため、ハンドラー側も冪等にしておく必要があります。
import { createHmac, timingSafeEqual } from "node:crypto";
export function verify(rawBody, header, secret) {
const [ts, sig] = header.split(",").map((p) => p.split("=")[1]);
const expected = createHmac("sha256", secret)
.update(`${ts}.${rawBody}`)
.digest("hex");
const a = Buffer.from(sig, "hex");
const b = Buffer.from(expected, "hex");
if (a.length !== b.length || !timingSafeEqual(a, b)) return false;
// Reject replays outside a five-minute window.
return Math.abs(Date.now() / 1000 - Number(ts)) < 300;
}保証
前提にできる性質。
冪等な作成処理
注文の作成にはすべて冪等性キーを指定します。タイムアウト、デプロイ、キューの再配信の後にリトライしても、二重課金にはならず、元の注文が返ります。
署名付き・リプレイ対策済みのイベント
Webhookにはタイムスタンプ付きのHMAC署名と、固定のイベントIDが含まれます。エンドポイントが2xxを返すまでバックオフを挟んで再送するため、デプロイ中でも決済を取りこぼしません。
一貫した1つのリファレンス
作成時に指定したリファレンスは、チェックアウト、領収書、Webhook、精算、その後の返金まで一貫して使われます。システム間で対応付けが必要な別のIDはありません。
テストモードも同じコードパス
テストキーでは、テストセッションに対して同一のフローが実行されます。テストで通ったものがそのまま本番に出ます。違いは、呼び出すエンドポイントではなく、送信するキーだけです。
テストデータ
重要なパスを検証する方法。
各パスにはテストカードが用意されており、サンドボックスの発行時にキーと併せて一覧でお知らせします。カード番号はサンドボックスごとに異なり、ここでは公開しません。カードブランドのテストレンジが変わっても、常に正しい番号をご利用いただけます。どちらの場合も挙動は決定的で、テストでは承認と同じように辞退（ディクライン）も確実に検証できます。
キーを取得して、開発を始めましょう。
API キー、Webhook シークレットを備え、すべての決済手段を有効にしたサンドボックス加盟店を提供します。完全なリファレンスも付属し、契約前でもチームで連携開発を進められます。