Integration Types
Two types of card payment experience
Hosted Type: TossPayments Payment Window
Direct Type: Card Company App
Compare Hosted Type and Direct Type
| Hosted | Direct | |
|---|---|---|
| Steps to complete payment (End User) | 5 steps | 3 steps |
| Payment conversion rate | Lower conversion rate due to longer payment process | Increased conversion rate due to fewer payment steps |
| Customization level | Low | High (payment method list, installment plan selection, promotion application, etc) |
| Implementation complexity | Easy | More elements to consider |
Recommendation: To implement Direct Type with less engineering effort, use our low-code Payment Widget SDK.
How to integrate Hosted Type
1. Using Create Payments API
Call the Create Payments API. The payment window URL is returned in the Payment.checkout.url field of the response.
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
}
2. Using TossPayments JavaScript SDK
Use the Payment Window SDK, a JavaScript library that provides a simple way to integrate TossPayments into your website.
Add SDK in your code and call tossPayments.requestPayment() method.
tossPayments.requestPayment('CARD', {
amount: 15000,
orderId: 'SrlYzXxfB0p6Mbb99cN6_',
orderName: '토스 티셔츠 외 2건',
customerName: '박토스',
successUrl: 'http://localhost:8080/success',
failUrl: 'http://localhost:8080/fail',
})
👉 See more details at Payment Window JavaScript SDK integration guide
👉 Check the Payment Window SDK parameters
👉 Watch the PC demo video
How to integrate Direct Type
1. Using Widget Javascript SDK
The Widget Javascript SDK is the easiest way to integrate Direct Type in Korea.
TossPayments provides a WYSIWYG editor where you can change the design, available payment methods, and more. Instead of making your own checkout page from scratch, use the Widget SDK to create a payment selector with little engineering effort and no-code
👉 See more details at Widget JavaScript SDK integration guide
paymentWidget.renderPaymentMethods('#payment-method', 15000); // Render payment methods
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'
})
👉 Widget JavaScript SDK integration guide
👉 Watch the Widget SDK demo video
2. Using TossPayments JavaScript SDK (with flowMode Parameter)
You can also implement Direct Type with the Payment Window SDK. However, while the Widget SDK provides all the UI and functions (installation, promotion, etc.) necessary for payment, the current method requires you to implement everything yourself.
We strongly recommend using the Widget SDK, but if you want to customize every detail of the payment experience, use this method.
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 more details at Payment Window JavaScript SDK integration guide
👉 Check the cardCompany and easyPay enum code list