메인 콘텐츠로 건너뛰기

개요

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

작동 방식

인라인 체크아웃은 웹사이트나 앱에 안전한 Dodo Payments 프레임을 임베드하여 작동합니다. 체크아웃 프레임은 고객 정보를 수집하고 결제 세부 정보를 캡처하는 역할을 합니다. 페이지는 항목 목록, 총액 및 체크아웃에서 변경할 수 있는 옵션을 표시합니다. SDK를 사용하면 페이지와 체크아웃 프레임이 상호작용할 수 있습니다. Dodo Payments는 체크아웃이 완료되면 자동으로 구독을 생성하여 프로비저닝할 준비를 합니다.
인라인 결제 프레임은 모든 민감한 결제 정보를 안전하게 처리하여, 귀사가 추가 인증 없이도 PCI 기준을 준수할 수 있도록 합니다.

좋은 인라인 체크아웃의 조건

고객이 누구에게서 구매하고 있는지, 무엇을 구매하고 있는지, 얼마를 지불하고 있는지 아는 것이 중요합니다. 준수 및 전환 최적화를 위한 인라인 체크아웃을 구축하려면 구현에 다음이 포함되어야 합니다:
Inline checkout example with required elements labeled
  1. 정기 정보: 정기적인 경우, 얼마나 자주 반복되는지 및 갱신 시 지불할 총액. 체험판인 경우, 체험판 기간.
  2. 항목 설명: 구매하는 항목에 대한 설명.
  3. 거래 총액: 거래 총액, 포함된 소계, 총 세금 및 총합. 통화도 포함해야 합니다.
  4. Dodo Payments 바닥글: Dodo Payments에 대한 정보, 판매 조건 및 개인정보 보호정책이 포함된 전체 인라인 체크아웃 프레임.
  5. 환불 정책: Dodo Payments의 표준 환불 정책과 다를 경우 환불 정책에 대한 링크.
인라인 결제 프레임 전체, 푸터를 포함한 모든 요소를 항상 표시하세요. 법적 정보를 제거하거나 숨기는 것은 준수 요구 사항을 위반합니다.

고객 여정

체크아웃 흐름은 체크아웃 세션 구성에 따라 결정됩니다. 체크아웃 세션을 구성하는 방식에 따라 고객은 모든 정보를 단일 페이지에서 또는 여러 단계에 걸쳐 제공받는 체크아웃을 경험하게 됩니다.
1

Customer opens checkout

아이템이나 기존 거래를 전달하여 인라인 체크아웃을 열 수 있습니다. SDK를 사용하여 페이지 정보를 표시하고 업데이트하며, 고객 상호작용에 따라 아이템을 업데이트하는 SDK 메서드를 사용하세요.아이템 목록과 결제 양식이 있는 초기 체크아웃 페이지
2

Customer enters their details

인라인 체크아웃은 먼저 고객에게 이메일 주소를 입력하고, 국가를 선택하며, (필요한 경우) 우편번호를 입력하도록 요청합니다. 이 단계에서는 세금 및 사용 가능한 결제 옵션을 결정하는 데 필요한 모든 정보를 수집합니다.고객 세부 정보를 미리 채우고 저장된 주소를 제시하여 경험을 간소화할 수 있습니다.
3

Customer selects payment method

세부 정보를 입력한 후 고객은 사용 가능한 결제 방법과 결제 양식을 제시받습니다. 옵션에는 신용 카드, 직불 카드, PayPal, Apple Pay, Google Pay 및 고객의 위치에 따라 다른 지역 결제 방법이 포함될 수 있습니다.가능한 경우 저장된 결제 방법을 표시하여 체크아웃 속도를 높입니다.사용 가능한 결제 방법 및 카드 세부 정보 양식
4

Checkout completed

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

Dodo Payments creates subscription

Dodo Payments는 고객을 위해 자동으로 구독을 생성하여 귀하가 프로비저닝할 준비를 합니다. 고객이 사용한 결제 방법은 갱신 또는 구독 변경을 위해 파일에 보관됩니다.웹훅 알림으로 생성된 구독

빠른 시작

몇 줄의 코드로 Dodo Payments 인라인 체크아웃을 시작하세요:
import { DodoPayments } from "dodopayments-checkout";

// Initialize the SDK for inline mode
DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

