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

전제 조건

1

Dodo Payments 계정

API 접근이 가능한 활성 Dodo Payments 상인 계정이 필요합니다.
2

API 자격 증명

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

제품 설정

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

첫 번째 Checkout 세션 생성하기

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: 'customer@example.com',
        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

Checkout URL 가져오기

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

고객 리디렉션

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

// Or open in new window
window.open(session.checkout_url, '_blank');
대체 통합 옵션: 리디렉션 대신 Overlay Checkout (모달 오버레이) 또는 Inline Checkout (완전 임베드)를 사용하여 페이지에 Checkout을 직접 삽입할 수 있습니다. 두 옵션 모두 동일한 Checkout 세션 URL을 사용합니다.
3

반환 처리

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

요청 본문

필수 필드

모든 Checkout 세션에 필요한 필수 필드

선택적 필드

Checkout 경험을 사용자 정의하기 위한 추가 구성

필수 필드

product_cart
array
필수
Checkout 세션에 포함할 제품의 배열입니다. 각 제품은 Dodo Payments 대시보드에서 유효한 product_id를 가져야 합니다.
혼합 Checkout: 동일한 Checkout 세션에서 일회성 결제 제품과 구독 제품을 결합할 수 있습니다. 이를 통해 구독과 함께 설정 수수료, 하드웨어 번들 및 기타 강력한 사용 사례를 가능하게 합니다.
제품 ID 찾기: Dodo Payments 대시보드의 제품 → 세부정보 보기에서 제품 ID를 찾거나 제품 목록 API를 사용하여 찾을 수 있습니다.

선택적 필드

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

사용 예시

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

1. 간단한 단일 제품 Checkout

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_ebook_guide',
      quantity: 1
    }
  ],
  customer: {
    email: 'customer@example.com',
    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: 'customer@example.com',
    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: 'user@startup.com',
    name: 'Jane Smith'
  },
  return_url: 'https://saas-app.com/onboarding',
  metadata: {
    plan_type: 'professional',
    referral_source: 'google_ads'
  }
});

4. 사전 확인된 Checkout

confirmtrue로 설정되면 고객은 확인 단계를 건너뛰고 Checkout 페이지로 직접 이동합니다.
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_premium_course',
      quantity: 1
    }
  ],
  customer: {
    email: 'student@university.edu',
    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. 통화 재정의가 있는 Checkout

billing_currency 재정의는 계정 설정에서 적응형 통화가 활성화된 경우에만 적용됩니다. 적응형 통화가 비활성화된 경우 이 매개변수는 효과가 없습니다.
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_consulting_service',
      quantity: 1
    }
  ],
  customer: {
    email: 'client@company.co.uk',
    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: 'returning.customer@example.com',
    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 Checkout

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_enterprise_license',
      quantity: 5
    }
  ],
  customer: {
    email: 'procurement@enterprise.com',
    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: 'john.sales@company.com'
  }
});

8. 할인 코드가 있는 다크 테마 Checkout

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: 'gamer@example.com',
    name: 'Mike Chen'
  },
  return_url: 'https://gaming-store.com/order-complete'
});

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

UPI 구성 및 테스트에 대한 자세한 내용은 인도 결제 방법 페이지를 참조하세요.
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_online_course_hindi',
      quantity: 1
    }
  ],
  allowed_payment_method_types: [
    'upi_collect',
    'credit',
    'debit'
  ],
  customer: {
    email: 'student@example.in',
    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 (지금 사서 나중에 결제하기) 체크아웃

BNPL 구성 및 테스트에 대한 자세한 내용은 지금 사서 나중에 결제하기 (BNPL) 페이지를 참조하세요.
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_luxury_watch',
      quantity: 1
    }
  ],
  allowed_payment_method_types: [
    'klarna',
    'afterpay_clearpay',
    'credit',
    'debit'
  ],
  customer: {
    email: 'fashion.lover@example.com',
    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: 'customer@example.com',
    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: 'customer@example.com',
    name: 'Jane Smith'
  }
});
사용자 정의 성공 페이지가 기본 결제 성공 페이지보다 더 나은 사용자 경험을 제공하는 경우 redirect_immediately: true를 사용하세요. 이는 특히 모바일 앱과 임베디드 체크아웃 흐름에 유용합니다.
redirect_immediately가 활성화되면, 고객은 결제가 완료된 즉시 당신의 return_url로 리디렉션되며 기본 성공 페이지를 완전히 건너뜁니다.

체크아웃 세션 미리 보기

체크아웃 세션을 생성하기 전에 세금, 할인 및 총액을 포함한 가격 분 breakdown을 미리 볼 수 있습니다. 이는 고객이 체크아웃을 진행하기 전에 정확한 가격을 표시하는 데 유용합니다.
const preview = await client.checkoutSessions.preview({
  product_cart: [
    { product_id: 'prod_123', quantity: 1 }
  ],
  billing_address: {
    country: 'US',
    state: 'CA',
    zipcode: '94102'
  },
  discount_code: 'SAVE20'
});

console.log('Subtotal:', preview.subtotal);
console.log('Tax:', preview.tax);
console.log('Discount:', preview.discount);
console.log('Total:', preview.total);

미리 보기 API 참조

전체 미리 보기 엔드포인트 문서를 확인하세요.

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

주요 차이점

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

마이그레이션 프로세스

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

통합 업데이트

새로운 API 또는 SDK 방법을 사용하도록 통합을 업데이트하세요.
2

요청 페이로드 조정

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

그게 전부입니다!

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