인라인 체크아웃

개요

인라인 체크아웃을 사용하면 웹사이트나 애플리케이션과 원활하게 통합된 체크아웃 경험을 생성할 수 있습니다. 페이지 위에 모달로 열리는 오버레이 체크아웃과 달리, 인라인 체크아웃은 결제 양식을 페이지 레이아웃에 직접 임베드합니다. 인라인 체크아웃을 사용하면 다음을 수행할 수 있습니다:

앱이나 웹사이트와 완전히 통합된 체크아웃 경험 생성
Dodo Payments가 고객 및 결제 정보를 안전하게 캡처하도록 최적화된 체크아웃 프레임 사용
페이지에 Dodo Payments의 항목, 총액 및 기타 정보 표시
SDK 메서드 및 이벤트를 사용하여 고급 체크아웃 경험 구축

작동 방식

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

인라인 체크아웃 프레임은 모든 민감한 결제 정보를 안전하게 처리하여 귀하의 추가 인증 없이 PCI 준수를 보장합니다.

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

고객이 누구에게서 구매하고 있는지, 무엇을 구매하고 있는지, 얼마를 지불하고 있는지 아는 것이 중요합니다. 준수 및 전환 최적화를 위한 인라인 체크아웃을 구축하려면 구현에 다음이 포함되어야 합니다:

필수 요소가 표시된 인라인 체크아웃 레이아웃 예시

정기 정보: 정기적인 경우, 얼마나 자주 반복되는지 및 갱신 시 지불할 총액. 체험판인 경우, 체험판 기간.
항목 설명: 구매하는 항목에 대한 설명.
거래 총액: 거래 총액, 포함된 소계, 총 세금 및 총합. 통화도 포함해야 합니다.
Dodo Payments 바닥글: Dodo Payments에 대한 정보, 판매 조건 및 개인정보 보호정책이 포함된 전체 인라인 체크아웃 프레임.
환불 정책: Dodo Payments의 표준 환불 정책과 다를 경우 환불 정책에 대한 링크.

법적 정보를 제거하거나 숨기는 것은 준수 요구 사항을 위반하므로 항상 전체 인라인 체크아웃 프레임을 표시해야 합니다.

고객 여정

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

고객이 체크아웃을 엽니다

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

고객이 세부 정보를 입력합니다

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

고객이 결제 방법을 선택합니다

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

체크아웃 완료

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

Dodo Payments가 구독을 생성합니다

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

단계별 통합 가이드

SDK 설치

Dodo Payments Checkout SDK를 설치하세요:

npm install dodopayments-checkout

인라인 표시를 위한 SDK 초기화

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.
    }
  },
});

컨테이너 요소 만들기

체크아웃 프레임이 삽입될 HTML 요소를 추가하세요:

<div id="dodo-inline-checkout"></div>

체크아웃 열기

DodoPayments.Checkout.open()를 호출하여 checkoutUrl와 컨테이너의 elementId을 전달하세요:

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

통합 테스트

개발 서버를 시작하세요:

npm run dev

체크아웃 흐름을 테스트하세요:
- 인라인 프레임에 이메일 및 주소 세부 정보를 입력하세요.
- 사용자 정의 주문 요약이 실시간으로 업데이트되는지 확인하세요.
- 테스트 자격 증명을 사용하여 결제 흐름을 테스트하세요.
- 리디렉션이 올바르게 작동하는지 확인하세요.

checkout.breakdown 이벤트가 브라우저 콘솔에 기록된 것을 확인할 수 있어야 합니다. onEvent 콜백에 콘솔 로그를 추가한 경우입니다.

라이브로 전환

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

모드를 'live'로 변경하세요:

DodoPayments.Initialize({
  mode: "live",
  displayType: "inline",
  onEvent: (event) => {
    // Handle events
  }
});

체크아웃 URL을 백엔드에서 라이브 체크아웃 세션을 사용하도록 업데이트하세요.
프로덕션에서 전체 흐름을 테스트하세요.

완전한 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"`로 설정해야 합니다.
`onEvent`	`function`	예	체크아웃 이벤트를 처리하는 콜백 함수.

체크아웃 옵션

