"use strict"; const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0]; const {useMDXComponents: _provideComponents} = arguments[0]; function _createMdxContent(props) { const _components = { a: "a", code: "code", hr: "hr", img: "img", li: "li", p: "p", pre: "pre", span: "span", strong: "strong", ul: "ul", ..._provideComponents(), ...props.components }, {Accordion, AccordionItem, Button, ExternalLink, GlossaryPopover, Grid, GridCol, LogNextLink, Mermaid, SampleCodeDownloadButton, Spacing, Stack, TutorialHeader, TutorialSection, WidgetClientKey, WidgetSecretKey} = _components; if (!Accordion) _missingMdxReference("Accordion", true); if (!AccordionItem) _missingMdxReference("AccordionItem", true); if (!AccordionItem.Badge) _missingMdxReference("AccordionItem.Badge", true); if (!AccordionItem.Icon) _missingMdxReference("AccordionItem.Icon", true); if (!Button) _missingMdxReference("Button", true); if (!Button.Icon) _missingMdxReference("Button.Icon", true); if (!ExternalLink) _missingMdxReference("ExternalLink", true); if (!GlossaryPopover) _missingMdxReference("GlossaryPopover", true); if (!Grid) _missingMdxReference("Grid", true); if (!GridCol) _missingMdxReference("GridCol", true); if (!LogNextLink) _missingMdxReference("LogNextLink", true); if (!Mermaid) _missingMdxReference("Mermaid", true); if (!SampleCodeDownloadButton) _missingMdxReference("SampleCodeDownloadButton", true); if (!Spacing) _missingMdxReference("Spacing", true); if (!Stack) _missingMdxReference("Stack", false); if (!Stack.Horizontal) _missingMdxReference("Stack.Horizontal", true); if (!TutorialHeader) _missingMdxReference("TutorialHeader", true); if (!TutorialSection) _missingMdxReference("TutorialSection", true); if (!WidgetClientKey) _missingMdxReference("WidgetClientKey", true); if (!WidgetSecretKey) _missingMdxReference("WidgetSecretKey", true); return _jsxs(_Fragment, { children: [_jsx(_components.p, { children: "주문서형 결제를 사용하면 모든 결제수단을 한 번에 연동할 수 있어요. 프로젝트 언어를 선택하고 빠르게 시작하세요.\n연동이 끝나면 노코드로 결제수단 설정과 디자인을 변경할 수 있어요." }), "\n", _jsx(_components.p, { children: _jsx(_components.a, { href: "https://static.tosspayments.com/docs/payment-widget/overview/payment-widget-main.png", target: "_blank", rel: "noreferrer noopener", className: "rehype-image-link", children: _jsx(_components.img, { src: "https://static.tosspayments.com/docs/payment-widget/overview/payment-widget-main.png", alt: "토스페이먼츠 주문서형 결제", width: "3600", height: "1634" }) }) }), "\n", _jsxs(Grid, { gap: 16, children: [_jsxs(GridCol, { width: { sm: 4, md: 4, lg: 4 }, children: [_jsxs(_components.p, { children: [_jsx("img", { src: "https://static.toss.im/icons/png/4x/icon-square-check-blue.png", height: "20", style: { marginBottom: "-3px" } }), " 신용・체크 카드"] }), _jsxs(_components.p, { children: [_jsx("img", { src: "https://static.toss.im/icons/png/4x/icon-square-check-blue.png", height: "20", style: { marginBottom: "-3px" } }), " 계좌이체(퀵계좌이체)"] })] }), _jsxs(GridCol, { width: { sm: 4, md: 4, lg: 4 }, children: [_jsxs(_components.p, { children: [_jsx("img", { src: "https://static.toss.im/icons/png/4x/icon-square-check-blue.png", height: "20", style: { marginBottom: "-3px" } }), " 간편결제"] }), _jsxs(_components.p, { children: [_jsx("img", { src: "https://static.toss.im/icons/png/4x/icon-square-check-blue.png", height: "20", style: { marginBottom: "-3px" } }), " 휴대폰"] })] }), _jsxs(GridCol, { width: { sm: 4, md: 4, lg: 4 }, children: [_jsxs(_components.p, { children: [_jsx("img", { src: "https://static.toss.im/icons/png/4x/icon-square-check-blue.png", height: "20", style: { marginBottom: "-3px" } }), " 가상계좌"] }), _jsxs(_components.p, { children: [_jsx("img", { src: "https://static.toss.im/icons/png/4x/icon-square-check-blue.png", height: "20", style: { marginBottom: "-3px" } }), " 상품권"] })] })] }), "\n", _jsxs(_components.p, { children: ["아래 ", _jsx(_components.strong, { children: "문서용 테스트 키" }), " 또는 ", _jsx(_components.strong, { children: "전자결제 신청 이후에 확인 가능한 주문서형, 결제창형 연동 키" }), "를 사용하세요."] }), "\n", _jsx(_Fragment, { children: _jsx(_components.pre, { className: "shiki shiki-themes dark grey", style: { backgroundColor: "#122440", "-ShikiGreyBg": "#f2f4f6", color: "#EEFFFF", "-ShikiGrey": "#24292e", fontSize: "14px", lineHeight: "1.4" }, tabIndex: "0", title: "문서용 테스트 키", icon: "", children: _jsxs(_components.code, { children: [_jsxs(_components.span, { className: "line", children: [_jsx(_components.span, { style: { color: "#00A661", "-ShikiGrey": "#D73A49" }, children: "const" }), _jsx(_components.span, { style: { color: "#EEFFFF", "-ShikiGrey": "#005CC5" }, children: " clientKey" }), _jsx(_components.span, { style: { color: "#89DDFF", "-ShikiGrey": "#D73A49" }, children: " =" }), _jsx(_components.span, { style: { color: "#89DDFF", "-ShikiGrey": "#032F62" }, children: " \"" }), _jsx(_components.span, { style: { color: "#FFB74D", "-ShikiGrey": "#032F62" }, children: _jsx(WidgetClientKey, {}) }), _jsx(_components.span, { style: { color: "#89DDFF", "-ShikiGrey": "#032F62" }, children: "\"" }), _jsx(_components.span, { style: { color: "#89DDFF", "-ShikiGrey": "#24292E" }, children: ";" })] }), "\n", _jsxs(_components.span, { className: "line", children: [_jsx(_components.span, { style: { color: "#00A661", "-ShikiGrey": "#D73A49" }, children: "const" }), _jsx(_components.span, { style: { color: "#EEFFFF", "-ShikiGrey": "#005CC5" }, children: " secretKey" }), _jsx(_components.span, { style: { color: "#89DDFF", "-ShikiGrey": "#D73A49" }, children: " =" }), _jsx(_components.span, { style: { color: "#89DDFF", "-ShikiGrey": "#032F62" }, children: " \"" }), _jsx(_components.span, { style: { color: "#FFB74D", "-ShikiGrey": "#032F62" }, children: _jsx(WidgetSecretKey, {}) }), _jsx(_components.span, { style: { color: "#89DDFF", "-ShikiGrey": "#032F62" }, children: "\"" }), _jsx(_components.span, { style: { color: "#89DDFF", "-ShikiGrey": "#24292E" }, children: ";" })] })] }) }) }), "\n", _jsxs(Stack.Horizontal, { gutter: 12, children: [_jsx(Button, { as: "a", href: "https://developers.tosspayments.com/sandbox", type: "primary", size: "small", rightAddon: _jsx(Button.Icon, { name: "icon-arrow-right-small" }), children: _jsx(_components.p, { children: "샌드박스로 시작하기" }) }), _jsx(SampleCodeDownloadButton, { version: "v2", size: "small", rightAddon: _jsx(Button.Icon, { name: "icon-arrow-right-small" }), children: _jsx(_components.p, { children: "코드 샘플 다운로드하기" }) })] }), "\n", _jsx(Spacing, { size: 24 }), "\n", _jsx(_components.p, { children: _jsx(_components.a, { href: "https://static.toss.im/3d-common/Docs_image_5.png", target: "_blank", rel: "noreferrer noopener", className: "rehype-image-link", children: _jsx(_components.img, { src: "https://static.toss.im/3d-common/Docs_image_5.png", alt: "토스페이먼츠 주문서형 결제 흐름", width: "5568", height: "3976" }) }) }), "\n", _jsx(_components.hr, {}), "\n", _jsx(TutorialHeader, { step: 1, target: "client", children: _jsx(_components.p, { children: "주문서형 결제 렌더하기" }) }), "\n", _jsxs(TutorialSection, { title: "SDK 설치", children: [_jsx(_components.p, { children: "스크립트 태그 또는 npm 패키지로 결제 SDK를 설치하세요." }), _jsx(_Fragment, { children: _jsx(_components.pre, { className: "shiki grey", style: { backgroundColor: "#f2f4f6", color: "#24292e", fontSize: "14px", lineHeight: "1.4" }, tabIndex: "0", theme: "grey", copyable: "false", feedbackable: "false", icon: "", children: _jsx(_components.code, { children: _jsxs(_components.span, { className: "line", children: [_jsx(_components.span, { style: { color: "#24292E" }, children: "<" }), _jsx(_components.span, { style: { color: "#22863A" }, children: "script" }), _jsx(_components.span, { style: { color: "#6F42C1" }, children: " src" }), _jsx(_components.span, { style: { color: "#24292E" }, children: "=" }), _jsx(_components.span, { style: { color: "#032F62" }, children: "\"https://js.tosspayments.com/v2/standard\"" }), _jsx(_components.span, { style: { color: "#24292E" }, children: ">" })] }) }) }) }), _jsx(_Fragment, { children: _jsx(_components.pre, { className: "shiki grey", style: { backgroundColor: "#f2f4f6", color: "#24292e", fontSize: "14px", lineHeight: "1.4" }, tabIndex: "0", theme: "grey", copyable: "false", feedbackable: "false", icon: "", children: _jsx(_components.code, { children: _jsxs(_components.span, { className: "line", children: [_jsx(_components.span, { style: { color: "#6F42C1" }, children: "npm" }), _jsx(_components.span, { style: { color: "#032F62" }, children: " install" }), _jsx(_components.span, { style: { color: "#032F62" }, children: " @tosspayments/tosspayments-sdk" }), _jsx(_components.span, { style: { color: "#005CC5" }, children: " --save" })] }) }) }) })] }), "\n", _jsxs(TutorialSection, { title: "주문서형 결제 인스턴스 생성", children: [_jsx(_components.p, { children: "토스페이먼츠 SDK를 초기화한 다음에 주문서형 결제 인스턴스를 생성하세요." }), _jsxs(Accordion, { children: [_jsxs(AccordionItem, { title: "클라이언트 키로 토스페이먼츠 SDK를 초기화하세요.", badge: _jsx(AccordionItem.Icon, { name: "icon-step1-off" }), defaultExpanded: true, children: [_jsxs(_components.p, { children: ["개발자센터에서 ", _jsx(ExternalLink, { href: "https://developers.tosspayments.com/my/api-keys", children: "주문서형, 결제창형 연동 키 > 클라이언트 키" }), "를 불러오세요.\n주문서형, 결제창형 연동 키는 토스페이먼츠 전자결제 신청 이후에만 확인할 수 있어요. 신청 전에는 아래 테스트 키로 연동해보세요."] }), _jsx(_Fragment, { children: _jsx(_components.pre, { className: "shiki grey", style: { backgroundColor: "#f2f4f6", color: "#24292e", fontSize: "14px", lineHeight: "1.4" }, tabIndex: "0", theme: "grey", copyable: "false", feedbackable: "false", icon: "", children: _jsx(_components.code, { children: _jsx(_components.span, { className: "line", children: _jsx(_components.span, { children: _jsx(WidgetClientKey, {}) }) }) }) }) }), _jsxs(_components.p, { children: ["클라이언트 키로 ", _jsx(LogNextLink, { passHref: true, href: "/sdk/v2/js/environment#토스페이먼츠-초기화", children: _jsx(_components.code, { children: "TossPayments()" }) }), " 초기화 메서드를 호출하면 토스페이먼츠 객체가 생성돼요."] })] }), _jsx(AccordionItem, { title: "주문서형 결제 인스턴스를 생성하세요.", badge: _jsx(AccordionItem.Icon, { name: "icon-step2-off" }), defaultExpanded: true, children: _jsxs(_components.p, { children: ["초기화된 토스페이먼츠 객체로 ", _jsx(LogNextLink, { passHref: true, href: "/sdk/v2/js/payment-widget#tosspaymentswidgets", children: _jsx(_components.code, { children: "widget()" }) }), "을 호출해서 주문서형 결제 객체를 생성해주세요.\n메서드 파라미터로 각 회원 구매자에게 발급한 고유 ", _jsx(_components.code, { children: "customerKey" }), " 값을 넣어주세요. ", _jsx(_components.code, { children: "customerKey" }), "는 ", _jsx(GlossaryPopover, { children: _jsx(LogNextLink, { passHref: true, href: "/resources/glossary/uuid", children: "UUID" }) }), "와 같이 충분히 무작위적인 고유 값을 사용하세요. 비회원 구매자는 ", _jsx(_components.code, { children: "ANONYMOUS" }), " 값을 사용하세요."] }) })] })] }), "\n", _jsx(TutorialSection, { title: "결제 금액 설정", children: _jsxs(_components.p, { children: ["주문서형 결제 인스턴스로 ", _jsx(LogNextLink, { passHref: true, href: "/sdk/v2/js/payment-widget#widgetssetamount", children: _jsx(_components.code, { children: "setAmount()" }) }), " 메서드로 주문의 결제 금액을 설정해주세요. 쿠폰, 할인 등으로 결제 금액을 업데이트할 일이 있다면 같은 메서드를 사용하세요."] }) }), "\n", _jsx(TutorialSection, { title: "결제 영역 정의", children: _jsxs(_components.p, { children: ["결제 UI, 이용약관 UI를 보여주고 싶은 영역을 각각 ", _jsx(_components.code, { children: "div" }), " 태그로 정의하세요.\n결제 버튼도 만들어주세요."] }) }), "\n", _jsxs(TutorialSection, { title: "결제 UI 렌더링", children: [_jsxs(_components.p, { children: ["DOM이 생성된 이후에 ", _jsx(LogNextLink, { passHref: true, href: "/sdk/v2/js/payment-widget#widgetsrenderpaymentmethods", children: _jsx(_components.code, { children: "renderPaymentMethods()" }) }), " 메서드로 결제 UI를 렌더링하세요.\n결제 영역의 ", _jsx(_components.code, { children: "div" }), " CSS 선택자(Selector)와 결제 금액을 파라미터로 넣으세요. ", _jsx(LogNextLink, { passHref: true, href: "/guides/v2/payment-widget/admin#새로운-결제-ui-추가하기", children: "여러 결제 UI를 만들었다면" }), ", ", _jsx(_components.code, { children: "variantKey" }), "를 결제 어드민에서 확인하고 파라미터로 넘기세요."] }), _jsxs(Accordion, { children: [_jsx(AccordionItem, { title: "variantKey는 뭔가요?", badge: _jsx(AccordionItem.Icon, { name: "icon-q-mono" }), children: _jsxs(_components.p, { children: ["어드민에서 결제 UI를 여러 개 만들었다면, 각 UI에 부여되는 키에요. 더 자세한 내용은 ", _jsx(LogNextLink, { passHref: true, href: "/guides/v2/payment-widget/admin#새로운-결제-ui-추가하기", children: "새로운 결제 UI 추가하기" }), "를 참고하세요."] }) }), _jsx(AccordionItem, { title: "주문서형 결제에서 특정 결제수단을 미리 선택할 수 있나요?", badge: _jsx(AccordionItem.Icon, { name: "icon-q-mono" }), children: _jsx(_components.p, { children: "구매자가 처음 주문서에 진입하면 항상 첫 번째 결제수단이 선택되어 있습니다. 재방문하는 구매자는 이전에 구매할 때 사용한 결제수단이 선택되어 있습니다." }) }), _jsx(AccordionItem, { title: "렌더링이 완료된 것을 어떻게 알 수 있나요?", badge: _jsx(AccordionItem.Icon, { name: "icon-q-mono" }), children: _jsxs(_components.p, { children: [_jsx(LogNextLink, { passHref: true, href: "/sdk/v2/js/payment-widget#widgetsrenderpaymentmethods", children: _jsx(_components.code, { children: "renderPaymentMethods()" }) }), "는 비동기 메서드입니다."] }) }), _jsx(AccordionItem, { title: "결제 UI가 렌더링되지 않아요.", badge: _jsx(AccordionItem.Icon, { name: "icon-q-mono" }), children: _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "UNAUTHORIZED_KEY" }), " 에러가 나면 클라이언트 키를 다시 확인하세요."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "NOT_REGISTERED_PAYMENT_WIDGET" }), " 에러가 나면 상점관리자에서 결제 UI를 추가하세요. 결제 UI가 생성되지 않았을 때 발생하는 에러입니다."] }), "\n", _jsx(_components.li, { children: "CSS 선택자(Selector)를 정확히 입력했는지 확인하세요." }), "\n", _jsxs(_components.li, { children: ["특정 브라우저 환경에서만 렌더링이 안 된다면 익스텐션을 확인하세요. ", _jsx(LogNextLink, { passHref: true, href: "/guides/v2/get-started/environment#지원-플랫폼브라우저-환경", children: "IE 환경" }), "은 지원하지 않습니다."] }), "\n"] }) }), _jsx(AccordionItem, { title: "애플페이가 왜 안 보이나요?", badge: _jsx(AccordionItem.Icon, { name: "icon-q-mono" }), children: _jsx(_components.p, { children: "애플페이는 iPhone 및 Mac Safari 에서만 노출돼요. 어드민 페이지에서는 예상 이미지를 확인할 수 있습니다." }) }), _jsx(AccordionItem, { title: "가상계좌가 왜 안 보이나요?", badge: _jsx(AccordionItem.Icon, { name: "icon-q-mono" }), children: _jsx(_components.p, { children: "가상계좌는 문서용 테스트 키로 테스트할 수 없습니다. 토스페이먼츠와 전자결제 계약 체결 이후 발급되는 내 상점만의 API 테스트 키로 테스트해보세요." }) })] })] }), "\n", _jsx(TutorialSection, { title: "이용약관 UI 렌더링", children: _jsxs(_components.p, { children: [_jsx(LogNextLink, { passHref: true, href: "/sdk/v2/js/payment-widget#widgetsrenderagreement", children: _jsx(_components.code, { children: "renderAgreement()" }) }), " 메서드로 이용약관 UI를 렌더링하세요.\n이용약관 영역의 ", _jsx(_components.code, { children: "div" }), " CSS 선택자(Selector)를 파라미터로 넣으세요."] }) }), "\n", _jsx(TutorialSection, { title: "(선택) 기타 결제 UI 추가", children: _jsx(_components.p, { children: "할인 쿠폰, 가격 정보 등 구매자에게 보여주고 싶은 기타 결제 UI를 직접 만들어서 추가해주세요." }) }), "\n", _jsx(_components.hr, {}), "\n", _jsx(TutorialHeader, { step: 2, target: "client", children: _jsx(_components.p, { children: "결제 요청하기" }) }), "\n", _jsxs(TutorialSection, { title: "결제 버튼 이벤트 설정", children: [_jsxs(_components.p, { children: ["결제를 요청하기 전에 ", _jsx(_components.code, { children: "orderId" }), "와 ", _jsx(_components.code, { children: "amount" }), "를 서버에 임시로 저장하세요. 결제 요청과 승인 사이에 데이터 무결성을 확인할 때 필요해요. 더 자세한 내용은 ", _jsx(LogNextLink, { passHref: true, href: "/guides/v2/get-started/payment-flow#결제-요청-전에-결제할-데이터-저장하기", children: "결제 흐름" }), " 가이드에서 확인하세요."] }), _jsxs(_components.p, { children: ["결제 버튼에 결제 요청 메서드 ", _jsx(LogNextLink, { passHref: true, href: "/sdk/v2/js/payment-widget#widgetsrequestpayment", children: _jsx(_components.code, { children: "requestPayment()" }) }), "를 이벤트로 걸어주세요. 더 많은 파라미터는 ", _jsx(LogNextLink, { passHref: true, href: "/sdk/v2/js/brandpay#brandpayrequestpayment", children: "SDK 문서" }), "에서 확인하세요."] }), _jsx(_components.p, { children: "결제 UI가 렌더링된 이후에 결제 요청 메서드를 호출하세요." }), _jsxs(Accordion, { children: [_jsx(AccordionItem, { title: "'successUrl', 'failUrl'은 뭔가요??", badge: _jsx(AccordionItem.Icon, { name: "icon-q-mono" }), children: _jsxs(_components.p, { children: ["결제 요청 및 인증이 끝난 뒤에 리다이렉트 되는 URL입니다. 결제 요청이 성공하면 ", _jsx(_components.code, { children: "successUrl" }), "로, 실패하면 ", _jsx(_components.code, { children: "failUrl" }), "로 이동해요."] }) }), _jsx(AccordionItem, { title: "결제 UI가 렌더링되기 전에 결제를 요청하면 어떻게 되나요?", badge: _jsx(AccordionItem.Icon, { name: "icon-q-mono" }), children: _jsx(_components.p, { children: "구매자가 선택한 결제수단의 결제창이 정상적으로 열리지 않습니다. 반드시 결제 UI가 렌더링된 이후에 결제 요청 메서드를 호출하세요." }) }), _jsx(AccordionItem, { title: "구매자가 선택한 결제수단을 미리 알 수 있나요?", badge: _jsx(AccordionItem.Icon, { name: "icon-q-mono" }), children: _jsxs(_components.p, { children: ["네. 결제를 요청하기 전에 ", _jsx(LogNextLink, { passHref: true, href: "/sdk/v2/js/payment-widget#paymentmethodwidgetgetselectedpaymentmethod", children: _jsx(_components.code, { children: "getSelectedPaymentMethod()" }) }), "를 호출해서 구매자가 선택한 결제수단을 확인할 수 있습니다."] }) }), _jsxs(AccordionItem, { title: "커스텀 파라미터를 보내고 승인 응답으로 받고 싶어요.", badge: _jsx(AccordionItem.Icon, { name: "icon-q-mono" }), children: [_jsxs(_components.p, { children: ["결제 성공 후 이동하는 ", _jsx(_components.code, { children: "successUrl" }), "로 받으세요. 적은 양의 데이터라면 ", _jsx(_components.code, { children: "successUrl" }), "의 ", _jsx(GlossaryPopover, { children: _jsx(LogNextLink, { passHref: true, href: "/resources/glossary/query-param", children: "쿼리 파라미터" }) }), "로 추가하세요."] }), _jsx(_components.p, { children: "만약 데이터가 많거나 결제 완료 전에 데이터를 처리해야 한다면, 결제 요청을 하기 전에 데이터베이스에 저장하세요." })] })] })] }), "\n", _jsxs(TutorialSection, { title: "결제창 띄우기", children: [_jsx(_components.p, { children: "결제 UI에서 자주 사용하는 결제수단을 선택하고 '결제하기' 버튼을 누르세요. 선택한 결제수단의 결제창에서 정보를 입력하세요. 테스트 환경에서는 결제가 가상으로만 이뤄지기 때문에 결제수단에서 금액이 차감되지 않아요. 결제를 마치면 결제 인증이 완료된 거예요." }), _jsxs(_components.p, { children: ["클라이언트는 결제 인증이 성공하면 ", _jsx(_components.code, { children: "successUrl" }), "로 이동하고, 실패하면 ", _jsx(_components.code, { children: "failUrl" }), "로 이동해요."] }), _jsxs(Accordion, { children: [_jsx(AccordionItem, { title: "계속 로딩 중인 화면에서 변화가 없어요.", badge: _jsx(AccordionItem.Icon, { name: "icon-q-mono" }), children: _jsxs(_components.p, { children: ["아직 결제 요청 중이에요. 이어서 ", _jsx(_components.code, { children: "successUrl" }), ", ", _jsx(_components.code, { children: "failUrl" }), " 페이지에서 요청 결과를 확인한 뒤, 결제 승인 API까지 호출해야 결제가 완료돼요. iframe을 사용하고 있다면 요청 결과 페이지(", _jsx(_components.code, { children: "successUrl" }), ", ", _jsx(_components.code, { children: "failUrl" }), ")로 이동할 수가 없어요."] }) }), _jsx(AccordionItem, { title: "모바일 환경에서 화면이 카드사로 이동하지 않아요.", badge: _jsx(AccordionItem.Icon, { name: "icon-q-mono" }), children: _jsxs(_components.p, { children: ["카드사 앱스킴을 등록해야 돼요. 자세한 내용은 ", _jsx(LogNextLink, { passHref: true, href: "/guides/v2/webview", children: "웹뷰 가이드" }), "에서 확인하세요."] }) }), _jsx(AccordionItem, { title: "iframe에서 결제창을 띄울 수 있나요?", badge: _jsx(AccordionItem.Icon, { name: "icon-q-mono" }), children: _jsx(_components.p, { children: "iframe을 이용한 결제창 팝업 형태는 PC에서만 제공하고 있습니다." }) }), _jsxs(AccordionItem, { title: "왜 페이지가 이동하나요?", badge: _jsx(AccordionItem.Icon, { name: "icon-q-mono" }), children: [_jsx("p", { style: { textAlign: "center" }, children: _jsx(Mermaid, { chart: "flowchart LR\n id1(주문서형 결제 그리기) --> id2(결제 요청 및 인증) --successUrl---> id5(결제 승인 API)\n id2 --failUrl---> id7\n id5 --200 OK---> id6(결제 성공)\n id5 --ERROR---> id7(결제 실패)\n style id1 fill:#e8f2fe,stroke:#b9d7f1\n style id2 fill:#e8f2fe,stroke:#b9d7f1\n style id5 fill:#e8f2fe,stroke:#b9d7f1\n style id6 fill:#e8f2fe,stroke:#b9d7f1\n style id7 fill:#e8f2fe,stroke:#b9d7f1" }) }), _jsx(_components.p, { children: "결제 인증과 승인 사이에는 클라이언트가 이동하는 리다이렉트 과정이 있습니다." }), _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "결제 요청 과정에서 인증 결과를 받고 다음 단계로 넘어가기 위해 리다이렉트 URL 확인과 처리가 필요합니다." }), " 토스페이먼츠에서 인증 결과를 URL의 ", _jsx(GlossaryPopover, { children: _jsx(LogNextLink, { passHref: true, href: "/resources/glossary/query-param", children: "쿼리 파라미터" }) }), "에 담아 리다이렉트하면, 상점에서는 리다이렉트 URL을 받아 결제를 승인할 수 있어요."] }), _jsxs(_components.p, { children: ["더 자세한 내용은 ", _jsx(LogNextLink, { passHref: true, href: "/blog/redirect", children: "리다이렉트 처리하기" }), ", ", _jsx(LogNextLink, { passHref: true, href: "/guides/v2/get-started/payment-flow", children: "결제 흐름 이해하기" }), "에서 확인해보세요."] })] })] })] }), "\n", _jsx(_components.hr, {}), "\n", _jsx(TutorialHeader, { step: 3, target: "client", children: _jsx(_components.p, { children: "리다이렉트 URL로 이동하기" }) }), "\n", _jsxs(TutorialSection, { title: "successUrl로 이동한 경우", children: [_jsxs(_components.p, { children: ["결제 요청이 성공하면 ", _jsx(_components.code, { children: "successUrl" }), "로 이동합니다. URL에 아래 네 가지 쿼리 파라미터가 추가돼요."] }), _jsx(_Fragment, { children: _jsx(_components.pre, { className: "shiki grey", style: { backgroundColor: "#f2f4f6", color: "#24292e", fontSize: "14px", lineHeight: "1.4" }, tabIndex: "0", theme: "grey", copyable: "false", feedbackable: "false", icon: "", children: _jsxs(_components.code, { children: [_jsx(_components.span, { className: "line", children: _jsx(_components.span, { children: "/success?paymentType={PAYMENT_TYPE}&orderId={ORDER_ID}" }) }), "\n", _jsx(_components.span, { className: "line", children: _jsx(_components.span, { children: "&paymentKey={PAYMENT_KEY}&amount={AMOUNT}" }) })] }) }) }), _jsxs(_components.p, { children: ["쿼리 파라미터의 ", _jsx(_components.code, { children: "amount" }), " 값과 ", _jsx(_components.code, { children: "setAmount()" }), "의 ", _jsx(_components.code, { children: "amount" }), " 파라미터의 값이 같은지 반드시 확인하세요. 클라이언트에서 결제 금액을 조작하는 행위를 방지할 수 있습니다.\n만약 값이 다르다면 결제를 취소하고 구매자에게 알려주세요."] }), _jsxs(_components.p, { children: ["일반결제 및 해외 간편결제의 ", _jsx(_components.code, { children: "paymentType" }), "은 ", _jsx(_components.code, { children: "NORMAL" }), "입니다. ", _jsx(LogNextLink, { passHref: true, href: "/guides/v2/payment-widget/integration-brandpay", children: "브랜드페이 결제" }), "의 ", _jsx(_components.code, { children: "paymentType" }), "은 ", _jsx(_components.code, { children: "BRANDPAY" }), "입니다."] })] }), "\n", _jsx(TutorialSection, { title: "서버로 결제정보 전달", children: _jsxs(_components.p, { children: ["서버로 ", _jsx(_components.code, { children: "paymentKey" }), ", ", _jsx(_components.code, { children: "amount" }), ", ", _jsx(_components.code, { children: "orderId" }), " 값을 전달하세요. 결제 승인에 필요한 데이터입니다.\n결제 승인 결과에 따라 클라이언트에서 필요한 결제 성공 및 실패 로직을 추가하세요."] }) }), "\n", _jsxs(TutorialSection, { title: "failUrl로 이동한 경우", children: [_jsxs(_components.p, { children: ["결제 요청이 실패하면 ", _jsx(_components.code, { children: "failUrl" }), "로 이동합니다. 쿼리 파라미터로 돌아오는 에러 코드, 메시지를 확인하고 필요한 로직을 구현해주세요."] }), _jsx(_Fragment, { children: _jsx(_components.pre, { className: "shiki grey", style: { backgroundColor: "#f2f4f6", color: "#24292e", fontSize: "14px", lineHeight: "1.4" }, tabIndex: "0", theme: "grey", copyable: "false", feedbackable: "false", icon: "", children: _jsxs(_components.code, { children: [_jsx(_components.span, { className: "line", children: _jsx(_components.span, { children: "/fail?code={ERROR_CODE}&message={ERROR_MESSAGE}" }) }), "\n", _jsx(_components.span, { className: "line", children: _jsx(_components.span, { children: "&orderId={ORDER_ID}" }) })] }) }) }), _jsxs(Accordion, { children: [_jsxs(AccordionItem, { title: "PAY_PROCESS_CANCELED", badge: _jsx(AccordionItem.Badge, { size: 'small', color: 'grey', variant: 'weak', children: "트러블슈팅" }), children: [_jsx(_components.p, { children: _jsx(_components.strong, { children: "오류원인" }) }), _jsxs(_components.p, { children: ["구매자에 의해 결제가 취소되면 ", _jsx(_components.code, { children: "PAY_PROCESS_CANCELED" }), " 에러가 발생합니다. 결제 과정이 중단된 것이라서 ", _jsx(_components.code, { children: "failUrl" }), "로 ", _jsx(_components.code, { children: "orderId" }), "가 전달되지 않아요."] })] }), _jsxs(AccordionItem, { title: "PAY_PROCESS_ABORTED", badge: _jsx(AccordionItem.Badge, { size: 'small', color: 'grey', variant: 'weak', children: "트러블슈팅" }), children: [_jsx(_components.p, { children: _jsx(_components.strong, { children: "오류원인" }) }), _jsxs(_components.p, { children: ["결제가 실패하면 ", _jsx(_components.code, { children: "PAY_PROCESS_ABORTED" }), " 에러가 발생합니다."] }), _jsx(_components.p, { children: _jsx(_components.strong, { children: "해결 방법" }) }), _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: ["오류 메시지를 확인하세요. 계약 관련 오류는 토스페이먼츠 고객센터(1544-7772, ", _jsx(LogNextLink, { passHref: true, href: "mailto:support@tosspayments.com", children: "support@tosspayments.com" }), ")로 문의해주세요."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: ["기타 오류는 토스페이먼츠 ", _jsx(ExternalLink, { href: "https://discord.com/invite/A4fRFXQhRu", children: "실시간 기술지원 채널" }), "에서 문의해주세요."] }), "\n"] }), "\n"] })] }), _jsxs(AccordionItem, { title: "REJECT_CARD_COMPANY", badge: _jsx(AccordionItem.Badge, { size: 'small', color: 'grey', variant: 'weak', children: "트러블슈팅" }), children: [_jsx(_components.p, { children: _jsx(_components.strong, { children: "오류원인" }) }), _jsxs(_components.p, { children: ["구매자가 입력한 카드 정보에 문제가 있다면 ", _jsx(_components.code, { children: "REJECT_CARD_COMPANY" }), " 에러가 발생합니다."] }), _jsx(_components.p, { children: _jsx(_components.strong, { children: "해결 방법" }) }), _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "오류 메시지를 확인하고 구매자에게 안내를 해주세요." }), "\n"] })] })] })] }), "\n", _jsx(_components.hr, {}), "\n", _jsx(TutorialHeader, { step: 4, target: "server", children: _jsx(_components.p, { children: "결제 승인 API 호출하기" }) }), "\n", _jsxs(TutorialSection, { title: "시크릿 키로 Basic 인증 헤더 설정", children: [_jsxs(_components.p, { children: ["개발자센터에서 ", _jsx(ExternalLink, { href: "https://developers.tosspayments.com/my/api-keys", children: "주문서형, 결제창형 연동 키 > 시크릿 키" }), "를 불러오세요. 주문서형, 결제창형 연동 키는 토스페이먼츠 전자결제 신청 이후에만 확인할 수 있어요. 신청 전에는 아래 테스트 키로 연동해보세요."] }), _jsx(_Fragment, { children: _jsx(_components.pre, { className: "shiki grey", style: { backgroundColor: "#f2f4f6", color: "#24292e", fontSize: "14px", lineHeight: "1.4" }, tabIndex: "0", theme: "grey", copyable: "false", feedbackable: "false", icon: "", children: _jsx(_components.code, { children: _jsx(_components.span, { className: "line", children: _jsx(_components.span, { children: _jsx(WidgetSecretKey, {}) }) }) }) }) }), _jsxs(_components.p, { children: ["시크릿 키와 ", _jsx(_components.code, { children: ":" }), "을 ", _jsx(GlossaryPopover, { children: _jsx(LogNextLink, { passHref: true, href: "/resources/glossary/base64", children: "base64" }) }), "로 인코딩해서 ", _jsx(LogNextLink, { passHref: true, href: "/reference/using-api/authorization#시크릿-키로-인증하기", children: "Basic 인증 헤더" }), "를 아래와 같이 만들어주세요. ", _jsx(_components.code, { children: ":" }), "을 빠트리지 않도록 주의하세요. 비밀번호가 없다는 것을 알리기 위해 시크릿 키 뒤에 콜론을 추가합니다."] }), _jsx(_Fragment, { children: _jsx(_components.pre, { className: "shiki grey", style: { backgroundColor: "#f2f4f6", color: "#24292e", fontSize: "14px", lineHeight: "1.4" }, tabIndex: "0", theme: "grey", copyable: "false", feedbackable: "false", icon: "", children: _jsx(_components.code, { children: _jsx(_components.span, { className: "line", children: _jsx(_components.span, { children: "Basic base64(\"{WIDGET_SECRET_KEY}:\")" }) }) }) }) }), _jsx(_components.p, { children: "* 시크릿 키는 클라이언트, GitHub 등 외부에 노출되면 안 됩니다." })] }), "\n", _jsxs(TutorialSection, { title: "결제 승인 API 호출", children: [_jsxs(_components.p, { children: ["결제를 승인하면 결제수단에서 금액이 차감돼요. 토스페이먼츠 ", _jsx(LogNextLink, { passHref: true, href: "/reference#결제-승인", children: "결제 승인 API" }), "를 호출해서 결제를 완료하세요."] }), _jsxs(_components.p, { children: ["Authorization 헤더에 인코딩된 시크릿 키값을 추가하세요.\n", _jsx(_components.code, { children: "orderId" }), ", ", _jsx(_components.code, { children: "amount" }), ", ", _jsx(_components.code, { children: "paymentKey" }), "를 요청 데이터로 사용하세요."] })] }), "\n", _jsx(TutorialHeader, { step: 5, target: "server", children: _jsx(_components.p, { children: "결제 승인 결과 확인하기" }) }), "\n", _jsxs(TutorialSection, { title: "성공 응답", children: [_jsxs(_components.p, { children: ["결제 승인에 성공하면 HTTP ", _jsx(_components.code, { children: "200 OK" }), "와 ", _jsx(LogNextLink, { passHref: true, href: "/reference#payment-객체", children: "Payment 객체" }), "를 받습니다."] }), _jsx(_components.p, { children: _jsx(_components.strong, { children: "데이터 저장" }) }), _jsxs(_components.p, { children: [_jsx(_components.code, { children: "paymentKey" }), ", ", _jsx(_components.code, { children: "orderId" }), "는 서버에 필수로 저장하세요. 결제 조회, 결제 취소에 사용되는 값입니다. 나머지 값들은 필요에 따라 저장하세요."] }), _jsx(_components.p, { children: _jsx(_components.strong, { children: "결제수단" }) }), _jsxs(_components.p, { children: ["응답 객체에 선택한 결제수단 정보를 확인하세요. 결제 UI에서 신용・체크를 선택했다면, ", _jsx(_components.code, { children: "card" }), " 필드에 카드 정보 객체가 돌아와요. ", _jsx(_components.code, { children: "method" }), " 필드도 ", _jsx(_components.code, { children: "카드" }), "로 나와요."] }), _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: ["간편결제는 ", _jsx(LogNextLink, { passHref: true, href: "/guides/v2/easypay-response", children: "간편결제 응답 가이드" }), "를 확인하세요."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: ["가상계좌는 ", _jsx(ExternalLink, { href: "https://developers.tosspayments.com/my/payment-logs", children: "테스트 결제내역" }), "에서 입금을 처리할 수 있어요. 가상계좌는 반드시 ", _jsx(LogNextLink, { passHref: true, href: "/blog/virtual-account-webhook", children: "웹훅을 연동" }), "해야 최종 입금 알림을 받을 수 있어요."] }), "\n"] }), "\n"] }), _jsx(_components.p, { children: _jsx(_components.strong, { children: "API 버전" }) }), _jsxs(_components.p, { children: ["응답 객체는 API 버전에 따라 조금씩 달라집니다. ", _jsx(ExternalLink, { href: "https://developers.tosspayments.com/my/api-keys", children: "개발자센터" }), "에 설정된 API 버전을 확인하고, 원하는 필드가 있는 버전으로 변경해보세요. API 버전 업데이트 사항은 ", _jsx(LogNextLink, { passHref: true, href: "/resources/release-note", children: "릴리즈 노트" }), "에서 확인할 수 있습니다."] })] }), "\n", _jsxs(TutorialSection, { title: "실패 응답", children: [_jsxs(_components.p, { children: ["결제 승인에 실패하면 HTTP ", _jsx(_components.code, { children: "4XX" }), " 또는 ", _jsx(_components.code, { children: "5XX" }), " 코드와 에러 객체를 받습니다. 결제 승인의 전체 오류 목록은 ", _jsx(LogNextLink, { passHref: true, href: "/reference/error-codes#결제-승인", children: "에러 코드" }), "를 참고하세요."] }), _jsx(_Fragment, { children: _jsx(_components.pre, { className: "shiki grey", style: { backgroundColor: "#f2f4f6", color: "#24292e", fontSize: "14px", lineHeight: "1.4" }, tabIndex: "0", theme: "grey", copyable: "false", feedbackable: "false", icon: "", children: _jsxs(_components.code, { children: [_jsx(_components.span, { className: "line", children: _jsx(_components.span, { style: { color: "#24292E" }, children: "{" }) }), "\n", _jsxs(_components.span, { className: "line", children: [_jsx(_components.span, { style: { color: "#005CC5" }, children: " \"code\"" }), _jsx(_components.span, { style: { color: "#24292E" }, children: ": " }), _jsx(_components.span, { style: { color: "#032F62" }, children: "\"NOT_FOUND_PAYMENT_SESSION\"" }), _jsx(_components.span, { style: { color: "#24292E" }, children: "," })] }), "\n", _jsxs(_components.span, { className: "line", children: [_jsx(_components.span, { style: { color: "#005CC5" }, children: " \"message\"" }), _jsx(_components.span, { style: { color: "#24292E" }, children: ": " }), _jsx(_components.span, { style: { color: "#032F62" }, children: "\"결제 시간이 만료되어 결제 진행 데이터가 존재하지 않습니다.\"" })] }), "\n", _jsx(_components.span, { className: "line", children: _jsx(_components.span, { style: { color: "#24292E" }, children: "}" }) })] }) }) }), _jsxs(Accordion, { children: [_jsxs(AccordionItem, { title: "NOT_FOUND_PAYMENT_SESSION", badge: _jsx(AccordionItem.Badge, { size: 'small', color: 'grey', variant: 'weak', children: "트러블슈팅" }), children: [_jsx(_components.p, { children: _jsx(_components.strong, { children: "오류원인" }) }), _jsxs(_components.p, { children: ["결제 승인에서 요청에 문제가 있으면 ", _jsx(_components.code, { children: "NOT_FOUND_PAYMENT_SESSION" }), " 에러가 발생합니다."] }), _jsx(_components.p, { children: _jsx(_components.strong, { children: "해결 방법" }) }), _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: "결제 요청이 완료된 이후 10분 이내에 결제를 승인해야 됩니다. 10분이 지나면 결제 데이터가 유실되어 승인이 불가합니다." }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: ["결제 요청했을 때 돌려받은 ", _jsx(_components.code, { children: "paymentKey" }), "와 결제 승인에 사용한 ", _jsx(_components.code, { children: "paymentKey" }), "가 같은 값인지 확인하세요."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: "결제 요청에 사용한 클라이언트 키와 결제 승인에 사용한 시크릿 키가 매칭된 키값인지 확인하세요." }), "\n"] }), "\n"] })] }), _jsxs(AccordionItem, { title: "REJECT_CARD_COMPANY", badge: _jsx(AccordionItem.Badge, { size: 'small', color: 'grey', variant: 'weak', children: "트러블슈팅" }), children: [_jsx(_components.p, { children: _jsx(_components.strong, { children: "오류원인" }) }), _jsxs(_components.p, { children: ["카드사에서 해당 카드를 거절했을 때 ", _jsx(_components.code, { children: "REJECT_CARD_COMPANY" }), " 에러가 발생합니다. 원인은 비밀번호 오류, 한도 초과, 포인트 부족 등 다양합니다."] }), _jsx(_components.p, { children: _jsx(_components.strong, { children: "해결 방법" }) }), _jsx(_components.p, { children: "에러 메시지를 확인해서 원인을 파악하고 구매자에게 올바른 안내를 해주세요." })] }), _jsxs(AccordionItem, { title: "FORBIDDEN_REQUEST", badge: _jsx(AccordionItem.Badge, { size: 'small', color: 'grey', variant: 'weak', children: "트러블슈팅" }), children: [_jsx(_components.p, { children: _jsx(_components.strong, { children: "오류원인" }) }), _jsxs(_components.p, { children: ["API 키값 또는 주문번호가 최초 요청한 값과 다르면 ", _jsx(_components.code, { children: "FORBIDDEN_REQUEST" }), "가 발생합니다."] }), _jsx(_components.p, { children: _jsx(_components.strong, { children: "해결 방법" }) }), _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: "결제 요청에 사용한 클라이언트 키와 API 호출에 사용한 시크릿 키가 매칭된 키값인지 확인하세요." }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.code, { children: "orderId" }), ", ", _jsx(_components.code, { children: "paymentKey" }), " 값이 최초 결제 요청한 값과 같은지 확인하세요."] }), "\n"] }), "\n"] })] }), _jsxs(AccordionItem, { title: "UNAUTHORIZED_KEY", badge: _jsx(AccordionItem.Badge, { size: 'small', color: 'grey', variant: 'weak', children: "트러블슈팅" }), children: [_jsx(_components.p, { children: _jsx(_components.strong, { children: "오류원인" }) }), _jsxs(_components.p, { children: ["API 키를 잘못 입력하면 ", _jsx(_components.code, { children: "UNAUTHORIZED_KEY" }), " 에러가 발생합니다."] }), _jsx(_components.p, { children: _jsx(_components.strong, { children: "해결 방법" }) }), _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: ["클라이언트 키와 매칭된 시크릿 키를 사용하고 있는지 확인하세요. API 키는 토스페이먼츠에 로그인한 뒤에 개발자센터의 ", _jsx(ExternalLink, { href: "https://developers.tosspayments.com/my/api-keys", children: "API 키 메뉴" }), "에서 확인할 수 있어요."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(LogNextLink, { passHref: true, href: "/reference/using-api/authorization#시크릿-키로-인증하기", children: "시크릿 키 인코딩" }), "을 다시 확인하세요. 시크릿 키 뒤에 ", _jsx(_components.code, { children: ":" }), "을 추가하고 base64로 인코딩해서 사용해야 됩니다."] }), "\n"] }), "\n"] })] })] })] }), "\n", _jsxs(TutorialSection, { title: "다음 단계", children: [_jsxs(_components.p, { children: ["결제 연동을 완성하셨어요. 이제 개발자센터에서 ", _jsx(ExternalLink, { href: "https://developers.tosspayments.com/my/payment-logs", children: "테스트 결제내역" }), "을 확인하거나 ", _jsx(LogNextLink, { passHref: true, href: "/reference", children: "토스페이먼츠 코어 API" }), "로 결제를 조회 또는 취소해보세요."] }), _jsxs(_components.p, { children: ["실시간으로 결제 알림을 받고 싶다면 ", _jsx(LogNextLink, { passHref: true, href: "/guides/v2/webhook", children: "웹훅을 연동하세요" }), "."] })] })] }); } function MDXContent(props = {}) { const {wrapper: MDXLayout} = { ..._provideComponents(), ...props.components }; return MDXLayout ? _jsx(MDXLayout, { ...props, children: _jsx(_createMdxContent, { ...props }) }) : _createMdxContent(props); } return { default: MDXContent }; function _missingMdxReference(id, component) { throw new Error("Expected " + (component ? "component" : "object") + " `" + id + "` to be defined: you likely forgot to import, pass, or provide it."); }