오버레이 체크아웃

오버레이 checkout은 페이지 위에 모달 창을 엽니다. 고객은 모달에서 결제 정보를 입력하고 페이지는 뒤에 계속 표시됩니다. 고객이 모달을 닫으면 페이지로 제어권이 돌아갑니다. 결제를 완료하면 return_url로 리디렉션됩니다.

Interactive Demo

실시간 데모에서 오버레이 checkout이 작동하는 모습을 확인하세요.

빠른 시작

SDK를 설치하고 초기화한 다음, create checkout session API의 checkout URL을 사용해 checkout을 엽니다:

import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

DodoPayments.Checkout.open({
  checkoutUrl: "https://test.checkout.dodopayments.com/session/cks_123"
});

단계별 통합

Install the SDK

npm, yarn 또는 pnpm을 통해 설치합니다:

npm install dodopayments-checkout

yarn add dodopayments-checkout

pnpm add dodopayments-checkout

Initialize the SDK

앱이 로드될 때 Initialize를 한 번 호출합니다. 일반적으로 기본 컴포넌트 또는 앱 진입점에서 호출합니다:

import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test", // Change to 'live' for production
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
    
    switch (event.event_type) {
      case "checkout.opened":
        // Modal has opened
        break;
      case "checkout.closed":
        // Modal has closed
        break;
      case "checkout.error":
        console.error("Checkout error:", event.data?.message);
        break;
    }
  },
});

checkout을 열기 전에 항상 SDK를 초기화해야 합니다. 애플리케이션이 로드될 때 한 번 초기화하고, 매번 checkout을 시도하기 전에 초기화하지 마세요.

Create a Checkout Button

checkout 모달을 여는 컴포넌트를 작성합니다:

// components/CheckoutButton.tsx
"use client";

import { Button } from "@/components/ui/button";
import { DodoPayments } from "dodopayments-checkout";
import { useEffect, useState } from "react";

export function CheckoutButton() {
  const [isLoading, setIsLoading] = useState(false);

  useEffect(() => {
    DodoPayments.Initialize({
      mode: "test",
      displayType: "overlay",
      onEvent: (event) => {
        if (event.event_type === "checkout.opened") {
          setIsLoading(false);
        }
        if (event.event_type === "checkout.error") {
          setIsLoading(false);
          console.error("Checkout error:", event.data?.message);
        }
      },
    });
  }, []);

  const handleCheckout = async () => {
    setIsLoading(true);
    try {
      await DodoPayments.Checkout.open({
        checkoutUrl: "https://test.checkout.dodopayments.com/session/cks_123"
      });
    } catch (error) {
      console.error("Failed to open checkout:", error);
      setIsLoading(false);
    }
  };

  return (
    <Button 
      onClick={handleCheckout}
      disabled={isLoading}
    >
      {isLoading ? "Loading..." : "Checkout Now"}
    </Button>
  );
}

Add the Button to Your Page

애플리케이션에서 checkout 버튼 컴포넌트를 사용합니다:

// app/page.tsx
import { CheckoutButton } from "@/components/CheckoutButton";

export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-center p-24">
      <h1>Welcome to Our Store</h1>
      <CheckoutButton />
    </main>
  );
}

Handle Redirects

결제 후 checkout 리디렉션을 처리할 페이지를 생성합니다:

// app/success/page.tsx
export default function SuccessPage() {
  return (
    <div className="flex min-h-screen flex-col items-center justify-center">
      <h1>Payment Successful</h1>
      <p>Thank you for your purchase.</p>
    </div>
  );
}

// app/failure/page.tsx
export default function FailurePage() {
  return (
    <div className="flex min-h-screen flex-col items-center justify-center">
      <h1>Payment Failed</h1>
      <p>Please try again or contact support.</p>
    </div>
  );
}

Test Your Integration

개발 서버를 시작합니다:

npm run dev

checkout 흐름을 테스트합니다:
- checkout 버튼을 클릭합니다
- 모달이 표시되는지 확인합니다
- 테스트 자격 증명을 사용해 결제 흐름을 테스트합니다
- 리디렉션이 올바르게 작동하는지 확인합니다

브라우저 콘솔에 checkout 이벤트가 기록되는 것을 확인할 수 있습니다.

