개요
인라인 체크아웃을 사용하면 웹사이트나 애플리케이션과 원활하게 통합된 체크아웃 경험을 생성할 수 있습니다. 페이지 위에 모달로 열리는 오버레이 체크아웃과 달리, 인라인 체크아웃은 결제 양식을 페이지 레이아웃에 직접 임베드합니다. 인라인 체크아웃을 사용하면 다음을 수행할 수 있습니다:- 앱이나 웹사이트와 완전히 통합된 체크아웃 경험 생성
- Dodo Payments가 고객 및 결제 정보를 안전하게 캡처하도록 최적화된 체크아웃 프레임 사용
- 페이지에 Dodo Payments의 항목, 총액 및 기타 정보 표시
- SDK 메서드 및 이벤트를 사용하여 고급 체크아웃 경험 구축

작동 방식
인라인 체크아웃은 웹사이트나 앱에 안전한 Dodo Payments 프레임을 임베드하여 작동합니다. 체크아웃 프레임은 고객 정보를 수집하고 결제 세부 정보를 캡처하는 역할을 합니다. 페이지는 항목 목록, 총액 및 체크아웃에서 변경할 수 있는 옵션을 표시합니다. SDK를 사용하면 페이지와 체크아웃 프레임이 상호작용할 수 있습니다. Dodo Payments는 체크아웃이 완료되면 자동으로 구독을 생성하여 프로비저닝할 준비를 합니다.인라인 결제 프레임은 모든 민감한 결제 정보를 안전하게 처리하여, 귀사가 추가 인증 없이도 PCI 기준을 준수할 수 있도록 합니다.
좋은 인라인 체크아웃의 조건
고객이 누구에게서 구매하고 있는지, 무엇을 구매하고 있는지, 얼마를 지불하고 있는지 아는 것이 중요합니다. 준수 및 전환 최적화를 위한 인라인 체크아웃을 구축하려면 구현에 다음이 포함되어야 합니다:
- 정기 정보: 정기적인 경우, 얼마나 자주 반복되는지 및 갱신 시 지불할 총액. 체험판인 경우, 체험판 기간.
- 항목 설명: 구매하는 항목에 대한 설명.
- 거래 총액: 거래 총액, 포함된 소계, 총 세금 및 총합. 통화도 포함해야 합니다.
- Dodo Payments 바닥글: Dodo Payments에 대한 정보, 판매 조건 및 개인정보 보호정책이 포함된 전체 인라인 체크아웃 프레임.
- 환불 정책: Dodo Payments의 표준 환불 정책과 다를 경우 환불 정책에 대한 링크.
고객 여정
체크아웃 흐름은 체크아웃 세션 구성에 따라 결정됩니다. 체크아웃 세션을 구성하는 방식에 따라 고객은 모든 정보를 단일 페이지에서 또는 여러 단계에 걸쳐 제공받는 체크아웃을 경험하게 됩니다.Customer opens checkout
아이템이나 기존 거래를 전달하여 인라인 체크아웃을 열 수 있습니다. SDK를 사용하여 페이지 정보를 표시하고 업데이트하며, 고객 상호작용에 따라 아이템을 업데이트하는 SDK 메서드를 사용하세요.

Customer enters their details
인라인 체크아웃은 먼저 고객에게 이메일 주소를 입력하고, 국가를 선택하며, (필요한 경우) 우편번호를 입력하도록 요청합니다. 이 단계에서는 세금 및 사용 가능한 결제 옵션을 결정하는 데 필요한 모든 정보를 수집합니다.고객 세부 정보를 미리 채우고 저장된 주소를 제시하여 경험을 간소화할 수 있습니다.
Customer selects payment method
세부 정보를 입력한 후 고객은 사용 가능한 결제 방법과 결제 양식을 제시받습니다. 옵션에는 신용 카드, 직불 카드, PayPal, Apple Pay, Google Pay 및 고객의 위치에 따라 다른 지역 결제 방법이 포함될 수 있습니다.가능한 경우 저장된 결제 방법을 표시하여 체크아웃 속도를 높입니다.

Checkout completed
Dodo Payments는 모든 결제를 해당 판매에 가장 적합한 인수자에게 라우팅하여 성공 가능성을 극대화합니다. 고객은 귀하가 구축할 수 있는 성공 워크플로우로 들어갑니다.

