Integrate Payment Widgets

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

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.

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

Add a new payment service to your current payment UI.

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

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

Add multiple versions or English versions of the agreement terms.

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

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.

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.

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

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.

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.

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.