Go Live

프로덕션을 사용할 준비가 되면 다음을 수행합니다:

모드를 'live'로 변경합니다:

DodoPayments.Initialize({
  mode: "live",
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  }
});

checkout URL을 백엔드의 live checkout session을 사용하도록 업데이트합니다
프로덕션에서 전체 흐름을 테스트합니다
이벤트와 오류를 모니터링합니다

API 레퍼런스

초기화

SDK를 설정하려면 Initialize를 한 번 호출합니다:

interface InitializeOptions {
  mode: "test" | "live";
  displayType?: "overlay" | "inline";
  onEvent: (event: CheckoutEvent) => void;
}

DodoPayments.Initialize(options);

옵션	유형	필수	설명
`mode`	`"test" \| "live"`	예	환경 모드: 개발 환경에서는 `"test"`, 프로덕션에서는 `"live"`
`displayType`	`"overlay" \| "inline"`	아니요	표시 유형: 모달 checkout에는 `"overlay"`(기본값), 임베디드 checkout에는 `"inline"`
`onEvent`	`function`	예	checkout 이벤트를 처리하는 Callback function

Checkout 열기

checkout 모달을 엽니다:

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
    themeConfig?: ThemeConfig;
    payButtonText?: string;
    fontSize?: FontSize;
    fontWeight?: FontWeight;
  };
}

DodoPayments.Checkout.open(options);

옵션	유형	필수	설명
`checkoutUrl`	`string`	예	create checkout session API의 checkout session URL
`options.showTimer`	`boolean`	아니요	session timer를 표시하거나 숨깁니다. 기본값은 `true`입니다. 비활성화하면 session이 만료될 때 `checkout.link_expired` 이벤트를 수신합니다.
`options.showSecurityBadge`	`boolean`	아니요	security badge를 표시하거나 숨깁니다. 기본값은 `true`입니다
`options.manualRedirect`	`boolean`	아니요	`true`인 경우 자동 리디렉션을 방지합니다. Checkout은 결제 결과와 함께 `checkout.status`를, 열 URL과 함께 `checkout.redirect_requested`를 내보내며 탐색은 사용자가 처리합니다
`options.themeConfig`	`ThemeConfig`	아니요	사용 중단 예정입니다. 대신 checkout session을 생성할 때 서버 측에서 theme을 구성합니다
`options.payButtonText`	`string`	아니요	pay button의 사용자 지정 텍스트
`options.fontSize`	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"`	아니요	checkout의 전역 글꼴 크기
`options.fontWeight`	`"normal" \| "medium" \| "bold" \| "extraBold"`	아니요	checkout의 전역 글꼴 두께

Checkout 닫기

프로그래밍 방식으로 모달을 닫습니다:

DodoPayments.Checkout.close();

상태 확인

현재 모달이 열려 있는지 확인합니다:

const isOpen = DodoPayments.Checkout.isOpen();
// Returns: boolean

이벤트

Initialize에 전달한 onEvent callback을 통해 checkout 이벤트를 수신합니다:

DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Modal has opened
        break;
      case "checkout.form_ready":
        // Form is ready for user input
        break;
      case "checkout.payment_page_opened":
        // Payment page is displayed
        break;
      case "checkout.customer_details_submitted":
        // Customer details submitted
        break;
      case "checkout.closed":
        // Modal has closed
        break;
      case "checkout.redirect":
        // Checkout will redirect
        break;
      case "checkout.error":
        console.error("Error:", event.data?.message);
        break;
      case "checkout.link_expired":
        // Session expired (only when showTimer is false)
        break;
    }
  }
});

이벤트	설명
`checkout.opened`	모달이 열렸습니다
`checkout.form_ready`	사용자의 입력을 받을 폼이 준비되었습니다. 로딩 상태를 숨길 때 사용합니다
`checkout.payment_page_opened`	결제 페이지가 표시되었습니다
`checkout.customer_details_submitted`	고객 및 청구 정보가 제출되었습니다
`checkout.closed`	모달이 닫혔습니다
`checkout.redirect`	Checkout이 리디렉션됩니다(예: 은행 페이지로)
`checkout.error`	checkout 중 오류가 발생했습니다
`checkout.link_expired`	checkout session이 만료되었습니다. `showTimer`가 `false`로 설정된 경우에만 수신됩니다.

