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.

JavaScript
paymentWidget.renderPaymentMethods('#payment-method', { value: 10000 }, { variantKey: 'widgetA' })

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.

JavaScript
const paymentAgreement = paymentWidget.renderAgreement('#agreement', { variantKey: 'AGREEMENT-EN' })

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.

JavaScript
const clientKey = 'test_gck_docs_Ovk5rk1EwkEbP0W43n07xlzm'
const secretKey = 'test_gsk_docs_OaPz8L5KdmQXkzRz3y47BMw6'

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.

<head>
<meta charset="utf-8" />
<!-- Add the Widget SDK -->
<script src="https://js.tosspayments.com/v1/payment-widget"></script>
</head>
<body>
<!-- Areas to render the widgets -->
<div id="payment-method"></div>
<div id="agreement"></div>
<!-- Payment button -->
<button id="payment-button">Pay now</button>
<script> const clientKey = "test_gck_docs_Ovk5rk1EwkEbP0W43n07xlzm" const customerKey = "" // Unique customer key used at your store const button = document.getElementById("payment-button") // ------ Initiate the SDK ------ // For customers who are not signed in, use PaymentWidget.ANONYMOUS instead of a customerKey const paymentWidget = PaymentWidget(clientKey, customerKey) // Customer signed in // const paymentWidget = PaymentWidget(clientKey, PaymentWidget.ANONYMOUS) // Customer not signed in // ------ Render the payment UI ------ // Designate a place to render the payment UI with a CSS selector such as `#payment-method`. // Call the method after the DOM has been created. // https://docs.tosspayments.com/reference/widget-sdk#renderpaymentmethods선택자-결제-금액-옵션 paymentWidget.renderPaymentMethods( "#payment-method", { value: 15000 } { variantKey: "DEFAULT" } // Multi UI parameter ) // ------ Render the agreement terms UI ------ // Designate a place to render the agreement terms UI. Pass a CSS selector such as `#agreement` as a parameter. // https://docs.tosspayments.com/reference/widget-sdk#renderagreement선택자 paymentWidget.renderAgreement( '#agreement', { variantKey: 'AGREEMENT-EN' } ) // ------ Open the payment window on click ------ // For more parameters, check the docs below. // https://docs.tosspayments.com/reference/widget-sdk#requestpayment결제-정보 button.addEventListener("click", function () { paymentWidget.requestPayment({ orderId: "", // Make a unique order ID orderName: "Toss T-shirts and 2 other items", successUrl: window.location.origin + "/success", // Client redirection to this url upon payment request success failUrl: window.location.origin + "/fail", // Client redirection to this url upon payment request failure customerEmail: "customer123@gmail.com", customerName: "Toss Kim", customerMobilePhone: "01012341234" }) }) </script>
</body>

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.

JavaScript
const paymentMethodsWidget = paymentWidget.renderPaymentMethods()
paymentMethodsWidget.updateAmount(50000)

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.

https://my-store.com/success?paymentKey={PAYMENT_KEY}&orderId={ORDER_ID}&amount={AMOUNT}&paymentType={PAYMENT_TYPE}
  • 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.

base64('test_gsk_docs_OaPz8L5KdmQXkzRz3y47BMw6:')
─────────────────┬───────────────── ┬
secretKey :

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

echo -n 'test_gsk_docs_OaPz8L5KdmQXkzRz3y47BMw6:' | base64

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.

요청
curl --request POST \
--url https://api.tosspayments.com/v1/payments/confirm \
--header 'Accept-Language: en-US' \
--header 'Authorization: dGVzdF9nc2tfZG9jc19PYVB6OEw1S2RtUVhrelJ6M3k0N0JNdzY6' \
--header 'Content-Type: application/json' \
--data '{"paymentKey":"{PAYMENT_KEY}","amount":15000,"orderId":"okOP2BswgCxbFWJmOqDQ8"}'

4. Check the final response

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

Response
JSON
{
"mId": "tosspayments",
"version": "2022-11-16",
"paymentKey": "",
"status": "DONE",
"lastTransactionKey": "",
"orderId": "",
"orderName": "Toss T-shirts and 2 other items",
"requestedAt": "2022-06-08T15:40:09+09:00",
"approvedAt": "2022-06-08T15:40:49+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": {
"issuerCode": "61",
"acquirerCode": "31",
"number": "12345678****789*",
"installmentPlanMonths": 0,
"isInterestFree": false,
"interestPayer": null,
"approveNo": "00000000",
"useCardPoint": false,
"cardType": "CREDIT",
"ownerType": "PERSONAL",
"acquireStatus": "READY",
"amount": 15000
},
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"cashReceipt": null,
"cashReceipts": null,
"discount": null,
"cancels": null,
"secret": null,
"type": "NORMAL",
"easyPay": null,
"country": "KR",
"failure": null,
"isPartialCancelable": true,
"receipt": {
"url": "https://dashboard.tosspayments.com/sales-slip?transactionId=KAgfjGxIqVVXDxOiSW1wUnRWBS1dszn3DKcuhpm7mQlKP0iOdgPCKmwEdYglIHX&ref=PX"
},
"checkout": {
"url": "https://api.tosspayments.com/v1/payments//checkout"
},
"currency": "KRW",
"totalAmount": 15000,
"balanceAmount": 15000,
"suppliedAmount": 13636,
"vat": 1364,
"taxFreeAmount": 0,
"method": "CARD"
}

✔️ 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.

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