interface CheckoutOptions {
  checkoutUrl: string;
  elementId: string; // Required for inline checkout
}

옵션	유형	필수	설명
`checkoutUrl`	`string`	예	체크아웃 세션 URL.
`elementId`	`string`	예	체크아웃이 렌더링되어야 하는 DOM 요소의 `id`.

메서드

체크아웃 열기

지정된 컨테이너에서 체크아웃 프레임을 엽니다.

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

체크아웃 닫기

프로그래밍 방식으로 체크아웃 프레임을 제거하고 이벤트 리스너를 정리합니다.

DodoPayments.Checkout.close();

상태 확인

현재 체크아웃 프레임이 삽입되었는지 여부를 반환합니다.

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

이벤트

SDK는 onEvent 콜백을 통해 실시간 이벤트를 제공합니다. 인라인 체크아웃의 경우, checkout.breakdown 이벤트가 UI 동기화에 특히 유용합니다.

이벤트 유형	설명
`checkout.opened`	체크아웃 프레임이 로드되었습니다.
`checkout.breakdown`	가격, 세금 또는 할인이 업데이트될 때 발생합니다.
`checkout.customer_details_submitted`	고객 세부 정보가 제출되었습니다.
`checkout.redirect`	체크아웃이 리디렉션을 수행합니다(예: 은행 페이지로).
`checkout.error`	체크아웃 중 오류가 발생했습니다.

체크아웃 세부 데이터

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
}

세부 이벤트 이해하기

checkout.breakdown 이벤트는 애플리케이션의 UI를 Dodo Payments 체크아웃 상태와 동기화하는 주요 방법입니다. 발생 시점:

초기화 시: 체크아웃 프레임이 로드되고 준비된 직후.
주소 변경 시: 고객이 세금을 재계산하는 국가를 선택하거나 우편번호를 입력할 때마다.

필드 세부정보:

필드	설명
`subTotal`	할인이나 세금이 적용되기 전 세션의 모든 항목의 합계입니다.
`discount`	적용된 모든 할인 총액입니다.
`tax`	계산된 세금 금액입니다. `inline` 모드에서는 사용자가 주소 필드와 상호작용할 때 동적으로 업데이트됩니다.
`total`	세션의 기본 통화로 `subTotal - discount + tax`의 수학적 결과입니다.
`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을 사용할 수 있습니다:

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

TypeScript 지원

SDK는 TypeScript로 작성되었으며 포괄적인 타입 정의를 포함합니다.

import { DodoPayments, CheckoutEvent } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  onEvent: (event: CheckoutEvent) => {
    // event is fully typed
    console.log(event.event_type, event.data);
  },
});

오류 처리

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 이벤트를 처리하세요.

모범 사례

반응형 디자인: 컨테이너 요소가 충분한 너비와 높이를 가지도록 하세요. iframe은 일반적으로 컨테이너를 채우도록 확장됩니다.
동기화: checkout.breakdown 이벤트를 사용하여 사용자 정의 주문 요약 또는 가격표를 체크아웃 프레임에서 사용자가 보는 내용과 동기화하세요.
스켈레톤 상태: checkout.opened 이벤트가 발생할 때까지 컨테이너에 로딩 표시기를 표시하세요.
정리: 구성 요소가 언마운트될 때 DodoPayments.Checkout.close()를 호출하여 iframe과 이벤트 리스너를 정리하세요.

문제 해결

체크아웃 프레임이 나타나지 않음

elementId가 DOM에 실제로 존재하는 id의 div와 일치하는지 확인하세요.
displayType: 'inline'가 Initialize에 전달되었는지 확인하세요.
checkoutUrl가 유효한지 확인하세요.

UI에서 세금이 업데이트되지 않음

checkout.breakdown 이벤트를 수신하고 있는지 확인하세요.
세금은 사용자가 체크아웃 프레임에 유효한 국가와 우편번호를 입력한 후에만 계산됩니다.

브라우저 지원

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

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

Apple Pay는 현재 인라인 체크아웃 경험에서 지원되지 않습니다. 향후 릴리스에서 Apple Pay 지원을 추가할 계획입니다.