오버레이 체크아웃

개요

Dodo Payments Checkout SDK는 웹 애플리케이션에 결제 오버레이를 통합하는 매끄러운 방법을 제공합니다. TypeScript와 현대 웹 표준으로 구축되어 있으며, 실시간 이벤트 처리 및 사용자 정의 가능한 테마를 통해 결제를 처리하는 강력한 솔루션을 제공합니다.

데모

Interactive Demo

실시간 데모에서 오버레이 체크아웃을 직접 확인하세요.

빠른 시작

Dodo Payments Checkout SDK를 몇 줄의 코드로 시작하세요:

import { DodoPayments } from "dodopayments-checkout";

// Initialize the SDK
DodoPayments.Initialize({
  mode: "test", // 'test' or 'live'
  displayType: "overlay", // Optional: defaults to 'overlay' for overlay checkout
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

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

체크아웃 URL은 create checkout session API에서 가져오세요.

단계별 통합 가이드

Install the SDK

선호하는 패키지 관리자를 사용하여 Dodo Payments Checkout SDK를 설치하세요:

npm install dodopayments-checkout

yarn add dodopayments-checkout

pnpm add dodopayments-checkout

Initialize the SDK

주로 메인 컴포넌트나 앱 진입점에서 애플리케이션 내에서 SDK를 초기화하세요:

import { DodoPayments } from "dodopayments-checkout";

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

체크아웃을 열기 전에 SDK를 항상 초기화하세요. 초기화는 애플리케이션이 로드될 때 한 번만 수행되어야 합니다.

Create a Checkout Button Component

체크아웃 오버레이를 여는 컴포넌트를 생성하세요:

// 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(() => {
    // Initialize the SDK
    DodoPayments.Initialize({
      mode: "test",
      displayType: "overlay",
      onEvent: (event) => {
        switch (event.event_type) {
          case "checkout.opened":
            setIsLoading(false);
            break;
          case "checkout.error":
            setIsLoading(false);
            console.error("Checkout error:", event.data?.message);
            break;
        }
      },
    });
  }, []);

  const handleCheckout = async () => {
    try {
      setIsLoading(true);
      await DodoPayments.Checkout.open({
        checkoutUrl: "https://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 Checkout to Your Page

애플리케이션에서 체크아웃 버튼 컴포넌트를 사용하세요:

// 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 Success and Failure Pages

체크아웃 리디렉션을 처리할 페이지를 생성하세요:

// 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

체크아웃 흐름을 테스트하세요:
- 체크아웃 버튼 클릭
- 오버레이가 나타나는지 확인
- 테스트 자격 증명을 사용하여 결제 흐름 테스트
- 리디렉션이 올바르게 작동하는지 확인

브라우저 콘솔에서 체크아웃 이벤트 로그를 확인할 수 있어야 합니다.

Go Live

프로덕션 준비가 되었을 때:

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

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

백엔드에서 라이브 체크아웃 세션을 사용하도록 체크아웃 URL을 업데이트하세요.
프로덕션에서 전체 흐름을 테스트하세요.
이벤트 및 오류를 모니터링하세요.

API 참조

구성

초기화 옵션

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

옵션	타입	필수	설명
`mode`	`"test" \| "live"`	예	환경 모드: 개발 시 `'test'`, 프로덕션 시 `'live'`
`displayType`	`"overlay" \| "inline"`	아니요	표시 유형: 기본값인 모달 체크아웃은 `'overlay'`, 임베디드 체크아웃은 `'inline'`
`onEvent`	`function`	예	체크아웃 이벤트 처리를 위한 콜백 함수

체크아웃 옵션

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
  };
}

옵션	타입	필수	설명
`checkoutUrl`	`string`	예	create checkout session API에서 가져온 체크아웃 세션 URL
`options.showTimer`	`boolean`	아니요	체크아웃 타이머 표시 여부. 기본값은 `true`입니다. 비활성화 시 세션 만료 시 `checkout.link_expired` 이벤트를 수신합니다.
`options.showSecurityBadge`	`boolean`	아니요	보안 배지 표시 여부. 기본값은 `true`입니다.
`options.manualRedirect`	`boolean`	아니요	활성화하면 체크아웃 완료 후 자동 리디렉션이 수행되지 않습니다. 대신 리디렉션을 직접 처리할 수 있도록 `checkout.status` 및 `checkout.redirect_requested` 이벤트가 발생합니다.

메서드

체크아웃 열기

지정된 체크아웃 세션 URL로 체크아웃 오버레이를 엽니다.

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

체크아웃 동작을 사용자 정의하기 위해 추가 옵션을 전달할 수도 있습니다:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    showTimer: false,
    showSecurityBadge: false,
    manualRedirect: true,
  },
});

