Quickstart: Hosted Checkout

In this quickstart, your backend creates a checkout and redirects the customer to a payment page hosted by TRADOM Payment.

Before you begin

Have the following ready:

• A Gateway API key beginning with gw_live_…
• A returnUrl for successful payments
• An optional cancelUrl

1. Install the SDK

npm install @tradom/payment

2. Set your API key

Store the Gateway API key in a server-side environment variable.

TRADOM_PAYMENT_GATEWAY_KEY=gw_live_...

3. Create a checkout

This example uses a Next.js Route Handler. orderId is your internal order ID. amount uses the major unit of currency; this example uses JPY.

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

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 is also the default; use "USD" for USD orders
    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",
  });

  // Both ok and kyc_declined responses include a destination URL.
  return Response.redirect(checkout.checkoutUrl, 303);
}

Requests with the same orderId return the existing checkout, so you can retry safely after a network error.

For a USD order, send values such as amount: 178.25, currency: "USD". Keep the amount in dollars; do not convert it to cents (USD up to two decimals, JPY whole yen).

4. Redirect the customer

When the route is called, the browser redirects to checkoutUrl. Hosted Checkout then handles asset and network selection, the QR code, and payment confirmation.

Before redirecting, save the relationship between checkoutUrl and your orderId in your database.

5. Confirm the payment

Do not treat a return to returnUrl as proof of payment. Extract the token from the end of checkoutUrl and check its status from your 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: the full amount has been received (false for an underpaid deposit)
• underpaid: a deposit arrived but is short
• state.state === "completed": all downstream processing is complete

Choose which state triggers fulfilment for your business, and make order updates idempotent.

Next steps

• Test without moving funds: Test your integration
• Receive payment updates automatically: Webhooks
• Understand every checkout state: Hosted Checkout