// Open checkout in a specific container
DodoPayments.Checkout.open({
  checkoutUrl: "https://test.dodopayments.com/session/cks_123",
  elementId: "dodo-inline-checkout" // ID of the container element
});
페이지에 해당 id가 있는 컨테이너 요소를 포함하고 있는지 확인하세요: <div id="dodo-inline-checkout"></div>.

단계별 통합 가이드

1

Install the SDK

Dodo Payments Checkout SDK를 설치하세요:
npm install dodopayments-checkout
2

Initialize the SDK for Inline Display

SDK를 초기화하고 displayType: 'inline'을 지정하세요. checkout.breakdown 이벤트를 청취하여 실시간 세금 및 총계 계산으로 UI를 업데이트하는 것도 권장합니다.
import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  onEvent: (event) => {
    if (event.event_type === "checkout.breakdown") {
      const breakdown = event.data?.message;
      // Update your UI with breakdown.subTotal, breakdown.tax, breakdown.total, etc.
    }
  },
});
3

Create a Container Element

체크아웃 프레임이 삽입될 HTML 요소를 추가하세요:
<div id="dodo-inline-checkout"></div>
4

Open the Checkout

checkoutUrl와 컨테이너의 elementId를 사용하여 DodoPayments.Checkout.open()을 호출하세요:
DodoPayments.Checkout.open({
  checkoutUrl: "https://test.dodopayments.com/session/cks_123",
  elementId: "dodo-inline-checkout"
});
5

Test Your Integration

  1. 개발 서버를 시작하세요:
npm run dev
  1. 체크아웃 흐름을 테스트하세요:
    • 인라인 프레임에 이메일 및 주소 세부 정보를 입력하세요.
    • 사용자 정의 주문 요약이 실시간으로 업데이트되는지 확인하세요.
    • 테스트 자격 증명을 사용하여 결제 흐름을 테스트하세요.
    • 리디렉션이 올바르게 작동하는지 확인하세요.
onEvent 콜백에 콘솔 로그를 추가한 경우, 브라우저 콘솔에 checkout.breakdown 이벤트가 기록되는 것을 확인할 수 있습니다.
6

Go Live

프로덕션 준비가 되었을 때:
  1. 모드를 'live'로 변경하세요:
DodoPayments.Initialize({
  mode: "live",
  displayType: "inline",
  onEvent: (event) => {
    // Handle events
  }
});
  1. 체크아웃 URL을 백엔드에서 라이브 체크아웃 세션을 사용하도록 업데이트하세요.
  2. 프로덕션에서 전체 흐름을 테스트하세요.

완전한 React 예제

이 예시는 인라인 결제와 함께 사용자 정의 주문 요약을 구현하는 방법을 보여주며, checkout.breakdown 이벤트를 사용하여 두 요소를 동기화합니다.
"use client";

import { useEffect, useState } from 'react';
import { DodoPayments, CheckoutBreakdownData } from 'dodopayments-checkout';

export default function CheckoutPage() {
  const [breakdown, setBreakdown] = useState<Partial<CheckoutBreakdownData>>({});

  useEffect(() => {
    // 1. Initialize the SDK
    DodoPayments.Initialize({
      mode: 'test',
      displayType: 'inline',
      onEvent: (event) => {
        // 2. Listen for the 'checkout.breakdown' event
        if (event.event_type === "checkout.breakdown") {
          const message = event.data?.message as CheckoutBreakdownData;
          if (message) setBreakdown(message);
        }
      }
    });

    // 3. Open the checkout in the specified container
    DodoPayments.Checkout.open({
      checkoutUrl: 'https://test.dodopayments.com/session/cks_123',
      elementId: 'dodo-inline-checkout'
    });

    return () => DodoPayments.Checkout.close();
  }, []);

  const format = (amt: number | null | undefined, curr: string | null | undefined) => 
    amt != null && curr ? `${curr} ${(amt/100).toFixed(2)}` : '0.00';

  const currency = breakdown.currency ?? breakdown.finalTotalCurrency ?? '';

  return (
    <div className="flex flex-col md:flex-row min-h-screen">
      {/* Left Side - Checkout Form */}
      <div className="w-full md:w-1/2 flex items-center">
        <div id="dodo-inline-checkout" className='w-full' />
      </div>

      {/* Right Side - Custom Order Summary */}
      <div className="w-full md:w-1/2 p-8 bg-gray-50">
        <h2 className="text-2xl font-bold mb-4">Order Summary</h2>
        <div className="space-y-2">
          {breakdown.subTotal && (
            <div className="flex justify-between">
              <span>Subtotal</span>
              <span>{format(breakdown.subTotal, currency)}</span>
            </div>
          )}
          {breakdown.discount && (
            <div className="flex justify-between">
              <span>Discount</span>
              <span>{format(breakdown.discount, currency)}</span>
            </div>
          )}
          {breakdown.tax != null && (
            <div className="flex justify-between">
              <span>Tax</span>
              <span>{format(breakdown.tax, currency)}</span>
            </div>
          )}
          <hr />
          {(breakdown.finalTotal ?? breakdown.total) && (
            <div className="flex justify-between font-bold text-xl">
              <span>Total</span>
              <span>{format(breakdown.finalTotal ?? breakdown.total, breakdown.finalTotalCurrency ?? currency)}</span>
            </div>
          )}
        </div>
      </div>
    </div>
  );
}

