Payment Widget
목차

The Toss Payments Widget is a low code solution that only needs to be integrated once for all payment services and customization features.

결제 UI 렌더링

Sample projectsExplore sample code in various languages.

About Widgets

The Widget is a collection of prebuilt payment and terms of agreement UI components. Integrate once and enjoy no-code customization with the widget admin.

Available payment services include:

  • Regular payment: Credit and debit card, bank transfers, virtual accounts, digital wallets, mobile payment
  • Brandpay*: Build a digital wallet for your business.
  • Key-in*: Key in card information and pay without authentication.
  • PayPal*: Accept payments from customers all over the world.

* Contact your sales representative to ensure you have access to these additional payment methods.

Admin Features

To access the widget admin, log in to your store and select the 'Payment UI settings (결제 UI 설정)' menu.

Add Payment Services

Add a new payment service to your current payment UI.

Payment services

Use Multi UI

Add a new payment UI. You can make multiple payment UI versions for varying business scenarios.

Multi UI

If you are using Multi UI, pass the variantKey as a parameter when rendering the widget.

Add Agreement Terms

Add multiple versions or English versions of the agreement terms.

Agreement UI

When rendering the agreement terms UI, pass the variantKey as a parameter. The code below renders the default English agreement terms UI.

API Keys

Before you get started, get your Widget API keys. If you haven't signed up for Toss Payments, use the keys below. If you have, log in and find your API Keys in the Developer Center. With your own keys, you can access test payment logs and integrate webhooks to get payment status updates.


1. Render the Widget and request payment

Copy the code below to render the Widget, which includes the payment UI and the agreement terms UI. Press the "Pay Now" button to bring up the payment window.

Input your payment information to complete the payment request. If you are using the test API keys, your payment method will not be charged.

Update the amount

If you want to update the amount on the widget after rendering, use the updateAmount() method. Input the updated amount as the parameter.

2. Get the request results

When your payment request succeeds, the client is redirected to the successUrl that was a parameter to the requestPayment() method. The successUrl is followed by four parameters.

  • paymentKey: Issued by Toss Payments and used to identify a unique payment.
  • orderId: Issued by you and passed as a parameter to requestPayment(). The orderId should be a unique value and saved to the database before the payment request.
  • amount: Amount charged.
  • paymentType: Type of payment method. Either NORMAL, BRANDPAY, or KEYIN.
    • NORMAL: Regular payment method.
    • BRANDPAY: Brandpay payment.
    • KEYIN: Key-in payment.

Make sure the orderId and amount are identical to the parameters passed in requestPayment(). If they are different, the payment may have been compromised. Abort the current payment and ask the customer to restart the payment process.

3. Authorize the payment

As the last step, make a payment authorization API request.

First, encode your secret key and colon in base64 to use as the API authentication header.

You can use the below terminal command to get the encoded auth header.

Now add the encoded auth header to the API request. Fill in the body with data retrieved from the query parameters of successUrl. If you'd like to recieve the API response in English, add the 'Accept-Language: en-US' as below.

4. Check the final response

If the authorization succeeds, the request returns 200 OK and a Payment object.

✔️ Make sure the method field has the correct payment method.

✔️ Check the details of your payment method. In the example above, card details are in the card field.

✔️ If the customer used a digital wallet, the response can vary.

✔️ To simulate payment with a virtual account, use the test payment logs menu in the Developer Center.

✔️ Response fields vary depending on the API version. If you can’t find a specific field in the response, check your API version through the Toss Payments Developer Center and update the version accordingly.

  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    실시간 문의|이메일 보내기