Chuyển đến nội dung chính
Thời gian hiệu lực của phiên: Các phiên thanh toán có hiệu lực trong 24 giờ theo mặc định. Nếu bạn truyền confirm=true trong yêu cầu của bạn, phiên sẽ chỉ có hiệu lực trong 15 phút.

Điều kiện tiên quyết

1

Tài khoản Dodo Payments

Bạn sẽ cần một tài khoản thương nhân Dodo Payments hoạt động với quyền truy cập API.
2

Thông tin xác thực API

Tạo thông tin xác thực API của bạn từ bảng điều khiển Dodo Payments:
3

Cài đặt Sản phẩm

Tạo sản phẩm của bạn trong bảng điều khiển Dodo Payments trước khi triển khai các phiên thanh toán.

Tạo Phiên Thanh toán Đầu tiên của Bạn

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' });
  }
});

Phản hồi API

Tất cả các phương thức trên đều trả về cùng một cấu trúc phản hồi:
{
  "session_id": "cks_Gi6KGJ2zFJo9rq9Ukifwa",
  "checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"
}
1

Lấy URL thanh toán

Trích xuất checkout_url từ phản hồi API.
2

Chuyển hướng khách hàng của bạn

Chuyển hướng khách hàng của bạn đến URL thanh toán để hoàn tất giao dịch của họ.
// Redirect immediately
window.location.href = session.checkout_url;

// Or open in new window
window.open(session.checkout_url, '_blank');
Tùy chọn tích hợp thay thế: Thay vì chuyển hướng, bạn có thể nhúng thanh toán trực tiếp vào trang của bạn bằng cách sử dụng Overlay Checkout (overlay modal) hoặc Inline Checkout (hoàn toàn nhúng). Cả hai tùy chọn đều sử dụng cùng một URL phiên thanh toán.
3

Xử lý việc trở lại

Sau khi thanh toán, khách hàng sẽ được chuyển hướng đến return_url của bạn với các tham số truy vấn bổ sung cho trạng thái thanh toán.

Thân bài yêu cầu

Trường bắt buộc

Các trường thiết yếu cần thiết cho mỗi phiên thanh toán

Trường tùy chọn

Cấu hình bổ sung để tùy chỉnh trải nghiệm thanh toán của bạn

Trường bắt buộc

product_cart
array
bắt buộc
Mảng các sản phẩm để bao gồm trong phiên thanh toán. Mỗi sản phẩm phải có một product_id hợp lệ từ bảng điều khiển Dodo Payments của bạn.
Thanh toán hỗn hợp: Bạn có thể kết hợp các sản phẩm thanh toán một lần và các sản phẩm đăng ký trong cùng một phiên thanh toán. Điều này cho phép các trường hợp sử dụng mạnh mẽ như phí thiết lập với các đăng ký, gói phần cứng với SaaS, và nhiều hơn nữa.
Tìm ID sản phẩm của bạn: Bạn có thể tìm ID sản phẩm trong bảng điều khiển Dodo Payments của bạn dưới Sản phẩm → Xem Chi tiết, hoặc bằng cách sử dụng List Products API.

Trường tùy chọn