빠른 시작
몇 줄의 코드로 Dodo Payments 인라인 체크아웃을 시작하세요:단계별 통합 가이드
Initialize the SDK for Inline Display
SDK를 초기화하고
displayType: 'inline'을 지정하세요. checkout.breakdown 이벤트를 청취하여 실시간 세금 및 총계 계산으로 UI를 업데이트하는 것도 권장합니다.Test Your Integration
- 개발 서버를 시작하세요:
- 체크아웃 흐름을 테스트하세요:
- 인라인 프레임에 이메일 및 주소 세부 정보를 입력하세요.
- 사용자 정의 주문 요약이 실시간으로 업데이트되는지 확인하세요.
- 테스트 자격 증명을 사용하여 결제 흐름을 테스트하세요.
- 리디렉션이 올바르게 작동하는지 확인하세요.
onEvent 콜백에 콘솔 로그를 추가한 경우, 브라우저 콘솔에 checkout.breakdown 이벤트가 기록되는 것을 확인할 수 있습니다.완전한 React 예제
이 예시는 인라인 결제와 함께 사용자 정의 주문 요약을 구현하는 방법을 보여주며,checkout.breakdown 이벤트를 사용하여 두 요소를 동기화합니다.
API 참조
구성
초기화 옵션
| 옵션 | 유형 | 필수 | 설명 |
|---|---|---|---|
mode | "test" | "live" | 예 | 환경 모드입니다. |
displayType | "inline" | "overlay" | 예 | 결제를 임베드하려면 "inline"으로 설정해야 합니다. |
onEvent | function | 예 | 결제 이벤트를 처리하는 콜백 함수입니다. |
체크아웃 옵션
| 옵션 | 유형 | 필수 | 설명 |
|---|---|---|---|
checkoutUrl | string | 예 | 체크아웃 세션 URL. |
elementId | string | 예 | 체크아웃을 렌더링할 DOM 요소의 id입니다. |
options.showTimer | boolean | 아니요 | 체크아웃 타이머 표시 여부. 기본값은 true입니다. 비활성화하면 세션이 만료될 때 checkout.link_expired 이벤트를 받습니다. |
options.showSecurityBadge | boolean | 아니요 | 보안 배지 표시 여부. 기본값은 true입니다. |
options.manualRedirect | boolean | 아니요 | 활성화하면 체크아웃 완료 후 자동 리디렉션이 발생하지 않습니다. 대신 리디렉션을 직접 처리하기 위해 checkout.status 및 checkout.redirect_requested 이벤트를 수신합니다. |
options.payButtonText | string | 아니요 | 결제 버튼에 표시할 사용자 지정 텍스트. |
options.fontSize | FontSize | 아니요 | 체크아웃의 전역 글꼴 크기. |
options.fontWeight | FontWeight | 아니요 | 체크아웃의 전역 글꼴 두께. |
메서드
체크아웃 열기
지정된 컨테이너에서 체크아웃 프레임을 엽니다.manualRedirect 사용 시, onEvent 콜백에서 결제 완료를 처리하세요:
체크아웃 닫기
프로그래밍적으로 체크아웃 프레임을 제거하고 이벤트 리스너를 정리합니다.상태 확인
현재 체크아웃 프레임이 주입되었는지 여부를 반환합니다.이벤트
SDK는onEvent 콜백을 통해 실시간 이벤트를 제공합니다. 인라인 결제에서는 checkout.breakdown가 UI를 동기화하는 데 특히 유용합니다.
| 이벤트 유형 | 설명 |
|---|---|
checkout.opened | 결제 프레임이 로드되었습니다. |
checkout.form_ready | 결제 폼이 사용자 입력을 받을 준비가 되었습니다. 로딩 상태를 숨기고 결제 UI를 표시할 때 유용합니다. |
checkout.breakdown | 가격, 세금 또는 할인이 업데이트될 때 발생합니다. |
checkout.customer_details_submitted | 고객 정보가 제출되었습니다. |
checkout.pay_button_clicked | 고객이 결제 버튼을 클릭할 때 발생합니다. 분석 및 전환 퍼널 추적에 유용합니다. |
checkout.redirect | 결제가 리디렉션을 수행합니다(예: 은행 페이지). |
checkout.error | 결제 중 오류가 발생했습니다. |
checkout.link_expired | 결제 세션이 만료될 때 발생합니다. showTimer가 false로 설정되어 있을 때만 수신됩니다. |
checkout.status | manualRedirect이 활성화되었을 때 발생합니다. 결제 상태(succeeded, failed 또는 processing)를 포함합니다. |
checkout.redirect_requested | manualRedirect이 활성화되었을 때 발생합니다. 고객을 리디렉션할 URL을 포함합니다. |
체크아웃 세부정보 데이터
checkout.breakdown 이벤트는 다음 데이터를 제공합니다:
체크아웃 상태 이벤트 데이터
manualRedirect이 활성화되면 다음 데이터를 포함한 checkout.status 이벤트를 수신합니다:
체크아웃 리디렉션 요청 이벤트 데이터
manualRedirect이 활성화되면 다음 데이터를 포함한 checkout.redirect_requested 이벤트를 수신합니다:
이벤트 이해하기
checkout.breakdown 이벤트는 애플리케이션의 UI를 Dodo Payments 결제 상태와 동기화하는 주요 수단입니다.
발생 시점:
- 초기화 시: 체크아웃 프레임이 로드되고 준비된 직후.
- 주소 변경 시: 고객이 세금 재계산을 초래하는 국가를 선택하거나 우편번호를 입력할 때마다.
| 필드 | 설명 |
|---|---|
subTotal | 세금이나 할인이 적용되기 전 세션의 전체 품목 합계입니다. |
discount | 적용된 모든 할인 금액의 총합입니다. |
tax | 계산된 세금 금액입니다. inline 모드에서는 사용자가 주소 필드를 조작할 때 실시간으로 업데이트됩니다. |
total | 세션의 기준 통화로 계산한 표준 가격 결과입니다. |
currency | 표준 소계, 할인 및 세금 값에 대한 ISO 통화 코드(예: "USD")입니다. |
finalTotal | 고객에게 실제 청구되는 금액입니다. 기본 가격 구성에 포함되지 않는 환율 조정이나 지역 결제 수수료가 포함될 수 있습니다. |
finalTotalCurrency | 고객이 실제로 결제하는 통화입니다. 구매력 평가지수나 지역 통화 변환이 활성화되어 있으면 currency와 다를 수 있습니다. |
- 통화 형식화: 가격은 항상 가장 작은 통화 단위(예: USD의 센트, JPY의 엔)로 정수로 반환됩니다. 표시하려면 100(또는 해당 단위의 10의 거듭제곱)으로 나누거나
Intl.NumberFormat와 같은 형식화 라이브러리를 사용하세요. - 초기 상태 처리: 체크아웃이 처음 로드되면
tax및discount는0또는null일 수 있으며, 사용자가 청구 정보를 제공하거나 코드를 적용할 때까지 이런 상태가 유지됩니다. UI에서는 이러한 상태를 정상적으로 처리해야 합니다(예: 대시—를 표시하거나 행을 숨김). - “최종 총계” 대 “총계”:
total는 표준 가격 계산을 제공하지만,finalTotal가 거래의 진실된 값입니다.finalTotal가 있으면 동적 조정 사항까지 포함하여 고객 카드에 실제로 청구되는 금액을 정확히 반영합니다. - 실시간 피드백:
tax필드를 사용하여 세금이 실시간으로 계산되고 있음을 사용자에게 보여주면 “실시간” 느낌을 제공하여 주소 입력 단계에서 마찰을 줄일 수 있습니다.
구현 옵션
패키지 관리자 설치
npm, yarn 또는 pnpm을 통해 단계별 통합 가이드와 같이 설치합니다.CDN 구현
빌드 단계 없이 빠른 통합을 위해 CDN을 사용할 수 있습니다:결제 수단 업데이트
인라인 체크아웃은 구독에 대한 결제 수단 업데이트를 지원합니다. 고객이 활성 구독 또는 보류 중인 구독을 다시 활성화하기 위해 결제 수단을 변경해야 하는 경우, 업데이트 흐름을 페이지 레이아웃 내에서 직접 렌더링할 수 있습니다.작동 원리
- Update Payment Method API를 호출하여
payment_link을 받습니다:
- 반환된
payment_link을checkoutUrl으로 전달하여 인라인 체크아웃을 엽니다:
보류 중인 구독의 경우
on_hold 상태의 구독에 대해 결제 수단을 업데이트하면 Dodo Payments는 남은 금액에 대해 자동으로 과금을 생성합니다. payment.succeeded 및 subscription.active 웹훅을 모니터링하여 다시 활성화 여부를 확인하세요.
오류 처리
SDK는 이벤트 시스템을 통해 상세한 오류 정보를 제공합니다. 항상onEvent 콜백에서 적절한 오류 처리를 구현하세요:
모범 사례
- 반응형 디자인: 컨테이너 요소에 충분한 너비와 높이를 확보하세요. iframe은 일반적으로 컨테이너를 채우도록 확장됩니다.
- 동기화:
checkout.breakdown이벤트를 사용하여 사용자 맞춤 주문 요약 또는 가격표를 체크아웃 프레임에서 보는 내용과 일치시키세요. - 스켈레톤 상태:
checkout.opened이벤트가 발생할 때까지 컨테이너에 로딩 표시기를 표시하세요. - 정리: 컴포넌트가 언마운트될 때
DodoPayments.Checkout.close()를 호출하여 iframe과 이벤트 리스너를 정리하세요.
다크 모드 구현의 경우, 인라인 체크아웃 프레임과 시각적으로 최적의 통합을 위해 백그라운드 색상으로
#0d0d0d를 사용하는 것이 좋습니다.결제 상태 검증
서버 측 검증이 중요한 이유
checkout.status과 같은 인라인 체크아웃 이벤트는 실시간 피드백을 제공하지만, 결제 상태의 유일한 진실원이 되어서는 안 됩니다. 네트워크 문제, 브라우저 충돌 또는 사용자가 페이지를 닫는 등의 상황에서 이벤트를 놓칠 수 있습니다. 신뢰할 수 있는 결제 검증을 위해 다음을 수행하세요:
- 서버가 웹훅 이벤트를 수신해야 합니다 - Dodo Payments는 결제 상태 변경에 대해 웹훅을 전송합니다.
- 폴링 메커니즘 구현 - 프런트엔드는 서버에 결제 상태 업데이트를 폴링해야 합니다.
- 두 가지 접근 방식 결합 - 웹훅을 주요 소스로 사용하고 폴링을 폴백으로 사용하세요.
추천 아키텍처
구현 단계
1. 체크아웃 이벤트 수신 - 사용자가 결제 버튼을 클릭하면 상태 확인을 준비하세요:payment.succeeded 또는 payment.failed 웹훅을 보낼 때 데이터베이스를 업데이트하세요. 자세한 내용은 Webhooks documentation를 확인하세요.
리디렉션 처리 (3DS, Google Pay, UPI)
manualRedirect: true을 사용할 때 특정 결제 수단은 인증을 위해 사용자를 페이지에서 벗어나게 하는 리디렉션이 필요합니다:
- 3D Secure (3DS) - 카드 인증
- Google Pay - 일부 플로우에서 지갑 인증
- UPI - 인도 결제 수단 리디렉션
checkout.redirect_requested 이벤트를 받습니다. 제공된 URL로 사용자를 리디렉션하세요:
- 사용자가 리디렉션에서 돌아왔는지 확인하세요 (예:
sessionStorage를 통해). - 서버에서 확정된 결제 상태를 폴링하기 시작하세요.
- 폴링하는 동안 “결제 확인 중…” 상태를 표시하세요.
- 서버에서 확인된 상태를 기반으로 성공/실패 UI를 표시하세요.
문제 해결
Checkout frame is not appearing
Checkout frame is not appearing
elementId이 실제 DOM에 존재하는div의id과 일치하는지 확인하세요.displayType: 'inline'이Initialize에 전달되었는지 확인하세요.checkoutUrl이 유효한지 확인하세요.
Taxes are not updating in my UI
Taxes are not updating in my UI
checkout.breakdown이벤트를 수신하는지 확인하세요.- 세금은 사용자가 체크아웃 프레임에서 유효한 국가 및 우편번호를 입력한 후에만 계산됩니다.
디지털 지갑 활성화
Apple Pay, Google Pay 및 기타 디지털 지갑 설정에 관한 자세한 내용은 Digital Wallets 페이지를 참조하세요.Apple Pay 빠른 설정
Download domain association file
Apple Pay 도메인 연결 파일을 다운로드하세요.
Request activation
운영 도메인 URL과 함께 support@dodopayments.com으로 이메일을 보내 Apple Pay 활성화를 요청하세요.
브라우저 지원
Dodo Payments Checkout SDK는 다음 브라우저를 지원합니다:- Chrome (최신)
- Firefox (최신)
- Safari (최신)
- Edge (최신)
- IE11+
인라인과 오버레이 체크아웃 비교
사용 사례에 적합한 체크아웃 유형을 선택하세요:| 기능 | 인라인 체크아웃 | 오버레이 체크아웃 |
|---|---|---|
| 통합 깊이 | 페이지에 완전히 내장됨 | 페이지 위에 모달 형식 |
| 레이아웃 제어 | 완전 제어 | 제한적 |
| 브랜딩 | 원활함 | 페이지와 분리됨 |
| 구현 노력 | 더 높음 | 더 낮음 |
| 가장 적합한 곳 | 맞춤 체크아웃 페이지, 높은 전환 흐름 | 빠른 통합, 기존 페이지 |
관련 자료
Overlay Checkout
빠른 모달 기반 통합을 위해 오버레이 체크아웃을 사용하세요.
Checkout Sessions API
체크아웃 경험을 지원하기 위해 체크아웃 세션을 생성하세요.
Webhooks
웹훅으로 서버 측에서 결제 이벤트를 처리하세요.
Integration Guide
Dodo Payments 통합에 관한 완전한 가이드.