CDN 구현

빌드 단계 없이 빠르게 통합하려면 CDN에서 SDK를 로드합니다:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Dodo Payments Checkout</title>
  
  <script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
  <script>
    DodoPaymentsCheckout.DodoPayments.Initialize({
      mode: "test",
      displayType: "overlay",
      onEvent: (event) => {
        console.log('Checkout event:', event);
      }
    });
  </script>
</head>
<body>
  <button onclick="openCheckout()">Checkout Now</button>

  <script>
    function openCheckout() {
      DodoPaymentsCheckout.DodoPayments.Checkout.open({
        checkoutUrl: "https://test.checkout.dodopayments.com/session/cks_123"
      });
    }
  </script>
</body>
</html>

Theme 사용자 지정

클라이언트 측 themeConfig 옵션은 사용 중단 예정이며 다음 메이저 버전의 Checkout SDK(v2.0.0)에서 제거됩니다. 이 옵션을 전달하면 브라우저 콘솔에 사용 중단 경고가 기록됩니다. 대신 customization.theme_config parameter를 사용해 API를 통해 checkout session을 생성할 때 theme을 구성하세요. 자세한 내용은 Checkout Theme Customization을 참조하거나 대시보드의 Design page에서 시각적으로 구성할 수 있습니다. Session에서 구성한 theme은 overlay, inline, hosted checkout 모두에 적용됩니다.

이 섹션에서는 Checkout SDK를 사용하는 더 이상 권장되지 않는 클라이언트 측 theme 구성을 다룹니다. 권장되는 방법은 theme_config parameter를 사용해 API를 통해 checkout session을 생성할 때 서버 측에서 theme을 구성하는 것입니다. API 수준의 구성은 Checkout Theme Customization을 참조하거나, 대시보드의 Design page에서 실시간 미리보기와 함께 시각적으로 theme을 구성할 수 있습니다.

클라이언트 측 theme 구성을 사용해야 한다면 options parameter에 themeConfig를 전달합니다:

DodoPayments.Checkout.open({
  checkoutUrl: "https://test.checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#344054",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});

Theme 속성

light 및 dark 모드에서 사용할 수 있는 모든 theme 속성입니다:

interface ThemeConfig {
  light?: {
    bgPrimary?: string;              // Primary background
    bgSecondary?: string;            // Secondary background (tabs, etc.)
    borderPrimary?: string;          // Primary border
    borderSecondary?: string;        // Secondary border
    textPrimary?: string;            // Primary text
    textSecondary?: string;          // Secondary text
    textPlaceholder?: string;        // Placeholder text
    textError?: string;              // Error text
    textSuccess?: string;            // Success text
    buttonPrimary?: string;          // Primary button background
    buttonPrimaryHover?: string;     // Primary button hover
    buttonTextPrimary?: string;      // Primary button text
    buttonSecondary?: string;        // Secondary button background
    buttonSecondaryHover?: string;   // Secondary button hover
    buttonTextSecondary?: string;    // Secondary button text
    inputFocusBorder?: string;       // Input focus border
  };
  dark?: {
    // Same properties as light mode
  };
  radius?: string;                   // Border radius (e.g., "8px")
}

오류 처리

항상 onEvent callback에서 오류 처리를 구현합니다:

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Show user-friendly error message
      // Optionally retry the checkout
    }
    if (event.event_type === "checkout.link_expired") {
      console.warn("Checkout session has expired");
      // Create a new checkout session and try again
    }
  }
});

오류가 발생했을 때 원활한 사용자 경험을 제공하려면 항상 checkout.error 이벤트를 처리해야 합니다.

모범 사례

한 번만 초기화: 앱이 로드될 때 Initialize를 한 번 호출하고, 매번 checkout 전에 호출하지 않습니다
오류 처리: 이벤트 callback에 적절한 오류 처리를 구현합니다
Test mode: 개발 중에는 "test" 모드를 사용하고, 프로덕션 준비가 되었을 때만 "live"로 전환합니다
이벤트 처리: 완전한 사용자 경험을 위해 관련된 모든 이벤트를 처리합니다
유효한 URL: 항상 create checkout session API에서 가져온 유효한 checkout URL을 사용합니다
TypeScript: 더 나은 type safety와 개발자 경험을 위해 TypeScript를 사용합니다
로딩 상태: UX를 개선하려면 checkout이 열리는 동안 로딩 상태를 표시합니다
Timer 관리: session 만료를 수동으로 처리하려면 timer(showTimer: false)를 비활성화합니다

