TossPayments Integration

Accept Korean payment methods including credit/debit cards, bank transfers, virtual accounts, and mobile payments using TossPayments.

Prerequisites

Before you begin, make sure you have:

A TossPayments account — sign up at tosspayments.com if you don’t have one
Your API keys from the TossPayments Developer Center
A working Headless Commerce store with at least one product

Use test mode keys during development. Test keys use the test_ck_ and test_sk_ prefixes. Switch to live keys only when you’re ready to accept real payments.

Environment Variables

Add the following environment variables to your API server:

# TossPayments secret key (server-side only — never expose this to the client)
TOSS_SECRET_KEY=test_sk_xxxxxxxxxxxxxxxxxxxxxxxx

# TossPayments webhook signing secret
TOSS_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxxxxx

For your frontend application, add the client key:

# TossPayments client key (safe for client-side usage)
NEXT_PUBLIC_TOSS_CLIENT_KEY=test_ck_xxxxxxxxxxxxxxxxxxxxxxxx

Never expose TOSS_SECRET_KEY or TOSS_WEBHOOK_SECRET to the client. These must only be used server-side.

Checkout Flow

The TossPayments checkout flow involves four steps: creating a cart, initiating checkout, completing payment with the TossPayments Widget SDK, and confirming the payment server-side.

Webhook Setup

Headless Commerce listens for TossPayments webhook events to handle asynchronous payment updates (e.g., virtual account deposits, cancellations). Configure webhooks in the TossPayments Developer Center:

Go to Developer Center → Webhook Settings
Enter your webhook URL: https://api.headlesscommerce.io/v1/webhooks/tosspayments
Select the events to receive
Save the Webhook secret and set it as TOSS_WEBHOOK_SECRET

Webhook Signature Verification

TossPayments signs webhook payloads using HMAC-SHA256. The signature is included in the x-tosspayments-signature header. Headless Commerce verifies this automatically, but if you need to implement custom verification:

import crypto from 'node:crypto';