Cấu hình các trường này để tùy chỉnh trải nghiệm thanh toán và thêm logic kinh doanh vào quy trình thanh toán của bạn.
customer
object
Thông tin khách hàng. Bạn có thể đính kèm một khách hàng hiện có bằng cách sử dụng ID của họ hoặc tạo một bản ghi khách hàng mới trong quá trình thanh toán.
Đính kèm một khách hàng hiện có vào phiên thanh toán bằng cách sử dụng ID của họ.
billing_address
object
Thông tin địa chỉ thanh toán để tính thuế chính xác, phòng ngừa gian lận và tuân thủ quy định.
Khi confirm được đặt thành true, tất cả các trường địa chỉ thanh toán trở thành bắt buộc để tạo phiên thành công.
allowed_payment_method_types
array
Kiểm soát các phương thức thanh toán nào có sẵn cho khách hàng trong quá trình thanh toán. Điều này giúp tối ưu hóa cho các thị trường hoặc yêu cầu kinh doanh cụ thể.Các tùy chọn có sẵn: 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
Quan trọng: Luôn bao gồm creditdebit như các tùy chọn dự phòng để ngăn chặn các lỗi thanh toán khi các phương thức thanh toán ưu tiên không khả dụng.
Ví dụ:
["apple_pay", "google_pay", "credit", "debit"]
billing_currency
string
Ghi đè lựa chọn tiền tệ mặc định bằng một loại tiền tệ thanh toán cố định. Sử dụng mã tiền tệ ISO 4217.Các loại tiền tệ được hỗ trợ: USD, EUR, GBP, CAD, AUD, INR, và nhiều hơn nữaVí dụ: "USD" cho Đô la Mỹ, "EUR" cho Euro
Trường này chỉ có hiệu lực khi giá cả thích ứng được kích hoạt. Nếu giá cả thích ứng bị vô hiệu hóa, loại tiền tệ mặc định của sản phẩm sẽ được sử dụng.
show_saved_payment_methods
boolean
mặc định:"false"
Hiển thị các phương thức thanh toán đã lưu trước đó cho khách hàng quay lại, cải thiện tốc độ thanh toán và trải nghiệm người dùng.
return_url
string
URL để chuyển hướng khách hàng sau khi thanh toán thành công hoặc hủy bỏ.
confirm
boolean
mặc định:"false"
Nếu đúng, hoàn tất tất cả các chi tiết phiên ngay lập tức. API sẽ ném ra lỗi nếu dữ liệu cần thiết bị thiếu.
discount_code
string
Áp dụng mã giảm giá cho phiên thanh toán.
metadata
object
Các cặp khóa-giá trị tùy chỉnh để lưu trữ thông tin bổ sung về phiên.
force_3ds
boolean
Ghi đè hành vi 3DS mặc định của thương nhân cho phiên này.
minimal_address
boolean
mặc định:"false"
Kích hoạt chế độ thu thập địa chỉ tối thiểu. Khi được kích hoạt, thanh toán chỉ thu thập:
  • Quốc gia: Luôn cần thiết để xác định thuế
  • Mã ZIP/Bưu chính: Chỉ ở những khu vực mà nó cần thiết cho việc tính thuế bán hàng, VAT hoặc GST
Điều này giảm đáng kể ma sát thanh toán bằng cách loại bỏ các trường biểu mẫu không cần thiết.
Kích hoạt địa chỉ tối thiểu để hoàn tất thanh toán nhanh hơn. Việc thu thập địa chỉ đầy đủ vẫn có sẵn cho các doanh nghiệp yêu cầu thông tin thanh toán đầy đủ.
customization
object
Tùy chỉnh giao diện và hành vi của giao diện thanh toán.
feature_flags
object
Cấu hình các tính năng và hành vi cụ thể cho phiên thanh toán.
subscription_data
object
Cấu hình bổ sung cho các phiên thanh toán chứa các sản phẩm đăng ký.

Ví dụ Sử dụng

Dưới đây là 10 ví dụ toàn diện trình bày các cấu hình phiên thanh toán khác nhau cho các kịch bản kinh doanh khác nhau:

1. Thanh toán Sản phẩm Đơn giản

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. Giỏ hàng Nhiều Sản phẩm

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. Đăng ký với Thời gian Dùng thử

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. Thanh toán Đã xác nhận trước

Khi confirm được đặt thành true, khách hàng sẽ được đưa trực tiếp đến trang thanh toán, bỏ qua bất kỳ bước xác nhận nào.
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. Thanh toán với Ghi đè Tiền tệ

Ghi đè billing_currency chỉ có hiệu lực khi tiền tệ thích ứng được kích hoạt trong cài đặt tài khoản của bạn. Nếu tiền tệ thích ứng bị vô hiệu hóa, tham số này sẽ không có tác dụng.
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. Các Phương thức Thanh toán Đã lưu cho Khách hàng Quay lại

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. Thanh toán B2B với Thu thập ID Thuế

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. Thanh toán Chủ đề Tối với Mã Giảm giá

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. Các Phương thức Thanh toán Khu vực (UPI cho Ấn Độ)

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: '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. Thanh toán BNPL (Mua ngay, Trả sau)

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: '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. Sử dụng Các Phương thức Thanh toán Hiện có cho Thanh toán Ngay lập tức