문제 해결

Events not firing

가능한 원인:

이벤트 핸들러가 올바르게 설정되지 않음
이벤트 전파를 방해하는 JavaScript 오류
SDK가 올바르게 초기화되지 않음

해결 방법:

Initialize()에서 이벤트 핸들러가 올바르게 구성되었는지 확인합니다
브라우저 콘솔에서 JavaScript 오류를 확인합니다
SDK 초기화가 성공적으로 완료되었는지 확인합니다
먼저 간단한 이벤트 핸들러로 테스트합니다

Styling issues

가능한 원인:

애플리케이션 스타일과 CSS 충돌
Theme 설정이 올바르게 적용되지 않음
반응형 디자인 문제

해결 방법:

브라우저 DevTools에서 CSS 충돌을 확인합니다
Theme 설정이 올바른지 확인합니다
다양한 화면 크기에서 테스트합니다
모달과 z-index 충돌이 없는지 확인합니다

Digital Wallets

Google Pay 및 기타 digital wallets 설정에 대한 자세한 내용은 Digital Wallets 페이지를 참조하세요.

Apple Pay는 아직 오버레이 checkout에서 지원되지 않습니다.

브라우저 지원

Dodo Payments Checkout SDK는 다음을 지원합니다:

Chrome(최신 버전)
Firefox(최신 버전)
Safari(최신 버전)
Edge(최신 버전)
IE11 이상

오버레이 checkout과 Inline checkout 비교

사용 사례에 적합한 checkout 유형을 선택하세요:

기능	오버레이	Inline
통합 수준	페이지 위의 모달	페이지에 완전히 임베드됨
레이아웃 제어	제한적	완전한 제어
브랜딩	페이지와 별도	페이지와 일치
구현 작업량	적음	많음
적합한 용도	빠른 통합, 기존 페이지	사용자 지정 checkout 페이지, 높은 전환율의 흐름

기존 페이지를 최소한으로 변경하면서 더 빠르게 통합하려면 오버레이 checkout을 사용하세요. checkout 경험을 최대한 제어하고 일관된 브랜딩을 적용하려면 inline checkout을 사용하세요.

Inline Checkout

완전히 통합된 경험을 위해 checkout을 페이지에 직접 임베드합니다.

Checkout Sessions API

checkout 경험을 구현할 checkout session을 생성합니다.

Webhooks

webhook을 사용해 서버 측에서 결제 이벤트를 처리합니다.

Integration Guide

Dodo Payments 통합에 대한 전체 가이드입니다.

추가 도움이 필요하면 Discord 커뮤니티를 방문하거나 개발자 지원팀에 문의하세요.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Interactive Demo

빠른 시작

단계별 통합

API 레퍼런스

초기화

Checkout 열기

Checkout 닫기

상태 확인

이벤트

CDN 구현

Theme 사용자 지정

Theme 속성

오류 처리

모범 사례

문제 해결

Digital Wallets

브라우저 지원

오버레이 checkout과 Inline checkout 비교

관련 리소스

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Interactive Demo

​빠른 시작

​단계별 통합

​API 레퍼런스

​초기화

​Checkout 열기

​Checkout 닫기

​상태 확인

​이벤트

​CDN 구현

​Theme 사용자 지정

​Theme 속성

​오류 처리

​모범 사례

​문제 해결

​Digital Wallets

​브라우저 지원

​오버레이 checkout과 Inline checkout 비교

​관련 리소스

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

빠른 시작

단계별 통합

API 레퍼런스

초기화

Checkout 열기

Checkout 닫기

상태 확인

이벤트

CDN 구현

Theme 사용자 지정

Theme 속성

오류 처리

모범 사례

문제 해결

Digital Wallets

브라우저 지원

오버레이 checkout과 Inline checkout 비교

관련 리소스