manualRedirect를 사용하는 경우 onEvent 콜백에서 체크아웃 완료를 처리하세요:

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event) => {
    if (event.event_type === "checkout.status") {
      const status = event.data?.message?.status;
      // Handle status: "succeeded", "failed", or "processing"
    }
    if (event.event_type === "checkout.redirect_requested") {
      const redirectUrl = event.data?.message?.redirect_to;
      // Redirect the customer manually
      window.location.href = redirectUrl;
    }
    if (event.event_type === "checkout.link_expired") {
      // Handle expired checkout session
    }
  },
});

체크아웃 닫기

프로그램적으로 체크아웃 오버레이를 닫습니다.

DodoPayments.Checkout.close();

상태 확인

현재 체크아웃 오버레이가 열려 있는지 여부를 반환합니다.

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

이벤트

SDK는 onEvent 콜백을 통해 수신할 수 있는 실시간 이벤트를 제공합니다:

체크아웃 상태 이벤트 데이터

manualRedirect가 활성화되면 다음 데이터를 포함한 checkout.status 이벤트를 수신합니다:

interface CheckoutStatusEventData {
  message: {
    status?: "succeeded" | "failed" | "processing";
  };
}

체크아웃 리디렉션 요청 이벤트 데이터

manualRedirect가 활성화되면 다음 데이터를 포함한 checkout.redirect_requested 이벤트를 수신합니다:

interface CheckoutRedirectRequestedEventData {
  message: {
    redirect_to?: string;
  };
}

DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Checkout overlay has been opened
        break;
      case "checkout.form_ready":
        // Checkout form is ready for user input
        break;
      case "checkout.payment_page_opened":
        // Payment page has been displayed
        break;
      case "checkout.customer_details_submitted":
        // Customer and billing details submitted
        break;
      case "checkout.closed":
        // Checkout has been closed
        break;
      case "checkout.redirect":
        // Checkout will perform a redirect
        break;
      case "checkout.error":
        // An error occurred
        console.error("Error:", event.data?.message);
        break;
      case "checkout.link_expired":
        // Checkout session has expired (only when showTimer is false)
        break;
      case "checkout.status":
        // Checkout status update (only when manualRedirect is enabled)
        const status = event.data?.message?.status;
        break;
      case "checkout.redirect_requested":
        // Redirect requested (only when manualRedirect is enabled)
        const redirectUrl = event.data?.message?.redirect_to;
        break;
    }
  }
});

이벤트 유형	설명
`checkout.opened`	체크아웃 오버레이가 열렸습니다
`checkout.form_ready`	체크아웃 양식이 사용자 입력을 받을 준비가 되었습니다. 로딩 상태를 숨길 때 유용합니다.
`checkout.payment_page_opened`	결제 페이지가 표시되었습니다
`checkout.customer_details_submitted`	고객 및 청구 정보가 제출되었습니다
`checkout.closed`	체크아웃 오버레이가 닫혔습니다
`checkout.redirect`	체크아웃이 리디렉션을 수행할 예정입니다
`checkout.error`	체크아웃 중 오류가 발생했습니다
`checkout.link_expired`	체크아웃 세션이 만료될 때 발생합니다. `showTimer`가 `false`로 설정된 경우에만 수신됩니다.
`checkout.status`	`manualRedirect`이 활성화되면 발생합니다. 체크아웃 상태(`succeeded`, `failed` 또는 `processing`)를 포함합니다.
`checkout.redirect_requested`	`manualRedirect`이 활성화되면 발생합니다. 고객을 리디렉션할 URL을 포함합니다.

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

이 섹션에서는 Checkout SDK를 사용한 client-side theme 구성 중 deprecated된 방식을 설명합니다. 권장되는 방법은 API를 통해 checkout session을 생성할 때 theme_config parameter를 사용하여 server-side에서 theme을 구성하는 것입니다. API 수준의 구성은 Checkout Theme Customization을 참조하거나, dashboard의 Design page에서 실시간 미리보기와 함께 시각적으로 theme을 구성할 수 있습니다.

기본 Theme 구성

