Quickstart: Hosted Checkout

公式SDKを使い、最初のcheckoutを作成して支払い状態を確認する

このQuickstartでは、マーチャントのbackendからcheckoutを作成し、買い手をTRADOM Paymentの決済画面へredirectします。

始める前に

次の情報を用意してください。

Gateway API key: gw_live_…
支払い完了後の returnUrl
キャンセル時の cancelUrl（任意）

1. SDKをインストール

npm install @tradom/payment

2. API keyを設定

Gateway API keyはサーバの環境変数に保存します。

TRADOM_PAYMENT_GATEWAY_KEY=gw_live_...

3. Checkoutを作成

次はNext.js Route Handlerの例です。orderId は自社の注文IDです。amount は currency の主単位で指定し、この例ではJPYを使用します。

app/api/checkout/route.ts

import { PaymentClient } from "@tradom/payment";

const TRADOM_PAYMENT_GATEWAY_KEY =
  process.env.TRADOM_PAYMENT_GATEWAY_KEY;

if (!TRADOM_PAYMENT_GATEWAY_KEY) {
  throw new Error(
    "環境変数 TRADOM_PAYMENT_GATEWAY_KEY が設定されていません",
  );
}

const tradomPayment = new PaymentClient({
  apiKey: TRADOM_PAYMENT_GATEWAY_KEY,
});

export async function POST() {
  const checkout = await tradomPayment.gateway.createOrder({
    orderId: "order_12345",
    amount: 50000,
    currency: "JPY", // 省略時もJPY。USD注文は "USD"
    buyerName: "Taro Yamada",
    buyerEmail: "taro@example.com",
    country: "JP",
    items: [{ name: "Coffee beans", category: "food" }],
    returnUrl: "https://shop.example/orders/order_12345/complete",
    cancelUrl: "https://shop.example/cart",
  });

  // ok / kyc_declined のどちらも、案内先のURLが返る
  return Response.redirect(checkout.checkoutUrl, 303);
}

同じ orderId で再送すると既存のcheckoutが返ります。通信error時も安全にretryできます。

USD注文では、たとえば amount: 178.25, currency: "USD" と指定します。ドルをセントへ変換せず、主単位のまま送信してください（USDは小数第2位まで、JPYは整数）。

4. 買い手をredirect

API routeを呼び出すと、ブラウザは checkoutUrl へredirectされます。以降のtoken・network選択、QR表示、入金確認はHosted Checkoutが担当します。

checkoutUrl と自社の orderId の対応は、redirect前にdatabaseへ保存してください。

5. 支払いを確認

買い手が returnUrl に戻ったことだけでは、支払い完了と判断しないでください。checkoutUrl の末尾にあるtokenを使い、backendから状態を確認します。

const status = await tradomPayment.gateway.checkoutStatus(checkoutToken);

if (status.confirmed) {
  await markOrderAsPaid(status.token);
} else if (status.underpaid) {
  await flagUnderpaid(status.token, status.sentAmount, status.expectedAmount);
}

confirmed: 全額の入金を確認済み（不足入金では false）
underpaid: 入金はあるが不足している
state.state === "completed": 後続の処理まで完了

業務上どちらを商品提供の基準にするかを決め、状態更新は冪等に実装してください。

次にすること

資金を動かさず試す: テスト方法
支払い完了を自動で受け取る: Webhook
注文状態の詳細を見る: Hosted Checkout