function verifyTossWebhook(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('base64');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Usage in an Express/Hono handler
app.post('/webhooks/tosspayments', async (req, res) => {
  const signature = req.headers['x-tosspayments-signature'] as string;
  const rawBody = await getRawBody(req);

  if (!verifyTossWebhook(rawBody.toString(), signature, process.env.TOSS_WEBHOOK_SECRET!)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(rawBody.toString());
  console.log(event.eventType); // e.g., "PAYMENT_STATUS_CHANGED"
  res.status(200).json({ success: true });
});

import hmac
import hashlib
import base64
from flask import Flask, request, jsonify

app = Flask(__name__)

def verify_toss_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = base64.b64encode(
        hmac.new(secret.encode(), payload, hashlib.sha256).digest()
    ).decode()
    return hmac.compare_digest(signature, expected)

@app.post("/webhooks/tosspayments")
def handle_webhook():
    signature = request.headers.get("x-tosspayments-signature", "")
    raw_body = request.get_data()

    if not verify_toss_webhook(raw_body, signature, TOSS_WEBHOOK_SECRET):
        return jsonify({"error": "Invalid signature"}), 401

    event = request.get_json()
    print(event["eventType"])  # e.g., "PAYMENT_STATUS_CHANGED"
    return jsonify({"success": True})

Event Types

TossPayments Event	Headless Commerce Action
`PAYMENT_STATUS_CHANGED` (status: `DONE`)	Order status set to `confirmed`, payment marked `completed`
`PAYMENT_STATUS_CHANGED` (status: `CANCELED`)	Order cancelled, `payment.refunded` webhook sent
`PAYMENT_STATUS_CHANGED` (status: `PARTIAL_CANCELED`)	Partial refund recorded
`VIRTUAL_ACCOUNT_DEPOSIT`	Virtual account payment confirmed, order marked `confirmed`

Testing

Test mode keys

Use test mode API keys during development. Test transactions are simulated and do not process real payments.

Key type	Prefix	Example
Client key	`test_ck_`	`test_ck_D5GePWvyJ...`
Secret key	`test_sk_`	`test_sk_zXLkKEypN...`

Test payments

In test mode, the TossPayments widget displays simulated payment flows:

Credit card: Select any card brand and complete the simulated authentication
Bank transfer: The transfer is instantly simulated as successful
Virtual account: A test virtual account is created and you can simulate a deposit
Mobile payment: Simulated mobile payment flow

TossPayments test mode does not use specific test card numbers like Stripe. Instead, the entire payment widget operates in a sandbox environment where all payment methods are simulated.

Testing webhooks locally

Use a tunneling tool like ngrok to forward webhook events to your local server:

# Install ngrok
brew install ngrok

# Start a tunnel to your local server
ngrok http 3000

# Use the ngrok URL as your webhook endpoint in TossPayments Developer Center
# e.g., https://abc123.ngrok.io/v1/webhooks/tosspayments

Error Handling

Handle payment errors in both the checkout and confirmation steps: Checkout errors:

try {
  const order = await client.carts.checkout(cart.id, {
    email: 'customer@example.com',
    shipping_address: { /* ... */ },
    payment_method: 'tosspayments',
  });
} catch (error: unknown) {
  if (error instanceof Error && 'code' in error) {
    const apiError = error as { code: string; message: string };
    switch (apiError.code) {
      case 'cart_empty':
        // Cart has no items
        break;
      case 'insufficient_stock':
        // One or more items are out of stock
        break;
      case 'payment_provider_error':
        // TossPayments returned an error
        break;
      default:
        console.error(apiError.message);
    }
  }
}

try:
    order = requests.post(
        f"{base_url}/storefront/carts/{cart_id}/checkout",
        headers=headers,
        json={
            "email": "customer@example.com",
            "shipping_address": { ... },
            "payment_method": "tosspayments",
        },
    )
    order.raise_for_status()
except requests.exceptions.HTTPError as e:
    error = e.response.json()
    code = error.get("code")
    if code == "cart_empty":
        pass  # Cart has no items
    elif code == "insufficient_stock":
        pass  # One or more items are out of stock
    elif code == "payment_provider_error":
        pass  # TossPayments returned an error
    else:
        print(error.get("message"))

Payment confirmation errors:

try {
  const confirmation = await client.payments.confirm({
    payment_key: paymentKey,
    order_id: orderId,
    amount: amount,
  });
} catch (error: unknown) {
  if (error instanceof Error && 'code' in error) {
    const apiError = error as { code: string; message: string };
    switch (apiError.code) {
      case 'payment_amount_mismatch':
        // The amount does not match the original order
        break;
      case 'payment_already_confirmed':
        // This payment was already confirmed
        break;
      case 'payment_expired':
        // The payment session has expired
        break;
      case 'payment_confirm_failed':
        // TossPayments rejected the confirmation
        break;
      default:
        console.error(apiError.message);
    }
  }
}

try:
    confirmation = requests.post(
        f"{base_url}/storefront/payments/confirm",
        headers=headers,
        json={
            "payment_key": payment_key,
            "order_id": order_id,
            "amount": amount,
        },
    )
    confirmation.raise_for_status()
except requests.exceptions.HTTPError as e:
    error = e.response.json()
    code = error.get("code")
    if code == "payment_amount_mismatch":
        pass  # Amount does not match the original order
    elif code == "payment_already_confirmed":
        pass  # Payment was already confirmed
    elif code == "payment_expired":
        pass  # Payment session expired
    elif code == "payment_confirm_failed":
        pass  # TossPayments rejected the confirmation
    else:
        print(error.get("message"))

Handling the failure redirect

When a payment fails, TossPayments redirects to your failUrl with error details:

// In your failure page (e.g., /payment/fail)
const searchParams = new URLSearchParams(window.location.search);
const errorCode = searchParams.get('code');
const errorMessage = searchParams.get('message');
const orderId = searchParams.get('orderId');

// Display an appropriate message to the user
switch (errorCode) {
  case 'PAY_PROCESS_CANCELED':
    // User cancelled the payment
    console.log('Payment was cancelled by the user.');
    break;
  case 'PAY_PROCESS_ABORTED':
    // Payment was aborted
    console.log('Payment process was aborted.');
    break;
  case 'REJECT_CARD_COMPANY':
    // Card company rejected the payment
    console.log('The card company rejected this payment.');
    break;
  default:
    console.log(`Payment failed: ${errorMessage}`);
}

Common TossPayments error codes:

Error Code	Description	Suggested Action
`PAY_PROCESS_CANCELED`	User cancelled the payment	Allow the user to retry
`PAY_PROCESS_ABORTED`	Payment process was aborted	Allow the user to retry
`REJECT_CARD_COMPANY`	Card company rejected the payment	Ask to use a different card
`EXCEED_MAX_DAILY_PAYMENT_COUNT`	Daily payment limit exceeded	Try again the next day
`EXCEED_MAX_PAYMENT_AMOUNT`	Maximum payment amount exceeded	Reduce the order amount
`INVALID_CARD_EXPIRATION`	Invalid card expiration date	Ask to re-enter card details
`NOT_SUPPORTED_INSTALLMENT_PLAN`	Installment plan not supported	Choose a different installment option

Next Steps

Webhooks

Learn about all webhook events and payload formats.

Stripe

Set up Stripe for global payment methods.

API Reference

Explore all checkout and payment endpoints.

SDKs

Full SDK reference with every resource and method.

Getting Started

Build with AI

API Conventions

Security

Integration Guides

Recipes

TossPayments Integration

TossPayments Integration

Prerequisites

Environment Variables

Checkout Flow

Webhook Setup

Webhook Signature Verification

Event Types

Testing

Test mode keys

Test payments

Testing webhooks locally

Error Handling

Handling the failure redirect

Next Steps

Webhooks

Stripe

API Reference

SDKs

​TossPayments Integration

​Prerequisites

​Environment Variables

​Checkout Flow

​Webhook Setup

​Webhook Signature Verification

​Event Types

​Testing

​Test mode keys

​Test payments

​Testing webhooks locally

​Error Handling

​Handling the failure redirect

​Next Steps

Webhooks

Stripe

API Reference

SDKs

TossPayments Integration

Prerequisites

Environment Variables

Checkout Flow

Webhook Setup

Webhook Signature Verification

Event Types

Testing

Test mode keys

Test payments

Testing webhooks locally

Error Handling

Handling the failure redirect

Next Steps