API 참조

구성

초기화 옵션

interface InitializeOptions {
  mode: "test" | "live";
  displayType: "inline"; // Required for inline checkout
  onEvent: (event: CheckoutEvent) => void;
}
옵션유형필수설명
mode"test" | "live"환경 모드입니다.
displayType"inline" | "overlay"결제를 임베드하려면 "inline"으로 설정해야 합니다.
onEventfunction결제 이벤트를 처리하는 콜백 함수입니다.

체크아웃 옵션

export type FontSize = "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
export type FontWeight = "normal" | "medium" | "bold" | "extraBold";

interface CheckoutOptions {
  checkoutUrl: string;
  elementId: string; // Required for inline checkout
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
    payButtonText?: string;
    fontSize?: FontSize;
    fontWeight?: FontWeight;
  };
}
옵션유형필수설명
checkoutUrlstring체크아웃 세션 URL.
elementIdstring체크아웃을 렌더링할 DOM 요소의 id입니다.
options.showTimerboolean아니요체크아웃 타이머 표시 여부. 기본값은 true입니다. 비활성화하면 세션이 만료될 때 checkout.link_expired 이벤트를 받습니다.
options.showSecurityBadgeboolean아니요보안 배지 표시 여부. 기본값은 true입니다.
options.manualRedirectboolean아니요활성화하면 체크아웃 완료 후 자동 리디렉션이 발생하지 않습니다. 대신 리디렉션을 직접 처리하기 위해 checkout.statuscheckout.redirect_requested 이벤트를 수신합니다.
options.payButtonTextstring아니요결제 버튼에 표시할 사용자 지정 텍스트.
options.fontSizeFontSize아니요체크아웃의 전역 글꼴 크기.
options.fontWeightFontWeight아니요체크아웃의 전역 글꼴 두께.

메서드

체크아웃 열기

지정된 컨테이너에서 체크아웃 프레임을 엽니다.
DodoPayments.Checkout.open({
  checkoutUrl: "https://test.dodopayments.com/session/cks_123",
  elementId: "dodo-inline-checkout"
});
체크아웃 동작을 사용자 정의하기 위해 추가 옵션을 전달할 수도 있습니다:
DodoPayments.Checkout.open({
  checkoutUrl: "https://test.dodopayments.com/session/cks_123",
  elementId: "dodo-inline-checkout",
  options: {
    showTimer: false,
    showSecurityBadge: false,
    manualRedirect: true,
    payButtonText: "Pay Now",
  },
});
manualRedirect 사용 시, onEvent 콜백에서 결제 완료를 처리하세요:
DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  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 콜백을 통해 실시간 이벤트를 제공합니다. 인라인 결제에서는 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결제 세션이 만료될 때 발생합니다. showTimerfalse로 설정되어 있을 때만 수신됩니다.
checkout.statusmanualRedirect이 활성화되었을 때 발생합니다. 결제 상태(succeeded, failed 또는 processing)를 포함합니다.
checkout.redirect_requestedmanualRedirect이 활성화되었을 때 발생합니다. 고객을 리디렉션할 URL을 포함합니다.

체크아웃 세부정보 데이터

checkout.breakdown 이벤트는 다음 데이터를 제공합니다:
interface CheckoutBreakdownData {
  subTotal?: number;          // Amount in cents
  discount?: number;         // Amount in cents
  tax?: number;              // Amount in cents
  total?: number;            // Amount in cents
  currency?: string;         // e.g., "USD"
  finalTotal?: number;       // Final amount including adjustments
  finalTotalCurrency?: string; // Currency for the final total
}

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

