메인 콘텐츠로 건너뛰기
세션 유효성: 체크아웃 세션은 기본적으로 24시간 동안 유효합니다. 요청에 confirm=true를 전달하면 세션은 15분 동안만 유효합니다.

전제 조건

1

Dodo Payments 계정

API 액세스가 있는 활성 Dodo Payments 상인 계정이 필요합니다.
2

API 자격 증명

Dodo Payments 대시보드에서 API 자격 증명을 생성하세요:
3

제품 설정

체크아웃 세션을 구현하기 전에 Dodo Payments 대시보드에서 제품을 생성하세요.

첫 체크아웃 세션 생성하기

import DodoPayments from 'dodopayments';

// Initialize the Dodo Payments client
const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

async function createCheckoutSession() {
  try {
    const session = await client.checkoutSessions.create({
      // Products to sell - use IDs from your Dodo Payments dashboard
      product_cart: [
        {
          product_id: 'prod_123', // Replace with your actual product ID
          quantity: 1
        }
      ],
      
      // Pre-fill customer information to reduce friction
      customer: {
        email: '[email protected]',
        name: 'John Doe',
        phone_number: '+1234567890'
      },
      
      // Billing address for tax calculation and compliance
      billing_address: {
        street: '123 Main St',
        city: 'San Francisco',
        state: 'CA',
        country: 'US', // Required: ISO 3166-1 alpha-2 country code
        zipcode: '94102'
      },
      
      // Where to redirect after successful payment
      return_url: 'https://yoursite.com/checkout/success',
      
      // Custom data for your internal tracking
      metadata: {
        order_id: 'order_123',
        source: 'web_app'
      }
    });

    // Redirect your customer to this URL to complete payment
    console.log('Checkout URL:', session.checkout_url);
    console.log('Session ID:', session.session_id);
    
    return session;
    
  } catch (error) {
    console.error('Failed to create checkout session:', error);
    throw error;
  }
}

// Example usage in an Express.js route
app.post('/create-checkout', async (req, res) => {
  try {
    const session = await createCheckoutSession();
    res.json({ checkout_url: session.checkout_url });
  } catch (error) {
    res.status(500).json({ error: 'Failed to create checkout session' });
  }
});

API 응답

위의 모든 메서드는 동일한 응답 구조를 반환합니다:
{
  "session_id": "cks_Gi6KGJ2zFJo9rq9Ukifwa",
  "checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"
}
1

체크아웃 URL 가져오기

API 응답에서 checkout_url를 추출하세요.
2

고객 리디렉션

고객을 체크아웃 URL로 안내하여 구매를 완료하세요.
// Redirect immediately
window.location.href = session.checkout_url;

// Or open in new window
window.open(session.checkout_url, '_blank');
3

반환 처리

결제 후 고객은 결제 상태에 대한 추가 쿼리 매개변수와 함께 return_url로 리디렉션됩니다.

요청 본문

필수 필드

모든 체크아웃 세션에 필요한 필수 필드

선택적 필드

체크아웃 경험을 사용자 정의하기 위한 추가 구성

필수 필드

product_cart
array
required
체크아웃 세션에 포함할 제품의 배열입니다. 각 제품은 Dodo Payments 대시보드에서 유효한 product_id를 가져야 합니다.
중요: 여러 제품 카트는 일회성 결제 제품만 포함할 수 있습니다. 동일한 체크아웃 세션에서 구독 제품과 일회성 제품을 혼합할 수 없습니다.
제품 ID 찾기: Dodo Payments 대시보드의 제품 → 세부정보 보기에서 제품 ID를 찾거나 제품 목록 API를 사용하세요.

선택적 필드