DodoPayments.Checkout.open({
  checkoutUrl: "https://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 구성

사용 가능한 모든 theme properties:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        // Background colors
        bgPrimary: "#FFFFFF",        // Primary background color
        bgSecondary: "#F9FAFB",      // Secondary background color (e.g., tabs)
        
        // Border colors
        borderPrimary: "#D0D5DD",     // Primary border color
        borderSecondary: "#6B7280",  // Secondary border color
        
        // Text colors
        textPrimary: "#344054",       // Primary text color
        textSecondary: "#6B7280",    // Secondary text color
        textPlaceholder: "#667085",  // Placeholder text color
        textError: "#D92D20",        // Error text color
        textSuccess: "#10B981",      // Success text color
        
        // Button colors
        buttonPrimary: "#A6E500",           // Primary button background
        buttonPrimaryHover: "#8CC500",      // Primary button hover state
        buttonTextPrimary: "#0D0D0D",       // Primary button text color
        buttonSecondary: "#F3F4F6",         // Secondary button background
        buttonSecondaryHover: "#E5E7EB",     // Secondary button hover state
        buttonTextSecondary: "#344054",     // Secondary button text color
      },
      dark: {
        // Background colors
        bgPrimary: "#0D0D0D",
        bgSecondary: "#1A1A1A",
        
        // Border colors
        borderPrimary: "#323232",
        borderSecondary: "#D1D5DB",
        
        // Text colors
        textPrimary: "#FFFFFF",
        textSecondary: "#909090",
        textPlaceholder: "#9CA3AF",
        textError: "#F97066",
        textSuccess: "#34D399",
        
        // Button colors
        buttonPrimary: "#A6E500",
        buttonPrimaryHover: "#8CC500",
        buttonTextPrimary: "#0D0D0D",
        buttonSecondary: "#2A2A2A",
        buttonSecondaryHover: "#3A3A3A",
        buttonTextSecondary: "#FFFFFF",
      },
      radius: "8px", // Border radius for inputs, buttons, and tabs
    },
  },
});

Light Mode 전용

light theme만 사용자 지정하려는 경우:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#000000",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

Dark Mode 전용

dark theme만 사용자 지정하려는 경우:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      dark: {
        bgPrimary: "#000000",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

부분 Theme 재정의

특정 properties만 재정의할 수 있습니다. 지정하지 않은 properties에는 checkout의 기본값이 사용됩니다:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        buttonPrimary: "#FF6B6B", // Only override primary button color
      },
      radius: "16px", // Override border radius
    },
  },
});

다른 옵션과 함께 사용하는 Theme 구성

theme 구성은 다른 checkout 옵션과 함께 사용할 수 있습니다:

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

TypeScript Types

TypeScript 사용자를 위해 모든 theme 구성 types가 export됩니다:

import { ThemeConfig, ThemeModeConfig } from "dodopayments-checkout";

const themeConfig: ThemeConfig = {
  light: {
    bgPrimary: "#FFFFFF",
    // ... other properties
  },
  dark: {
    bgPrimary: "#0D0D0D",
    // ... other properties
  },
  radius: "8px",
};

Error Handling

SDK는 event system을 통해 자세한 error 정보를 제공합니다. onEvent callback에는 항상 적절한 error handling을 구현하세요:

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Handle error appropriately
      // You may want to show a user-friendly error message
      // or retry the checkout process
    }
    if (event.event_type === "checkout.link_expired") {
      // Handle expired checkout session
      console.warn("Checkout session has expired");
    }
  }
});

오류가 발생했을 때 사용자에게 원활한 경험을 제공하려면 항상 checkout.error event를 처리하세요.

Best Practices

한 번만 초기화: 애플리케이션이 로드될 때 SDK를 한 번 초기화하고, checkout을 시도할 때마다 초기화하지 마세요
Error handling: event callback에 항상 적절한 error handling을 구현하세요
Test mode: 개발 중에는 test mode를 사용하고, production 준비가 완료된 경우에만 live로 전환하세요
Event handling: 완전한 사용자 경험을 위해 관련된 모든 event를 처리하세요
유효한 URL: create checkout session API에서 제공하는 유효한 checkout URL을 항상 사용하세요
TypeScript: 더 나은 type safety와 developer experience를 위해 TypeScript를 사용하세요
Loading states: checkout이 열리는 동안 loading states를 표시하여 UX를 개선하세요
Timer 관리: session 만료를 직접 처리하려면 timer(showTimer: false)를 비활성화하세요

Troubleshooting

Checkout not opening

가능한 원인:

open()를 호출하기 전에 SDK가 초기화되지 않음
유효하지 않은 checkout URL
콘솔의 JavaScript 오류
Network 연결 문제

해결 방법:

checkout을 열기 전에 SDK 초기화가 수행되는지 확인하세요
콘솔 오류를 확인하세요
checkout URL이 유효하고 create checkout session API에서 제공된 것인지 확인하세요
Network 연결을 확인하세요