manualRedirect이 활성화되면 다음 데이터를 포함한 checkout.status 이벤트를 수신합니다:
interface CheckoutStatusEventData {
  message: {
    status?: "succeeded" | "failed" | "processing";
  };
}

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

manualRedirect이 활성화되면 다음 데이터를 포함한 checkout.redirect_requested 이벤트를 수신합니다:
interface CheckoutRedirectRequestedEventData {
  message: {
    redirect_to?: string;
  };
}

이벤트 이해하기

checkout.breakdown 이벤트는 애플리케이션의 UI를 Dodo Payments 결제 상태와 동기화하는 주요 수단입니다. 발생 시점:
  • 초기화 시: 체크아웃 프레임이 로드되고 준비된 직후.
  • 주소 변경 시: 고객이 세금 재계산을 초래하는 국가를 선택하거나 우편번호를 입력할 때마다.
필드 세부정보:
필드설명
subTotal세금이나 할인이 적용되기 전 세션의 전체 품목 합계입니다.
discount적용된 모든 할인 금액의 총합입니다.
tax계산된 세금 금액입니다. inline 모드에서는 사용자가 주소 필드를 조작할 때 실시간으로 업데이트됩니다.
total세션의 기준 통화로 계산한 표준 가격 결과입니다.
currency표준 소계, 할인 및 세금 값에 대한 ISO 통화 코드(예: "USD")입니다.
finalTotal고객에게 실제 청구되는 금액입니다. 기본 가격 구성에 포함되지 않는 환율 조정이나 지역 결제 수수료가 포함될 수 있습니다.
finalTotalCurrency고객이 실제로 결제하는 통화입니다. 구매력 평가지수나 지역 통화 변환이 활성화되어 있으면 currency와 다를 수 있습니다.
주요 통합 팁:
  1. 통화 형식화: 가격은 항상 가장 작은 통화 단위(예: USD의 센트, JPY의 엔)로 정수로 반환됩니다. 표시하려면 100(또는 해당 단위의 10의 거듭제곱)으로 나누거나 Intl.NumberFormat와 같은 형식화 라이브러리를 사용하세요.
  2. 초기 상태 처리: 체크아웃이 처음 로드되면 taxdiscount0 또는 null일 수 있으며, 사용자가 청구 정보를 제공하거나 코드를 적용할 때까지 이런 상태가 유지됩니다. UI에서는 이러한 상태를 정상적으로 처리해야 합니다(예: 대시 를 표시하거나 행을 숨김).
  3. “최종 총계” 대 “총계”: total는 표준 가격 계산을 제공하지만, finalTotal가 거래의 진실된 값입니다. finalTotal가 있으면 동적 조정 사항까지 포함하여 고객 카드에 실제로 청구되는 금액을 정확히 반영합니다.
  4. 실시간 피드백: tax 필드를 사용하여 세금이 실시간으로 계산되고 있음을 사용자에게 보여주면 “실시간” 느낌을 제공하여 주소 입력 단계에서 마찰을 줄일 수 있습니다.

구현 옵션

패키지 관리자 설치

npm, yarn 또는 pnpm을 통해 단계별 통합 가이드와 같이 설치합니다.

CDN 구현

빌드 단계 없이 빠른 통합을 위해 CDN을 사용할 수 있습니다:
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Dodo Payments Inline Checkout</title>
    
    <!-- Load DodoPayments -->
    <script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
    <script>
        // Initialize the SDK
        DodoPaymentsCheckout.DodoPayments.Initialize({
            mode: "test",
            displayType: "inline",
            onEvent: (event) => {
                console.log('Checkout event:', event);
            }
        });
    </script>
</head>
<body>
    <div id="dodo-inline-checkout"></div>

    <script>
        // Open the checkout
        DodoPaymentsCheckout.DodoPayments.Checkout.open({
            checkoutUrl: "https://test.dodopayments.com/session/cks_123",
            elementId: "dodo-inline-checkout"
        });
    </script>
</body>
</html>

결제 수단 업데이트

인라인 체크아웃은 구독에 대한 결제 수단 업데이트를 지원합니다. 고객이 활성 구독 또는 보류 중인 구독을 다시 활성화하기 위해 결제 수단을 변경해야 하는 경우, 업데이트 흐름을 페이지 레이아웃 내에서 직접 렌더링할 수 있습니다.