이 필드를 구성하여 체크아웃 경험을 사용자 정의하고 결제 흐름에 비즈니스 로직을 추가하세요.
customer
object
고객 정보입니다. 고객 ID를 사용하여 기존 고객을 연결하거나 체크아웃 중에 새 고객 레코드를 생성할 수 있습니다.
고객 ID를 사용하여 체크아웃 세션에 기존 고객을 연결합니다.
billing_address
object
정확한 세금 계산, 사기 방지 및 규제 준수를 위한 청구 주소 정보입니다.
confirmtrue로 설정되면 모든 청구 주소 필드가 성공적인 세션 생성을 위해 필수로 변환됩니다.
allowed_payment_method_types
array
체크아웃 중 고객에게 제공되는 결제 방법을 제어합니다. 이는 특정 시장 또는 비즈니스 요구 사항에 최적화하는 데 도움이 됩니다.사용 가능한 옵션: credit, debit, upi_collect, upi_intent, apple_pay, google_pay, amazon_pay, klarna, affirm, afterpay_clearpay, sepa, ach, cashapp, multibanco, bancontact_card, eps, ideal, przelewy24, paypal
중요: 항상 creditdebit를 대체 옵션으로 포함하여 선호하는 결제 방법이 사용 불가능할 때 체크아웃 실패를 방지하세요.
예시:
["apple_pay", "google_pay", "credit", "debit"]
billing_currency
string
기본 통화 선택을 고정된 청구 통화로 재정의합니다. ISO 4217 통화 코드를 사용합니다.지원되는 통화: USD, EUR, GBP, CAD, AUD, INR, 기타예시: "USD" (미국 달러), "EUR" (유로)
이 필드는 적응형 가격 책정이 활성화된 경우에만 효과적입니다. 적응형 가격 책정이 비활성화된 경우 제품의 기본 통화가 사용됩니다.
show_saved_payment_methods
boolean
default:"false"
반복 고객을 위해 이전에 저장된 결제 방법을 표시하여 체크아웃 속도와 사용자 경험을 개선합니다.
return_url
string
결제가 성공적으로 완료되거나 취소된 후 고객을 리디렉션할 URL입니다.
confirm
boolean
default:"false"
true로 설정하면 모든 세션 세부정보가 즉시 확정됩니다. 필수 데이터가 누락된 경우 API가 오류를 발생시킵니다.
discount_code
string
체크아웃 세션에 할인 코드를 적용합니다.
metadata
object
세션에 대한 추가 정보를 저장하기 위한 사용자 정의 키-값 쌍입니다.
force_3ds
boolean
이 세션에 대해 상인 기본 3DS 동작을 재정의합니다.
minimal_address
boolean
default:"false"
최소 주소 수집 모드를 활성화합니다. 활성화되면 체크아웃에서 다음만 수집합니다:
  • 국가: 세금 결정에 항상 필요
  • 우편/ZIP 코드: 판매세, VAT 또는 GST 계산에 필요한 지역에서만
이것은 불필요한 양식 필드를 제거하여 체크아웃 마찰을 크게 줄입니다.
더 빠른 체크아웃 완료를 위해 최소 주소를 활성화하세요. 전체 주소 수집은 완전한 청구 세부정보가 필요한 비즈니스에 대해 계속 사용할 수 있습니다.
customization
object
체크아웃 인터페이스의 모양과 동작을 사용자 정의합니다.
feature_flags
object
체크아웃 세션에 대한 특정 기능 및 동작을 구성합니다.
subscription_data
object
구독 제품이 포함된 체크아웃 세션에 대한 추가 구성입니다.

사용 예시

다양한 비즈니스 시나리오에 대한 다양한 체크아웃 세션 구성을 보여주는 10개의 포괄적인 예시입니다:

1. 간단한 단일 제품 체크아웃

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_ebook_guide',
      quantity: 1
    }
  ],
  customer: {
    email: '[email protected]',
    name: 'John Doe'
  },
  return_url: 'https://yoursite.com/success'
});

2. 다중 제품 카트

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_laptop',
      quantity: 1
    },
    {
      product_id: 'prod_mouse',
      quantity: 2
    },
    {
      product_id: 'prod_warranty',
      quantity: 1
    }
  ],
  customer: {
    email: '[email protected]',
    name: 'John Doe',
    phone_number: '+1234567890'
  },
  billing_address: {
    street: '123 Tech Street',
    city: 'San Francisco',
    state: 'CA',
    country: 'US',
    zipcode: '94102'
  },
  return_url: 'https://electronics-store.com/order-confirmation'
});

3. 시험 기간이 있는 구독

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_monthly_plan',
      quantity: 1
    }
  ],
  subscription_data: {
    trial_period_days: 14
  },
  customer: {
    email: '[email protected]',
    name: 'Jane Smith'
  },
  return_url: 'https://saas-app.com/onboarding',
  metadata: {
    plan_type: 'professional',
    referral_source: 'google_ads'
  }
});

4. 사전 확인된 체크아웃

confirmtrue로 설정되면 고객은 확인 단계를 건너뛰고 체크아웃 페이지로 직접 이동합니다.
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_premium_course',
      quantity: 1
    }
  ],
  customer: {
    email: '[email protected]',
    name: 'Alex Johnson',
    phone_number: '+1555123456'
  },
  billing_address: {
    street: '456 University Ave',
    city: 'Boston',
    state: 'MA',
    country: 'US',
    zipcode: '02134'
  },
  confirm: true,
  return_url: 'https://learning-platform.com/course-access',
  metadata: {
    course_category: 'programming',
    enrollment_date: '2024-01-15'
  }
});

5. 통화 재정의가 있는 체크아웃

billing_currency 재정의는 계정 설정에서 적응형 통화가 활성화된 경우에만 적용됩니다. 적응형 통화가 비활성화된 경우 이 매개변수는 효과가 없습니다.
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_consulting_service',
      quantity: 1
    }
  ],
  customer: {
    email: '[email protected]',
    name: 'Oliver Williams'
  },
  billing_address: {
    street: '789 Business Park',
    city: 'London',
    state: 'England',
    country: 'GB',
    zipcode: 'SW1A 1AA'
  },
  billing_currency: 'GBP',
  feature_flags: {
    allow_currency_selection: true,
    allow_tax_id: true
  },
  return_url: 'https://consulting-firm.com/service-confirmation'
});

