결제위젯 연동하기
✅ 신용・체크 카드, 가상계좌, 계좌이체, 휴대폰, 상품권 결제를 웹 페이지에 한 번에 연동할 수 있어요. 계좌이체 결제는 간편한 퀵계좌결제를 활성화해서 사용해 보세요.
✅ 결제위젯 SDK를 사용해서 내 상점의 주문서 페이지에 최적의 주문서 UI를 만들 수 있어요.
결제위젯 연동 키 준비하기
결제위젯 연동 테스트 키를 준비하세요. 토스페이먼츠 계약, 회원가입 없이 아래 문서용 테스트 키로 바로 시작할 수 있어요. 개발자센터에 회원가입해서 나만의 테스트 키를 발급받으면 테스트 결제내역도 조회하고 웹훅을 연동할 수 있어요.
결제 UI 커스터마이징 기능은 어드민 체험하기에서 살펴보세요. 계약 이후에는 결제위젯 어드민에서 직접 결제 UI를 바꿀 수 있어요.
// 토스페이먼츠 회원가입하기 전이라면, 아래 문서용 테스트 키를 사용하세요. 문서용 테스트 키는 _docs_가 포함되어 있어요.
// 토스페이먼츠에 회원가입했다면, 개발자센터에서 내 테스트 상점 키를 확인하세요.
// 로그인한 상태라면, 문서에 있는 클라이언트 키, 시크릿 키가 내 테스트 키로 바뀌어요.
const clientKey = 'test_gck_docs_Ovk5rk1EwkEbP0W43n07xlzm'
const secretKey = 'test_gsk_docs_OaPz8L5KdmQXkzRz3y47BMw6'
토스페이먼츠와 계약을 완료했다면 상점 테스트 키로 결제위젯을 연동하고 상점관리자에서 커스터마이징을 해보세요. 상점 테스트 키는 '상점관리자 > 매출 · 정산 관리 > 내 상점 이름 > 개발 정보'에서 확인하세요.
계약 문의는 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 해주세요.
1. 결제위젯 그리기
아래 예제 코드는 주문서 페이지에 결제위젯, 이용약관 UI를 그립니다. 결제하기 버튼을 눌러서 결제창을 띄워보세요.
이 예제에서는 신용카드로 결제해 볼게요. 실제로 결제되지 않으니 안심하세요.
<head>
<meta charset="utf-8" />
<!-- 결제위젯 SDK 추가 -->
<script src="https://js.tosspayments.com/v1/payment-widget"></script>
</head>
<body>
<!-- 결제 UI, 이용약관 UI 영역 -->
<div id="payment-method"></div>
<div id="agreement"></div>
<!-- 할인 쿠폰 -->
<div>
<input type="checkbox" id="coupon-box" />
<label for="coupon-box"> 5,000원 쿠폰 적용 </label>
</div>
<!-- 결제하기 버튼 -->
<button id="payment-button">결제하기</button>
<script>
const clientKey = "test_gck_docs_Ovk5rk1EwkEbP0W43n07xlzm"
const customerKey = "" // 내 상점에서 고객을 구분하기 위해 발급한 고객의 고유 ID
const coupon = document.getElementById("coupon-box")
const button = document.getElementById("payment-button")
// ------ 결제위젯 초기화 ------
// 비회원 결제에는 customerKey 대신 ANONYMOUS를 사용하세요.
const paymentWidget = PaymentWidget(clientKey, customerKey) // 회원 결제
// const paymentWidget = PaymentWidget(clientKey, PaymentWidget.ANONYMOUS) // 비회원 결제
// ------ 결제 UI 렌더링 ------
// 결제 UI를 렌더링할 위치를 지정합니다. `#payment-method`와 같은 CSS 선택자와 결제 금액 객체를 추가하세요.
// DOM이 생성된 이후에 렌더링 메서드를 호출하세요.
// https://docs.tosspayments.com/reference/widget-sdk#renderpaymentmethods선택자-결제-금액-옵션
const paymentMethodWidget = paymentWidget.renderPaymentMethods(
"#payment-method",
{ value: 50000 },
// 렌더링하고 싶은 결제 UI의 variantKey
// 결제 수단 및 스타일이 다른 멀티 UI를 직접 만들고 싶다면 계약이 필요해요.
// https://docs.tosspayments.com/guides/payment-widget/admin#멀티-결제-ui
{ variantKey: "DEFAULT" }
)
// ------ 이용약관 UI 렌더링 ------
// 이용약관 UI를 렌더링할 위치를 지정합니다. `#agreement`와 같은 CSS 선택자를 추가하세요.
// https://docs.tosspayments.com/reference/widget-sdk#renderagreement선택자-옵션
paymentWidget.renderAgreement(
'#agreement',
{ variantKey: "AGREEMENT" } // 기본 이용약관 UI 렌더링
)
// ------ 금액 업데이트 ------
// 새로운 결제 금액을 넣어주세요.
// https://docs.tosspayments.com/reference/widget-sdk#updateamount결제-금액
coupon.addEventListener("change", function () {
if (coupon.checked) {
paymentMethodWidget.updateAmount(amount - 5000)
} else {
paymentMethodWidget.updateAmount(amount)
}
})
// ------ '결제하기' 버튼 누르면 결제창 띄우기 ------
// 더 많은 결제 정보 파라미터는 결제위젯 SDK에서 확인하세요.
// https://docs.tosspayments.com/reference/widget-sdk#requestpayment결제-정보
button.addEventListener("click", function () {
paymentWidget.requestPayment({
orderId: "",
orderName: "토스 티셔츠 외 2건",
successUrl: window.location.origin + "/success",
failUrl: window.location.origin + "/fail",
customerEmail: "customer123@gmail.com",
customerName: "김토스",
customerMobilePhone: "01012341234"
})
})
</script>
</body>
트러블슈팅
아직 결제 요청 중이에요. 이어서 successUrl, failUrl에 설정한 페이지에서 요청 결과를 확인한 뒤, 결제 승인 API 호출까지 해야 결제가 완료돼요. iframe을 사용하고 있다면 요청 결과 페이지(successUrl, failUrl)로 이동할 수가 없어요.
결제 금액이 바뀐다면 updateAmount()를 사용해서 결제위젯을 업데이트하세요.
const paymentMethodsWidget = paymentWidget.renderPaymentMethods()
// 새로운 결제 금액을 넣어주세요.
paymentMethodsWidget.updateAmount(5000)
customerKey는 내 상점에서 고객을 구분하기 위해 발급한 고객의 고유 ID입니다. 다른 사용자가 이 값을 알게 되면 악의적으로 사용할 수 있어 자동 증가하는 숫자는 안전하지 않습니다. UUID와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 또, 고객에게 할당된 customerKey는 변경 없이 항상 같은 값을 사용해주세요. customerKey는 재구매율, 이탈률, 구매전환율 등을 측정하거나 결제창에서 이탈한 고객을 다시 결제로 유도하는데 이용됩니다.
토스페이먼츠에서 발급하지 않은 클라이언트 키 혹은 시크릿 키를 사용했을 때 발생합니다. 개발자센터에 들어가서 키 값을 다시 확인하고 시크릿 키 인증을 올바르게 했는지 확인해주세요.
결제위젯을 생성하지 않은 클라이언트 키로 연동을 시도하면 발생합니다. 상점관리자에서 결제위젯 UI를 추가하세요.
2. 테스트 결제 후 페이지 이동 확인하기
결제창을 띄워 테스트 결제를 하면, 페이지가 이동해요. 이동한 페이지에서 결제 요청 결과를 확인할 수 있어요.
이렇게 인증과 승인 사이에 리다이렉트(페이지 이동) 과정이 있습니다.
두 단계로 나누어져 있는 결제 요청 과정에서 첫 번째 단계인 인증 결과를 받아 다음 단계로 넘어가기 위해 리다이렉트 URL 확인과 처리가 필요합니다. 토스페이먼츠에서 인증 결과를 URL의 쿼리 파라미터에 담아 리다이렉트하면, 상점에서는 리다이렉트 URL을 받아 결제 승인을 처리할 수 있게 됩니다.
인증에 성공했다면 성공 리다이렉트 URL(successUrl)에 쿼리 파라미터로 담긴 결제 정보를 이용해 승인 API를 호출합니다. 인증에 실패했다면 이동한 실패 리다이렉트 URL(failUrl)에 쿼리 파라미터로 담긴 에러 정보를 보며 디버깅합니다.
더 자세한 내용은 리다이렉트 처리하기, 결제 흐름 이해하기에서 확인해보세요.
결과로 돌아온 쿼리 파라미터로 다음 단계인 결제 승인을 요청합니다. 끝까지 다 연동했다면 결제 고객 입장에서는 페이지 이동과 다음 단계인 결제 승인 API 호출이 순식간에 이뤄져서 인지하기 어려워요.
테스트 결제 요청이 성공하면 requestPayment()의 파라미터로 설정했던 (successUrl)을 통해 결제 성공 페이지로 이동해요. 성공 리다이렉트 URL을 나타내는 success 뒤에 네 가지 쿼리 파라미터가 들어있습니다.
https://{ORIGIN}/success?paymentType={PAYMENT_TYPE}&orderId={ORDER_ID}&paymentKey={PAYMENT_KEY}&amount={AMOUNT}
paymentType: 결제 유형입니다.NORMAL,BRANDPAY,KEYIN중 하나입니다. 브랜드페이, 키인 결제를 사용할 때만 확인하면 되는 파라미터입니다. 지금과 같은 경우에는 항상NORMAL이 돌아옵니다.orderId:주문 ID입니다. 주문한 결제를 식별하는 역할로, 결제를 요청할 때 가맹점에서 만들어서requestPayment()에 담아 보낸 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 중복되지 않는 고유한 값을 발급해야 합니다. 결제 상태가 변해도 값이 유지됩니다.paymentKey: 결제의 키 값입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 값이 유지됩니다. 결제 승인에 사용됩니다.amount: 실제로 결제된 금액입니다.
renderPaymentMethods() 메서드에 담아 보낸 결제 금액과 successUrl로 돌아온 amount 값이 같은지 반드시 확인해보세요. 클라이언트에서 결제 금액을 조작해 승인하는 행위를 방지할 수 있습니다.
만약 값이 다르다면 결제를 취소하고 구매자에게 알려주세요. 적립금이나 쿠폰이 적용된 금액이 맞는지도 확인해보세요.
결제 요청이 실패했을 때
결제 요청이 실패하면 설정했던 결제 실패 페이지(failUrl)로 이동합니다. 에러 목록을 확인하세요.
https://{ORIGIN}/fail?code={ERROR_CODE}&message={ERROR_MESSAGE}&orderId={ORDER_ID}
3. 결제 승인하기
결제 승인 API를 호출해서 마지막 단계를 완료합니다. 먼저 API 인증을 위해 아래와 같이 인증 헤더 값을 만듭니다.
시크릿 키 뒤에 :을 추가하고 base64로 인코딩합니다. :을 빠트리지 않도록 주의하세요.
토스페이먼츠에서는 기본적으로 Basic 인증 방식을 사용하기 때문이에요. Basic 인증은 인증 정보로 사용자 ID, 비밀번호를 사용해요. 다음과 같이 base64로 인코딩한 “사용자ID:비밀번호” 문자열을 Basic과 함께 인증 헤더에 입력하는 방식이죠.
Authorization: Basic base64({USERNAME}:{PASSWORD})
토스페이먼츠는 시크릿 키를 사용자 ID, 즉 {USERNAME}으로 사용하고, 비밀번호는 따로 넣지 않는 방식이에요. 그래서 마지막에 :만 남게 됩니다. 더 자세한 내용은 토스페이먼츠 콘텐츠 Basic 인증과 Bearer 인증의 모든 것에서 확인해보세요.
base64('test_gsk_docs_OaPz8L5KdmQXkzRz3y47BMw6:')
─────────────────┬─────────────────── ┬
secretKey :
결제위젯 연동 키 > 시크릿 키 콜론
아래 명령어를 터미널에서 실행하면 인코딩된 값을 얻을 수 있습니다.
echo -n 'test_gsk_docs_OaPz8L5KdmQXkzRz3y47BMw6:' | base64
인코딩된 값을 Basic 인증 헤더에 넣고 요청 본문도 추가하세요.
- 헤더에
Authorization을 추가하고Basic {인코딩된 값}을 넣어주세요. 아래 예제 코드를 참고하세요. - 요청 본문으로는 앞 단계에서 리다이렉트 URL로 받은
paymentKey,orderId,amount를 넣어주세요. 아래 예제 코드에는 내 테스트 결제의paymentKey값을 넣어 실행해주세요.
curl --request POST \
--url https://api.tosspayments.com/v1/payments/confirm \
--header 'Authorization: Basic dGVzdF9nc2tfZG9jc19PYVB6OEw1S2RtUVhrelJ6M3k0N0JNdzY6' \
--header 'Content-Type: application/json' \
--data '{"paymentKey":"{PAYMENT_KEY}","amount":50000,"orderId":"-p8_v9S0Gb9HjIwd8FJTO"}'성공 페이지로 리다이렉트 된 후 10분 이내에 결제 승인 API를 호출하지 않았거나, 결제창을 iframe 안에서 호출했기 때문입니다. 브라우저의 보안 정책에 따라 성공 페이지로 이동이 차단될 수 있으니 iframe은 사용하지 말아주세요.
4. 결제 완료 후 응답 확인하기
결제 승인에 성공하면 HTTP 200 OK와 Payment 객체를 받습니다.
{
"mId": "tosspayments",
"version": "2022-11-16",
"paymentKey": "",
"status": "DONE",
"lastTransactionKey": "",
"orderId": "",
"orderName": "토스 티셔츠 외 2건",
"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": "신용",
"ownerType": "개인",
"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": "카드"
}
결제수단별 응답
퀵계좌결제와 계좌이체는 transfer 필드에 결제 정보가 담겨있습니다. transfer 필드에 담겨있는 bankCode는 이체 은행 코드입니다. 더 자세한 응답 필드 설명은 API 문서를 참고하세요.
{
"mId": "tosspayments",
"version": "2022-11-16",
"paymentKey": "",
"status": "DONE",
"lastTransactionKey": "",
"orderId": "",
"orderName": "토스 티셔츠 외 2건",
"requestedAt": "2022-06-08T15:40:09+09:00",
"approvedAt": "2022-06-08T15:40:49+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": null,
"virtualAccount": null,
"transfer": {
"bankCode": "92",
"settlementStatus": "INCOMPLETED"
},
"mobilePhone": null,
"giftCertificate": null,
"cashReceipt": {
"type": "소득공제",
"receiptKey": "G45eDbZnodP9BRQmyarY5wX5oAPGwLrJ07KzLNkE6AOMwXYW",
"issueNumber": "158269135",
"receiptUrl": "https://dashboard.tosspayments.com/receipts/cash-receipt/pS28vbVw01GMDz2m9Dstz/tvivarepublica?ref=PX",
"amount": 70000,
"taxFreeAmount": 0
},
"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 객체와 easyPay 객체가 함께 들어있습니다. card 객체에는 결제에 사용한 카드 정보가 들어있고, easyPay 객체에는 결제에 사용한 간편결제 정보가 들어있습니다.
easyPay의 amount는 간편결제 서비스에 등록된 계좌 혹은 현금성 포인트로 결제한 금액, easyPay의 discountAmount는 간편결제 서비스에서 제공하는 포인트나 쿠폰 등으로 결제한 금액입니다. 따라서 전액 카드로 결제했다면 amount와 discountAmount는 0입니다.
더 자세한 내용은 간편결제 응답 처리를 참고하세요.
{
"mId": "tosspayments",
"version": "2022-11-16",
"paymentKey": "",
"status": "DONE",
"lastTransactionKey": "",
"orderId": "",
"orderName": "토스 티셔츠 외 2건",
"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": "신용",
"ownerType": "개인",
"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": {
"provider": "토스페이",
"amount": 0,
"discountAmount": 0
},
"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": "간편결제"
}
가상계좌 결제 요청 결과는 virtualAccount 필드에 담겨있습니다. virtualAccount 필드에 담겨있는 accountNumber는 발급된 가상계좌 번호이고, dueDate는 입금 기한입니다. expired는 입금 기한이 지났는지 여부입니다. 더 자세한 응답 필드 설명은 API 문서를 참고하세요.
테스트 환경에서 발급된 가상계좌는 계좌번호 앞에 'X'가 붙습니다. 테스트 환경에서 발급된 계좌로 직접 입금할 수 없지만, 개발자센터의 테스트 결제내역 메뉴에서 입금처리를 할 수 있습니다.
결제위젯 어드민에서 고객의 환불 계좌 정보를 입력 기능을 활성화했다면 환불 계좌 정보를 확인하세요.
{
"mId": "tosspayments",
"version": "2022-11-16",
"paymentKey": "",
"status": "DONE",
"lastTransactionKey": "",
"orderId": "",
"orderName": "토스 티셔츠 외 2건",
"requestedAt": "2022-06-08T15:40:09+09:00",
"approvedAt": "2022-06-08T15:40:49+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": null,
"virtualAccount": {
"accountNumber": "X6516204518243",
"accountType": "일반",
"bankCode": "20",
"customerName": "김토스",
"dueDate": "2023-11-03T10:23:08+09:00",
"expired": false,
"settlementStatus": "INCOMPLETED",
"refundStatus": "NONE",
"refundReceiveAccount": 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": "가상계좌"
}
상품권 결제는 giftCertificate 필드에 결제 정보가 담겨있습니다. giftCertificate 필드에 담겨있는 approveNo는 결제 승인 번호입니다. 더 자세한 응답 필드 설명은 API 문서를 참고하세요.
method에는 '문화상품권', '도서문화상품권', '게임문화상품권' 중 선택한 상품권 결제수단이 들어옵니다.
{
"mId": "tosspayments",
"version": "2022-11-16",
"paymentKey": "",
"status": "DONE",
"lastTransactionKey": "",
"orderId": "",
"orderName": "토스 티셔츠 외 2건",
"requestedAt": "2022-06-08T15:40:09+09:00",
"approvedAt": "2022-06-08T15:40:49+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": null,
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": {
"approveNo": "0231026202237jQNi4",
"settlementStatus": "INCOMPLETED"
},
"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": "문화상품권"
}
휴대폰 결제는 mobilePhone 필드에 결제 정보가 담겨있습니다. mobilePhone 필드에 담겨있는 customerMobilePhone은 결제 고객의 휴대폰 번호입니다. 더 자세한 응답 필드 설명은 API 문서를 참고하세요.
{
"mId": "tosspayments",
"version": "2022-11-16",
"paymentKey": "",
"status": "DONE",
"lastTransactionKey": "",
"orderId": "",
"orderName": "토스 티셔츠 외 2건",
"requestedAt": "2022-06-08T15:40:09+09:00",
"approvedAt": "2022-06-08T15:40:49+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": null,
"virtualAccount": null,
"transfer": null,
"mobilePhone": {
"customerMobilePhone": "01012345678",
"settlementStatus": "INCOMPLETED",
"receiptUrl": "https://pgweb.tosspayments.com:9091/MpFlowCtrl?eventDiv1=search&eventDiv2=getWirelessReceipt&trxid=tviva202310262024459lq95&SYSTEM=NEW"
},
"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": "휴대폰"
}
확인할 내용
✔️ 응답 객체에 선택한 결제수단 필드가 있는지 확인하세요. 만약 원하는 필드가 없다면 API 버전을 확인해보세요. 응답 객체의 필드는 API 버전에 따라 조금씩 달라집니다. 개발자센터에 설정된 API 버전을 확인하고, 원하는 필드가 있는 버전으로 변경해보세요. API 버전 업데이트 사항은 릴리즈 노트에서 확인할 수 있습니다.
✔️ 응답 객체의 method가 선택한 결제수단이 맞는지 확인하세요.
결제 승인에 실패했다면
결제 승인 요청이 정상적으로 처리되지 않으면 응답으로 HTTP 상태 코드와 함께 아래와 같은 에러 객체가 돌아옵니다.
{
"code": "NOT_FOUND_PAYMENT",
"message": "존재하지 않는 결제 입니다."
}
code: 에러 타입을 보여주는 에러 코드입니다.message: 에러 메시지입니다. 에러 발생 이유를 알려줍니다.
API 별 에러 코드와 메시지는 에러 코드 페이지에서 살펴보세요.
FAQ
결제위젯 SDK는 Web, Native Android, Native iOS, React Native, Flutter를 지원하고 있어요.
네. getSelectedPaymentMethod()를 호출해서 고객이 선택한 결제수단을 확인할 수 있습니다.
아니요. 렌더링이 완료되었을 때 이벤트를 제공하지 않습니다.
아니요. 커스텀 파라미터를 보내거나 결제 승인 응답에 커스텀 파라미터를 포함시키는 기능은 지원되지 않습니다.
대신 다음과 같은 방법을 사용할 수 있습니다. 첫 번째 방법은 결제 성공 후 이동하는 successUrl로 받는 방법입니다. 적은 양의 데이터라면 successUrl의 쿼리 파라미터로 추가해서 확인할 수 있습니다. 만약 전달하고자 하는 데이터가 많거나 결제 완료 전에 데이터를 처리해야 한다면, 결제 요청을 하기 전에 데이터베이스에 저장하세요. 예를 들면 orderId 등과 데이터를 매핑해서 가맹점 데이터베이스에 저장하는 방식입니다. 또는 세션이나 쿠키를 활용하거나 Promise를 사용해서 객체로 데이터를 받을 수 있습니다. 다만 Promise 방식은 모바일에서 사용할 수 없으니 유의하세요.
애플페이는 iPhone 및 Mac Safari 에서만 노출돼요. 어드민 페이지에서는 예상 이미지를 확인할 수 있습니다.