Integration Types

Learn about the different ways to integrate Toss Payments and find the best option for your business.

There are two ways to integrate payment in Korea. The first is hosted, where the customer selects their preferred payment method on the Toss Payments Payment Window, as shown below. The hosted type is easier to integrate, but the payment process is longer and there is almost no room available for customization.

The second is direct, where the customer selects their payment method on your own website to directly open the chosen method's payment window as shown below. The direct type is more difficult to integrate because you must make your own payment UI. Because you are making your own UI, the payment process is more customizable and shorter as the customer skips the Toss Payments Payment Window.

If you want the benefits of the direct type but lack resources to make your own UI, try using the Toss Payments Widget. The Widget is a low-code solution that once integrated, can be customized in your store dashboard with no additional code.

A more detailed comparison of the hosted and direct types can be found in the table below.

Call the Create Payments API. The Payment object is given as a reponse. Check the checkout.url field for the payment window URL.

curl --request POST \
--url https://api.tosspayments.com/v1/payments \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '{"method":"CARD","amount":15000,"orderId":"a4CWyWY5m89PNh7xJwhk1","orderName":"토스 티셔츠 외 2건","successUrl":"http://localhost:8080/success","failUrl":"http://localhost:8080/fail"}'

{
  "mId": "tosspayments",
  "paymentKey": "0jPR7DvYpNk6bJXmgo28e1QkmPjlE8LAnGKWx4qMl91aEwB5",
  "orderId": "a4CWyWY5m89PNh7xJwhk1",
  // ...
  "checkout": {
    "url": "https://api.tosspayments.com/v1/payments/0jPR7DvYpNk6bJXmgo28e1QkmPjlE8LAnGKWx4qMl91aEwB5/checkout"
  },
  // ...
  "taxFreeAmount": 0,
  "taxExemptionAmount": 0,
  "method": null
}

Use the Payment Window SDK, a JavaScript library that provides a simple way to integrate Toss Payments into your website.

Add SDK in your code and call the requestPayment() method.

var tossPayments = TossPayments(clientKey)

tossPayments.requestPayment('CARD', {
  amount: 15000,
  orderId: 'SrlYzXxfB0p6Mbb99cN6_',
  orderName: '토스 티셔츠 외 2건',
  customerName: '박토스',
  successUrl: 'http://localhost:8080/success',
  failUrl: 'http://localhost:8080/fail',
})

👉 See our Payment Window integration guide

👉 Check the Payment Window SDK parameters

👉 Watch the Desktop demo video

The Widget Javascript SDK is the easiest way to integrate direct type.

After integration, you can change the design, payment methods, agreement terms and more on a dashboard with no additional code. Instead of making your own checkout page from scratch, use the Widget to integrate a payment UI in minutes.

👉 See our Widget integration guide

👉 Watch the Widget demo video

const paymentWidget = PaymentWidget(clientKey, customerKey)

paymentWidget.renderPaymentMethods('#payment-method', { value: 10000 });
paymentWidget.requestPayment({
  orderId: 'AD8aZDpbzXs4EQa-UkIX6',
  orderName: 'Toss T-Shirts',
  successUrl: 'http://localhost:8080/success',
  failUrl: 'http://localhost:8080/fail',
  customerEmail: 'customer123@gmail.com',
  customerName: 'Tom Kim'
})

You can also implement direct type with the Payment Window SDK. However, unlike the Widget, this method requires you to design and create a payment UI from scratch and integrate each payment method separately. We strongly recommend using the Widget, but this method is useful if you need to customize every detail of the payment experience.

To use direct type with the Payment Window SDK, set the flowMode parameter to DIRECT and designate the payment method with either the cardCompany or easyPay parameter.

var tossPayments = TossPayments(clientKey)

tossPayments.requestPayment('CARD', {
  amount: 15000,
  orderId: 'SrlYzXxfB0p6Mbb99cN6_',
  orderName: 'Toss T-Shirts',
  customerName: 'Tom Kim',
  flowMode : 'DIRECT', // Direct Type
  cardCompany : 'KOOKMIN' // Card Company
  // easyPay : 'TOSSPAY' // You can add digital wallet(e-wallet) company enum code here and remove cardCompany parameter.
  successUrl: 'http://localhost:8080/success',
  failUrl: 'http://localhost:8080/fail',
})

👉 See our Payment Window integration guide

👉 Check the cardCompany and easyPay enum code list