6. 반복 고객을 위한 저장된 결제 방법

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_monthly_subscription',
      quantity: 1
    }
  ],
  customer: {
    email: '[email protected]',
    name: 'Robert Johnson',
    phone_number: '+1555987654'
  },
  show_saved_payment_methods: true,
  feature_flags: {
    allow_phone_number_collection: true,
    always_create_new_customer: false
  },
  return_url: 'https://subscription-service.com/welcome-back',
  metadata: {
    customer_tier: 'premium',
    account_age: 'returning'
  }
});

7. 세금 ID 수집이 있는 B2B 체크아웃

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_enterprise_license',
      quantity: 5
    }
  ],
  customer: {
    email: '[email protected]',
    name: 'Sarah Davis',
    phone_number: '+1800555000'
  },
  billing_address: {
    street: '1000 Corporate Blvd',
    city: 'New York',
    state: 'NY',
    country: 'US',
    zipcode: '10001'
  },
  feature_flags: {
    allow_tax_id: true,
    allow_phone_number_collection: true,
    always_create_new_customer: false
  },
  return_url: 'https://enterprise-software.com/license-delivery',
  metadata: {
    customer_type: 'enterprise',
    contract_id: 'ENT-2024-001',
    sales_rep: '[email protected]'
  }
});

8. 할인 코드가 있는 다크 테마 체크아웃

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_gaming_chair',
      quantity: 1
    }
  ],
  discount_code: 'BLACKFRIDAY2024',
  customization: {
    theme: 'dark',
    show_order_details: true,
    show_on_demand_tag: false
  },
  feature_flags: {
    allow_discount_code: true
  },
  customer: {
    email: '[email protected]',
    name: 'Mike Chen'
  },
  return_url: 'https://gaming-store.com/order-complete'
});

9. 지역 결제 방법 (인도의 UPI)

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_online_course_hindi',
      quantity: 1
    }
  ],
  allowed_payment_method_types: [
    'upi_collect',
    'upi_intent',
    'credit',
    'debit'
  ],
  customer: {
    email: '[email protected]',
    name: 'Priya Sharma',
    phone_number: '+919876543210'
  },
  billing_address: {
    street: 'MG Road',
    city: 'Bangalore',
    state: 'Karnataka',
    country: 'IN',
    zipcode: '560001'
  },
  billing_currency: 'INR',
  return_url: 'https://education-platform.in/course-access',
  metadata: {
    region: 'south_india',
    language: 'hindi'
  }
});

10. BNPL (지금 구매하고 나중에 결제하기) 체크아웃

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_luxury_watch',
      quantity: 1
    }
  ],
  allowed_payment_method_types: [
    'klarna',
    'affirm',
    'afterpay_clearpay',
    'credit',
    'debit'
  ],
  customer: {
    email: '[email protected]',
    name: 'Emma Thompson',
    phone_number: '+1234567890'
  },
  billing_address: {
    street: '555 Fashion Ave',
    city: 'Los Angeles',
    state: 'CA',
    country: 'US',
    zipcode: '90210'
  },
  feature_flags: {
    allow_phone_number_collection: true
  },
  return_url: 'https://luxury-store.com/purchase-confirmation',
  metadata: {
    product_category: 'luxury',
    price_range: 'high_value'
  }
});

동적 링크에서 체크아웃 세션으로 이동하기

주요 차이점

이전에는 동적 링크로 결제 링크를 생성할 때 고객의 전체 청구 주소를 제공해야 했습니다. 체크아웃 세션에서는 더 이상 필요하지 않습니다. 가지고 있는 정보를 간단히 전달하면 나머지는 저희가 처리합니다. 예를 들어:
  • 고객의 청구 국가만 알고 있다면, 그 정보만 제공하세요.
  • 체크아웃 흐름은 결제 페이지로 이동하기 전에 누락된 세부정보를 자동으로 수집합니다.
  • 반면에, 모든 필수 정보를 이미 알고 있고 결제 페이지로 직접 건너뛰고 싶다면, 전체 데이터 세트를 전달하고 요청 본문에 confirm=true를 포함할 수 있습니다.

마이그레이션 프로세스

동적 링크에서 체크아웃 세션으로의 마이그레이션은 간단합니다:
1

통합 업데이트

새 API 또는 SDK 메서드를 사용하도록 통합을 업데이트하세요.
2

요청 페이로드 조정

체크아웃 세션 형식에 따라 요청 페이로드를 조정하세요.
3

그게 전부입니다!

네. 귀하 측에서 추가 처리나 특별한 마이그레이션 단계가 필요하지 않습니다.