TypeScript SDK

@tradom/payment is the server-side Node.js SDK for the TRADOM Payment API. This documentation covers version 0.5.0.

0.5.0 adds the deposit receipt to checkoutStatus (underpaid / txHash / paidAmount …) and the Hosted Checkout helper endpoints (referenceQuote / verifyStatus / extendSession / resetVerification). USD Gateway orders, TRON / USDT, and slippageCheck are available in production.

Install

npm install @tradom/payment

Create a 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,
});

The SDK is server-only. Never include an API key in a browser bundle, mobile app, or public repository.

Credentials

Create a separate client for each API and credential type.

Key	Resource	Purpose
`gw_live_…`	`client.gateway`	Hosted Checkout
`sk_test_…` / `sk_live_…`	`client.paymentIntents`	Custom Payment Flow
`sk_test_…` / `sk_live_…`	`client.webhookEndpoints` / `client.events`	Webhook registration and event retrieval
`whsec_…`	`constructEvent`	Webhook signature verification

Gateway keys and PaymentIntent secret keys are separate credentials. Do not reuse one PaymentClient for both.

Resources

Resource	Methods
`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`

Import constructEvent or verifyWebhookSignature directly to verify webhook signatures.

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	Description
`apiKey`	None	Required for authenticated operations; optional for token/client-secret-scoped calls only
`baseUrl`	`https://payment.tradom.jp`	API origin
`authScheme`	`x-api-key`	Gateway credential scheme; `bearer` is also supported
`timeoutMs`	`15000`	Request timeout
`fetch`	`globalThis.fetch`	Custom fetch implementation for tests or custom agents

PaymentIntent merchant operations always use Bearer authentication, regardless of authScheme. Passing clientSecret to the options for retrieve, cryptoQuote, or confirm sends X-Client-Secret instead.

Create a client without an API key

You can omit the API key when you only use a public checkout token or a PaymentIntent client secret.

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

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

Calling an authenticated method on a keyless client throws PaymentError("authentication_required") before a network request is sent. The SDK remains server-only, so keep this logic in your backend or BFF.

Responses and errors

The SDK converts REST API snake_case fields to TypeScript-friendly camelCase. API and network failures become PaymentError instances.

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

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

See Handle errors for details.

Version compatibility

See Compatibility and known limitations for known differences between the production REST API and SDK.

On this page