메인 콘텐츠로 건너뛰기
세션 유효성: 체크아웃 세션은 기본적으로 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');
대체 통합 옵션: 리디렉션 대신, Overlay Checkout (모달 오버레이) 또는 Inline Checkout (완전 임베디드)를 사용하여 체크아웃을 페이지에 직접 삽입할 수 있습니다. 두 옵션 모두 동일한 체크아웃 세션 URL을 사용합니다.
3

반환 처리

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

요청 본문

필수 필드

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

선택적 필드

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

필수 필드

product_cart
array
필수
체크아웃 세션에 포함할 제품의 배열입니다. 각 제품은 Dodo Payments 대시보드에서 유효한 product_id를 가져야 합니다.
혼합 체크아웃: 동일한 체크아웃 세션에서 일회성 결제 제품과 구독 제품을 결합할 수 있습니다. 이를 통해 구독과 함께하는 설정 비용, SaaS와 함께하는 하드웨어 번들 등과 같은 강력한 사용 사례를 가능하게 합니다.
제품 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
기본값:"false"
반복 고객을 위해 이전에 저장된 결제 방법을 표시하여 체크아웃 속도와 사용자 경험을 개선합니다.
return_url
string
결제가 성공적으로 완료되거나 취소된 후 고객을 리디렉션할 URL입니다.
confirm
boolean
기본값:"false"
true로 설정하면 모든 세션 세부정보가 즉시 확정됩니다. 필수 데이터가 누락된 경우 API가 오류를 발생시킵니다.
discount_code
string
체크아웃 세션에 할인 코드를 적용합니다.
metadata
object
세션에 대한 추가 정보를 저장하기 위한 사용자 정의 키-값 쌍입니다.
force_3ds
boolean
이 세션에 대해 상인 기본 3DS 동작을 재정의합니다.
minimal_address
boolean
기본값:"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'
  }
});

11. 기존 결제 수단을 사용한 즉시 체크아웃

고객의 저장된 결제 수단을 사용하여 즉시 처리되는 체크아웃 세션을 생성하고 결제 수단 수집을 건너뜁니다:
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_premium_plan',
      quantity: 1
    }
  ],
  customer: {
    customer_id: 'cus_123'  // Required when using payment_method_id
  },
  payment_method_id: 'pm_abc123',  // Use customer's saved payment method
  confirm: true,  // Required when using payment_method_id
  return_url: 'https://yourapp.com/success'
});
payment_method_id를 사용할 때, confirmtrue로 설정되어야 하며, 기존의 customer_id가 제공되어야 합니다. 결제 수단은 결제 통화에 대한 적격성을 검증합니다.
결제 수단은 고객에게 속해야 하며 결제 통화와 호환되어야 합니다. 이는 재구매 고객을 위한 원클릭 구매를 가능하게 합니다.

12. 깔끔한 결제 URL을 위한 짧은 링크

사용자 정의 슬러그가 있는 짧고 공유 가능한 결제 링크를 생성합니다:
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_monthly_subscription',
      quantity: 1
    }
  ],
  short_link: true,  // Generate a shortened payment link
  return_url: 'https://yourapp.com/success',
  customer: {
    email: '[email protected]',
    name: 'John Doe'
  }
});

// The checkout_url will be a shortened, cleaner link
console.log(session.checkout_url);  // e.g., https://checkout.dodopayments.com/buy/abc123
짧은 링크는 SMS, 이메일 또는 소셜 미디어 공유에 적합합니다. 긴 URL보다 기억하기 쉽고 고객 신뢰를 더 구축합니다.

13. 즉시 리디렉션으로 결제 성공 페이지 건너뛰기

결제 완료 후 고객을 즉시 리디렉션하여 기본 성공 페이지를 우회합니다:
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_digital_product',
      quantity: 1
    }
  ],
  feature_flags: {
    redirect_immediately: true  // Skip success page, redirect immediately
  },
  return_url: 'https://yourapp.com/success',
  customer: {
    email: '[email protected]',
    name: 'Jane Smith'
  }
});
기본 결제 성공 페이지보다 더 나은 사용자 경험을 제공하는 사용자 정의 성공 페이지가 있는 경우 redirect_immediately: true를 사용하세요. 이는 모바일 앱 및 임베디드 체크아웃 흐름에 특히 유용합니다.
redirect_immediately가 활성화되면, 고객은 결제 완료 후 즉시 return_url로 리디렉션되어 기본 성공 페이지를 완전히 건너뜁니다.

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

주요 차이점

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

마이그레이션 프로세스

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

통합 업데이트

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

요청 페이로드 조정

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

그게 전부입니다!

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