Events not firing

가능한 원인:

Event handler가 올바르게 설정되지 않음
Event propagation을 방해하는 JavaScript 오류
SDK가 올바르게 초기화되지 않음

해결 방법:

Initialize()에서 event handler가 올바르게 구성되었는지 확인하세요
브라우저 콘솔에서 JavaScript 오류를 확인하세요
SDK 초기화가 성공적으로 완료되었는지 확인하세요
먼저 간단한 event handler로 테스트하세요

Styling issues

가능한 원인:

애플리케이션 styles와 CSS 충돌
Theme settings가 올바르게 적용되지 않음
Responsive design 문제

해결 방법:

브라우저 DevTools에서 CSS 충돌을 확인하세요
Theme settings가 올바른지 확인하세요
다양한 화면 크기에서 테스트하세요
overlay와 z-index 충돌이 없는지 확인하세요

Digital Wallet 활성화

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

Apple Pay는 아직 overlay checkout에서 지원되지 않습니다. Apple Pay 지원은 곧 제공될 예정입니다.

Browser Support

Dodo Payments Checkout SDK는 다음 브라우저를 지원합니다:

Chrome (최신 버전)
Firefox (최신 버전)
Safari (최신 버전)
Edge (최신 버전)
IE11+

Overlay vs Inline Checkout

사용 사례에 맞는 checkout type을 선택하세요:

Feature	Overlay Checkout	Inline Checkout
Integration depth	페이지 위에 표시되는 Modal	페이지에 완전히 embedded됨
Layout control	제한적	전체 제어
Branding	페이지와 별도	Seamless
Implementation effort	낮음	높음
Best for	빠른 integration, 기존 페이지	Custom checkout pages, high-conversion flows

기존 페이지를 최소한으로 변경하면서 빠르게 integration하려면 overlay checkout을 사용하세요. checkout experience를 최대한 제어하고 seamless branding을 구현하려면 inline checkout을 사용하세요.

Inline Checkout

완전히 통합된 experience를 위해 checkout을 페이지에 직접 embed하세요.

Checkout Sessions API

checkout experience를 구현할 checkout session을 생성하세요.

Webhooks

webhook을 사용하여 server-side에서 payment event를 처리하세요.

Integration Guide

Dodo Payments integration에 대한 전체 guide입니다.

추가 도움이 필요하면 Discord community를 방문하거나 developer support team에 문의하세요.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

개요

데모

Interactive Demo

빠른 시작

단계별 통합 가이드

API 참조

구성

초기화 옵션

체크아웃 옵션

메서드

체크아웃 열기

체크아웃 닫기

상태 확인

이벤트

체크아웃 상태 이벤트 데이터

체크아웃 리디렉션 요청 이벤트 데이터

기본 Theme 구성

전체 Theme 구성

Light Mode 전용

Dark Mode 전용

부분 Theme 재정의

다른 옵션과 함께 사용하는 Theme 구성

TypeScript Types

Error Handling

Best Practices

Troubleshooting

Digital Wallet 활성화

Browser Support

Overlay vs Inline Checkout

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

​개요

​데모

Interactive Demo

​빠른 시작

​단계별 통합 가이드

​API 참조

​구성

​초기화 옵션

​체크아웃 옵션

​메서드

​체크아웃 열기

​체크아웃 닫기

​상태 확인

​이벤트

​체크아웃 상태 이벤트 데이터

​체크아웃 리디렉션 요청 이벤트 데이터

​기본 Theme 구성

​전체 Theme 구성

​Light Mode 전용

​Dark Mode 전용

​부분 Theme 재정의

​다른 옵션과 함께 사용하는 Theme 구성

​TypeScript Types

​Error Handling

​Best Practices

​Troubleshooting

​Digital Wallet 활성화

​Browser Support

​Overlay vs Inline Checkout

​Related Resources

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

개요

데모

빠른 시작

단계별 통합 가이드

API 참조

구성

초기화 옵션

체크아웃 옵션

메서드

체크아웃 열기

체크아웃 닫기

상태 확인

이벤트

체크아웃 상태 이벤트 데이터

체크아웃 리디렉션 요청 이벤트 데이터

기본 Theme 구성

전체 Theme 구성

Light Mode 전용

Dark Mode 전용

부분 Theme 재정의

다른 옵션과 함께 사용하는 Theme 구성

TypeScript Types

Error Handling

Best Practices

Troubleshooting

Digital Wallet 활성화

Browser Support

Overlay vs Inline Checkout

Related Resources