Sử dụng phương thức thanh toán đã lưu của khách hàng để tạo một phiên thanh toán xử lý ngay lập tức, bỏ qua việc thu thập phương thức thanh toán:
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'
});
Khi sử dụng payment_method_id, confirm phải được đặt thành true và một customer_id hiện có phải được cung cấp. Phương thức thanh toán sẽ được xác thực để kiểm tra tính đủ điều kiện với loại tiền tệ của thanh toán.
Phương thức thanh toán phải thuộc về khách hàng và tương thích với loại tiền tệ thanh toán. Điều này cho phép mua hàng một lần cho khách hàng quay lại.

12. Liên kết Ngắn cho Các URL Thanh toán Sạch hơn

Tạo các liên kết thanh toán ngắn gọn, có thể chia sẻ với các slug tùy chỉnh:
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
Liên kết ngắn rất hoàn hảo cho việc chia sẻ qua SMS, email hoặc mạng xã hội. Chúng dễ nhớ hơn và tạo dựng niềm tin hơn cho khách hàng so với các URL dài.

13. Bỏ qua Trang Thành công Thanh toán với Chuyển hướng Ngay lập tức

Chuyển hướng khách hàng ngay lập tức sau khi hoàn tất thanh toán, bỏ qua trang thành công mặc định:
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'
  }
});
Sử dụng redirect_immediately: true khi bạn có một trang thành công tùy chỉnh cung cấp trải nghiệm người dùng tốt hơn so với trang thành công thanh toán mặc định. Điều này đặc biệt hữu ích cho các ứng dụng di động và quy trình thanh toán nhúng.
Khi redirect_immediately được kích hoạt, khách hàng sẽ được chuyển hướng đến return_url của bạn ngay lập tức sau khi hoàn tất thanh toán, bỏ qua hoàn toàn trang thành công mặc định.

Xem trước Các Phiên Thanh toán

Trước khi tạo một phiên thanh toán, bạn có thể xem trước phân tích giá cả bao gồm thuế, giảm giá và tổng số. Điều này hữu ích để hiển thị giá chính xác cho khách hàng trước khi họ tiến hành thanh toán.
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);

Tài liệu API Xem trước

Xem tài liệu đầy đủ về điểm cuối xem trước.

Chuyển từ Liên kết Động sang Các Phiên Thanh toán

Sự khác biệt chính

Trước đây, khi tạo một liên kết thanh toán với Liên kết Động, bạn được yêu cầu cung cấp địa chỉ thanh toán đầy đủ của khách hàng. Với Các Phiên thanh toán, điều này không còn cần thiết. Bạn chỉ cần truyền bất kỳ thông tin nào bạn có, và chúng tôi sẽ xử lý phần còn lại. Ví dụ:
  • Nếu bạn chỉ biết quốc gia thanh toán của khách hàng, chỉ cần cung cấp điều đó.
  • Quy trình thanh toán sẽ tự động thu thập các chi tiết còn thiếu trước khi chuyển khách hàng đến trang thanh toán.
  • Mặt khác, nếu bạn đã có tất cả thông tin cần thiết và muốn bỏ qua trực tiếp đến trang thanh toán, bạn có thể truyền toàn bộ tập dữ liệu và bao gồm confirm=true trong thân yêu cầu của bạn.

Quy trình Di chuyển

Di chuyển từ Liên kết Động sang Các Phiên thanh toán là đơn giản:
1

Cập nhật tích hợp của bạn

Cập nhật tích hợp của bạn để sử dụng phương thức API hoặc SDK mới.
2

Điều chỉnh tải trọng yêu cầu

Điều chỉnh tải trọng yêu cầu theo định dạng của Các Phiên thanh toán.
3

Chỉ vậy thôi!

Đúng vậy. Không cần xử lý bổ sung hoặc các bước di chuyển đặc biệt nào khác từ phía bạn.