Payment widgets
목차

The Toss Payments widget is a low code payment solution. Embed the payment UI to your checkout page and customize no-code via admin.

결제 UI 렌더링

SandboxSee integration demo with our sandbox.

About widgets

Widgets are the most convenient way to integrate payments and provide your customers with a seamless payment experience. Not only does it offer a fully customizable payment UI, it also includes an agreement UI. The agreement UI includes the Toss Payments terms of use, and you are free to add your own terms if necessary.

Supported payments

Available payment services on the widget include the following.

  • 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 for access.

Admin features

Access the widget admin by logging in to your store and navigating to the Payment UI settings (결제 UI 설정) menu. Through the admin, you can add payment services and customize your payment UI.

  1. Click Add+ on the payment UI.
    결제 UI에 서비스 추가하기 1
  2. Toggle on the payment service you'd like to add. Select an MID if necessary and click Save.
    결제 UI에 서비스 추가하기 2
  3. Now you'll see that a new payment service has been added. Hover over the payment service to see the associated MID.
    결제 UI에 서비스 추가하기 3
  4. Find your widget key in the Development Center's API key menu and start your integration.
    결제 UI에 서비스 추가하기 3
  1. In the payment UI menu, click Add UI
    새로운 결제 UI 추가하기 1
  2. Check all the payment services you'd like to use on the new UI and click Next.
    새로운 결제 UI 추가하기 2
  3. If you have multiple MIDs for a payment services, choose one to use and click Next.
    새로운 결제 UI 추가하기 3
  4. Enter a variantKey for the UI and click Save.
    새로운 결제 UI 추가하기 4
  5. Copy the UI's variantKey.
    새로운 결제 UI 추가하기 5
  6. Find your widget key in the API key menu and set the variantKey accordingly when rendering the widget.

In the agreement UI menu, click on the drop-down in the top right corner and click + Add new agreement terms. Set the language to English, and fill in the name, and variantKey. Click Next.

이용약관 추가

Render the new agreement by using the variantKey you set as below.


Integrate widgets

Use the below docs widget API keys for your initial integration. If you sign up and log into the Toss Payments developer center, you will be issued a set of your own keys and access to test logs and webhooks.

widget key

1. Render the widget to request payment

Copy the code below to render both the payment UI and the agreement UI. Choose a payment method and press the Pay Now button to bring up the payment window. Input your payment information to complete the request. If you are using a test client key that starts with test_, your payment method will not be charged.

Toss Payments currently supports both version 1 and 2 of the SDK. The main difference between the two is that the many payment products that were separate SDKs in version 1 have been merged into a single SDK in version 2. We recommend using version 2 but if you need native mobile SDK support, please use version 1.

2. Handle the redirect

Successful requests

If your payment request is successful, the client is redirected to the successUrl that you set with the requestPayment() method. The successUrl is followed by four query parameters.

The amount value of the query parameter should be the same as the amount you originally set during the payment request. If they are different, it may be due to a malicious attempt to change the amount on the client side. Stop the payment and ask the customer to re-attempt the purchase.

Save the paymentKey, amount, orderId values to your server. paymentKey is used for refunds, payment retrievals, and more.

There are three payment types. Verify that the payment type is the one you intended to use.

  • NORMAL: Regular one-time payments such as a card payment or transfer payment.
  • BRANDPAY: BrandPay payment.
  • KEYIN: Card key-in payment available to select merchants. Contact your sales associate for more information.

Failed requests

If your payment request fails, the client is redirected to the failUrl that you set with the requestPayment() method. The failUrl is followed by three query parameters.

Cause of error

When the customer terminate the payment process. Because the payment is terminated before authentication, the orderId is not added as a query parameter.

Cause of error

When an error arises during the payment request or payment method authentication.

Solution

  • See the error message for details. Contract related inquiries should be direct to the Toss Payments customer center(1544-7772, support@tosspayments.com).

  • For other technical issues visit our Discord channel for help.

Cause of error

When the card information the customer has entered is incorrect or invalid.

Solution

  • See the error message for details.

3. Authorize the payment

Finally, authorize the payment to charge your customer's payment method. Encode your widget secret key and colon in base64 to use as the API authorization header.

Use the below terminal command to get the encoded auth header.

Add the base64 encoded secret key as the Auth header. Optionally, add the Accept-Language header as below to get your responses in English. Fill in the request body with the paymentKey, amount, and orderId retrieved from the successUrl.

4. See the API response

When your authorization succeeds, you will get a 200 OK with the Payment object. Check the below Payment object fields.

  • method should have the payment method that your customer selected
  • card holds the card details for a card payment, transfer for a transfer payment and so on. Check the appropriate field for the customer's payment details. However if the customer has paid with a digital wallet, it may be necessary to check both card and easyPay fields.
  • virtualAccount payments can be simulated using the test payment logs menu if you are logged in.
  • If you can't find the field you're looking for, check the API version.

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