TypeScript SDK

@tradom/payment は、TRADOM Payment APIをNode.jsから利用するためのサーバ側SDKです。このドキュメントは 0.5.0 を対象にしています。

0.5.0 は checkoutStatus の入金レシート（underpaid / txHash / paidAmount など）と、Hosted Checkoutの補助endpoint（referenceQuote / verifyStatus / extendSession / resetVerification）を追加したreleaseです。GatewayのUSD注文・TRON / USDT・slippageCheck はproductionで利用できます。

インストール

npm install @tradom/payment

Clientを作成

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 is required");
}

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

SDKはサーバ専用です。API keyをbrowser bundle、mobile app、公開repositoryへ含めないでください。

認証情報

利用するAPIごとに、別のclientを作成します。

Key	Resource	用途
`gw_live_…`	`client.gateway`	Hosted Checkout
`sk_test_…` / `sk_live_…`	`client.paymentIntents`	Custom Payment Flow
`sk_test_…` / `sk_live_…`	`client.webhookEndpoints` / `client.events`	Webhook登録・event参照
`whsec_…`	`constructEvent`	Webhook署名検証

Gateway用とPaymentIntent用のkeyは別の認証情報です。1つの PaymentClient で使い回さないでください。

Resource

Resource	Method
`gateway`	`createOrder`、`checkoutStatus`、`selectAsset`、`refreshQuote`、`acceptTos`、`simulateDeposit`、`slippageCheck`、`referenceQuote`、`verifyStatus`、`extendSession`、`resetVerification`
`paymentIntents`	`create`、`createCheckoutSession`、`retrieve`、`cryptoQuote`、`confirm`、`cancel`、`refund`、`simulateDeposit`
`webhookEndpoints`	`create`、`list`
`events`	`list`、`retrieve`

Webhook署名検証は constructEvent または verifyWebhookSignature を直接importします。

Client options

const client = new PaymentClient({
  apiKey: TRADOM_PAYMENT_GATEWAY_KEY,
  baseUrl: "https://payment.tradom.jp",
  authScheme: "x-api-key",
  timeoutMs: 15_000,
});

Option	Default	説明
`apiKey`	なし	認証付き操作では必須。token／client-secret scoped操作だけなら省略可
`baseUrl`	`https://payment.tradom.jp`	APIの接続先
`authScheme`	`x-api-key`	Gatewayのkey送信方式。`bearer`も選択可
`timeoutMs`	`15000`	request timeout
`fetch`	`globalThis.fetch`	testやcustom agent用のfetch実装

PaymentIntentのマーチャント操作は、authScheme に関係なくBearer認証を使います。retrieve、cryptoQuote、confirm はoptionsへ clientSecret を渡すと、代わりに X-Client-Secret を送信します。

API keyなしのclient

公開checkout tokenまたはPaymentIntentのclient secretだけを使う場合は、API keyを省略できます。

const checkoutClient = new PaymentClient({});
const session = await checkoutClient.paymentIntents.createCheckoutSession({
  paymentLinkToken: "<share_token>",
});

const latest = await checkoutClient.paymentIntents.retrieve(session.id, {
  clientSecret: session.clientSecret!,
});

API keyを省略したclientで認証必須methodを呼ぶと、通信前に PaymentError("authentication_required") をthrowします。SDK自体はサーバ専用なので、この処理はbackend／BFFに置いてください。

Responseとerror

REST APIの snake_case はSDKで camelCase に変換されます。API errorと通信errorは PaymentError になります。

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

try {
  await tradomPayment.gateway.checkoutStatus(checkoutToken);
} catch (error) {
  if (error instanceof PaymentError) {
    console.error(error.code, error.httpStatus);
  }
}

詳しくは error handling を参照してください。

Versionと互換性

本番REST APIとSDKの既知差分は互換性・既知の制約にまとめています。

このページの内容