작동 원리

  1. Update Payment Method API를 호출하여 payment_link을 받습니다:
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  type: 'new',
  return_url: 'https://example.com/return'
});
  1. 반환된 payment_linkcheckoutUrl으로 전달하여 인라인 체크아웃을 엽니다:
DodoPayments.Checkout.open({
  checkoutUrl: response.payment_link,
  elementId: "dodo-inline-checkout"
});
인라인 프레임은 결제 수단 수집 양식만 렌더링합니다. 고객은 페이지를 떠나지 않고도 새 카드 정보를 입력하거나 저장된 결제 수단을 선택할 수 있습니다.

보류 중인 구독의 경우

on_hold 상태의 구독에 대해 결제 수단을 업데이트하면 Dodo Payments는 남은 금액에 대해 자동으로 과금을 생성합니다. payment.succeededsubscription.active 웹훅을 모니터링하여 다시 활성화 여부를 확인하세요.
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  type: 'new',
  return_url: 'https://example.com/return'
});

if (response.payment_id) {
  // Charge created for remaining dues
  // Open inline checkout for payment collection
  DodoPayments.Checkout.open({
    checkoutUrl: response.payment_link,
    elementId: "dodo-inline-checkout"
  });
}
새 정보를 수집하는 대신 기존에 저장된 결제 수단을 사용할 수도 있으며, Update Payment Method API에 type: 'existing'payment_method_id를 전달하면 됩니다.

오류 처리

SDK는 이벤트 시스템을 통해 상세한 오류 정보를 제공합니다. 항상 onEvent 콜백에서 적절한 오류 처리를 구현하세요:
DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Handle error appropriately
    }
  }
});
문제가 발생했을 때 좋은 사용자 경험을 제공하기 위해 항상 checkout.error 이벤트를 처리하세요.

모범 사례

  1. 반응형 디자인: 컨테이너 요소에 충분한 너비와 높이를 확보하세요. iframe은 일반적으로 컨테이너를 채우도록 확장됩니다.
  2. 동기화: checkout.breakdown 이벤트를 사용하여 사용자 맞춤 주문 요약 또는 가격표를 체크아웃 프레임에서 보는 내용과 일치시키세요.
  3. 스켈레톤 상태: checkout.opened 이벤트가 발생할 때까지 컨테이너에 로딩 표시기를 표시하세요.
  4. 정리: 컴포넌트가 언마운트될 때 DodoPayments.Checkout.close()를 호출하여 iframe과 이벤트 리스너를 정리하세요.
다크 모드 구현의 경우, 인라인 체크아웃 프레임과 시각적으로 최적의 통합을 위해 백그라운드 색상으로 #0d0d0d를 사용하는 것이 좋습니다.

결제 상태 검증

결제 성공 또는 실패를 판단하기 위해 인라인 체크아웃 이벤트만 의존하지 마세요. 웹훅 및/또는 폴링을 사용하여 항상 서버 측 검증을 구현하세요.

서버 측 검증이 중요한 이유

checkout.status과 같은 인라인 체크아웃 이벤트는 실시간 피드백을 제공하지만, 결제 상태의 유일한 진실원이 되어서는 안 됩니다. 네트워크 문제, 브라우저 충돌 또는 사용자가 페이지를 닫는 등의 상황에서 이벤트를 놓칠 수 있습니다. 신뢰할 수 있는 결제 검증을 위해 다음을 수행하세요:
  1. 서버가 웹훅 이벤트를 수신해야 합니다 - Dodo Payments는 결제 상태 변경에 대해 웹훅을 전송합니다.
  2. 폴링 메커니즘 구현 - 프런트엔드는 서버에 결제 상태 업데이트를 폴링해야 합니다.
  3. 두 가지 접근 방식 결합 - 웹훅을 주요 소스로 사용하고 폴링을 폴백으로 사용하세요.

추천 아키텍처

구현 단계

1. 체크아웃 이벤트 수신 - 사용자가 결제 버튼을 클릭하면 상태 확인을 준비하세요:
onEvent: (event) => {
  if (event.event_type === 'checkout.status') {
    // Start polling your server for confirmed status
    startPolling();
  }
}
2. 서버를 폴링 - 웹훅으로 업데이트된 결제 상태를 확인하기 위해 데이터베이스를 조회하는 엔드포인트를 만드세요:
// Poll every 2 seconds until status is confirmed
const interval = setInterval(async () => {
  const { status } = await fetch(`/api/payments/${paymentId}/status`).then(r => r.json());
  if (status === 'succeeded' || status === 'failed') {
    clearInterval(interval);
    handlePaymentResult(status);
  }
}, 2000);
3. 서버 측에서 웹훅 처리 - Dodo가 payment.succeeded 또는 payment.failed 웹훅을 보낼 때 데이터베이스를 업데이트하세요. 자세한 내용은 Webhooks documentation를 확인하세요.

리디렉션 처리 (3DS, Google Pay, UPI)

manualRedirect: true을 사용할 때 특정 결제 수단은 인증을 위해 사용자를 페이지에서 벗어나게 하는 리디렉션이 필요합니다:
  • 3D Secure (3DS) - 카드 인증
  • Google Pay - 일부 플로우에서 지갑 인증
  • UPI - 인도 결제 수단 리디렉션
리디렉션이 필요한 경우 checkout.redirect_requested 이벤트를 받습니다. 제공된 URL로 사용자를 리디렉션하세요:
if (event.event_type === 'checkout.redirect_requested') {
  const redirectUrl = event.data?.message?.redirect_to;
  // Save payment ID before redirect, then redirect
  sessionStorage.setItem('pendingPaymentId', paymentId);
  window.location.href = redirectUrl;
}
인증이 완료되면(성공 또는 실패), 사용자가 페이지로 돌아옵니다. 사용자가 돌아왔다고 해서 결제가 성공했다고 가정하지 마세요. 대신 다음을 수행하세요:
  1. 사용자가 리디렉션에서 돌아왔는지 확인하세요 (예: sessionStorage를 통해).
  2. 서버에서 확정된 결제 상태를 폴링하기 시작하세요.
  3. 폴링하는 동안 “결제 확인 중…” 상태를 표시하세요.
  4. 서버에서 확인된 상태를 기반으로 성공/실패 UI를 표시하세요.
리디렉션 이후에는 항상 서버 측에서 결제 상태를 검증하세요. 사용자가 페이지로 돌아왔다는 것은 인증이 완료되었다는 의미일 뿐이며, 결제가 성공했는지는 아닙니다.

문제 해결

  • elementId이 실제 DOM에 존재하는 divid과 일치하는지 확인하세요.
  • displayType: 'inline'Initialize에 전달되었는지 확인하세요.
  • checkoutUrl이 유효한지 확인하세요.
  • checkout.breakdown 이벤트를 수신하는지 확인하세요.
  • 세금은 사용자가 체크아웃 프레임에서 유효한 국가 및 우편번호를 입력한 후에만 계산됩니다.

디지털 지갑 활성화

Apple Pay, Google Pay 및 기타 디지털 지갑 설정에 관한 자세한 내용은 Digital Wallets 페이지를 참조하세요.

Apple Pay 빠른 설정

1

Download domain association file

Apple Pay 도메인 연결 파일을 다운로드하세요.
2

Request activation

운영 도메인 URL과 함께 support@dodopayments.com으로 이메일을 보내 Apple Pay 활성화를 요청하세요.
3

Test after confirmation

확인되면 Apple Pay가 체크아웃에 표시되는지 확인하고 전체 흐름을 테스트하세요.
Apple Pay는 운영 환경에 표시되기 전에 도메인 검증이 필요합니다. Apple Pay를 제공할 계획이라면 베타 이전에 지원팀에 문의하세요.

브라우저 지원

Dodo Payments Checkout SDK는 다음 브라우저를 지원합니다:
  • Chrome (최신)
  • Firefox (최신)
  • Safari (최신)
  • Edge (최신)
  • IE11+

인라인과 오버레이 체크아웃 비교

사용 사례에 적합한 체크아웃 유형을 선택하세요:
기능인라인 체크아웃오버레이 체크아웃
통합 깊이페이지에 완전히 내장됨페이지 위에 모달 형식
레이아웃 제어완전 제어제한적
브랜딩원활함페이지와 분리됨
구현 노력더 높음더 낮음
가장 적합한 곳맞춤 체크아웃 페이지, 높은 전환 흐름빠른 통합, 기존 페이지
체크아웃 경험과 브랜딩을 최대한 제어하고자 한다면 인라인 체크아웃을 사용하세요. 기존 페이지에 최소한의 변경으로 빠르게 통합하려면 오버레이 체크아웃을 사용하세요.

관련 자료

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