Bun Adaptor

Tìm hiểu cách tích hợp <CardGroup cols={2}> với dự án máy chủ Bun bằng Bun Adaptor của chúng tôi. Bao gồm checkout, Customer Portal, webhook và thiết lập môi trường an toàn.

Checkout Handler

Tích hợp checkout của Dodo Payments vào máy chủ Bun của bạn.

Customer Portal

Cho phép khách hàng quản lý các subscription và thông tin chi tiết.

Webhooks

Nhận và xử lý các sự kiện webhook của Dodo Payments.

​

Cài đặt

1. Install the package

   Chạy lệnh sau tại thư mục gốc của dự án:

   bun add @dodopayments/bun
   
2. Set up environment variables

   Tạo tệp .env tại thư mục gốc của dự án:

   DODO_PAYMENTS_API_KEY=your-api-key
   DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
   DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
   DODO_PAYMENTS_RETURN_URL=your-return-url
   

   Không bao giờ commit tệp .env hoặc secrets vào hệ thống quản lý phiên bản.

​

Ví dụ Route Handler

Tất cả ví dụ đều giả định bạn đang sử dụng máy chủ native của Bun với Bun.serve().

Checkout Handler

Sử dụng handler này để tích hợp checkout của Dodo Payments vào máy chủ Bun của bạn. Hỗ trợ các luồng thanh toán static (GET), dynamic (POST) và session (POST).

Bun Server Handler

import { Checkout } from '@dodopayments/bun';

const staticCheckoutHandler = Checkout({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    type: "static"
});

const sessionCheckoutHandler = Checkout({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    type: "session"
});

const dynamicCheckoutHandler = Checkout({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    type: "dynamic"
});

Bun.serve({
  port: 3000,
  fetch(request) {
    const url = new URL(request.url);
    
    if (url.pathname === "/api/checkout") {
      if (request.method === "GET") {
        return staticCheckoutHandler(request);
      }
      if (request.method === "POST") {
        return sessionCheckoutHandler(request);
        // or return dynamicCheckoutHandler(request);
      }
    }
    
    return new Response("Not Found", { status: 404 });
  },
});

Static Checkout Curl example

curl --request GET \
--url 'https://example.com/api/checkout?productId=pdt_xxx' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test

Dynamic Checkout Curl example

curl --request POST \
--url https://example.com/api/checkout \
--header 'Content-Type: application/json' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test \
--data '{
"billing": {
  "city": "Texas",
  "country": "US",
  "state": "Texas",
  "street": "56, hhh",
  "zipcode": "560000"
},
"customer": {
  "email": "[e-mail]",
  	"name": "test"
},
"metadata": {},
"payment_link": true,
  "product_id": "pdt_xxx",
  "quantity": 1,
  "billing_currency": "USD",
  "discount_codes": ["IKHZ23M9GQ"],
  "return_url": "https://example.com",
  "trial_period_days": 10
}'

Checkout Session Curl example

curl --request POST \
--url https://example.com/api/checkout \
--header 'Content-Type: application/json' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test \
--data '{
"product_cart": [
  {
    "product_id": "pdt_xxx",
    "quantity": 1
  }
],
"customer": {
  "email": "[e-mail]",
  "name": "test"
},
"return_url": "https://example.com/success"
}'

Customer Portal Handler

Sử dụng handler này để cho phép khách hàng quản lý các subscription và thông tin chi tiết của họ thông qua Customer Portal của Dodo Payments.

Bun Server Handler

import { CustomerPortal } from "@dodopayments/bun";

const customerPortalHandler = CustomerPortal({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
});

Bun.serve({
  port: 3000,
  fetch(request) {
    const url = new URL(request.url);
    
    if (url.pathname === "/api/customer-portal" && request.method === "GET") {
      return customerPortalHandler(request);
    }
    
    return new Response("Not Found", { status: 404 });
  },
});

Customer Portal Curl example

curl --request GET \
--url 'https://example.com/api/customer-portal?customer_id=cus_123&send_email=true' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test

Webhook Handler

Sử dụng handler này để nhận và xử lý an toàn các sự kiện webhook của Dodo Payments trong máy chủ Bun của bạn.

Bun Server Handler

import { Webhooks } from "@dodopayments/bun";

const webhookHandler = Webhooks({
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
  onPayload: async (payload) => {
    // handle the payload
  },
  // ... other event handlers for granular control
});

Bun.serve({
  port: 3000,
  fetch(request) {
    const url = new URL(request.url);
    
    if (url.pathname === "/api/webhook/dodo-payments" && request.method === "POST") {
      return webhookHandler(request);
    }
    
    return new Response("Not Found", { status: 404 });
  },
});

​

Checkout Route Handler

Dodo Payments hỗ trợ ba loại luồng thanh toán để tích hợp thanh toán vào website của bạn; adaptor này hỗ trợ tất cả các loại luồng thanh toán.

• Liên kết thanh toán static: URL có thể chia sẻ ngay để thu tiền nhanh chóng mà không cần code.
• Liên kết thanh toán dynamic: Tạo liên kết thanh toán theo chương trình với thông tin tùy chỉnh bằng API hoặc SDK.
• Checkout Sessions: Tạo trải nghiệm checkout được lưu trữ an toàn và có thể tùy chỉnh, với giỏ sản phẩm và thông tin khách hàng được cấu hình trước.

Static Checkout (GET)

​

Query Parameters được hỗ trợ

productId · string · bắt buộc

Mã định danh sản phẩm (ví dụ: ?productId=pdt_xxx).

quantity · integer

Số lượng sản phẩm.

fullName · string

Họ tên đầy đủ của khách hàng.

firstName · string

Tên của khách hàng.

lastName · string

Họ của khách hàng.

email · string

Địa chỉ email của khách hàng.

country · string

Quốc gia của khách hàng.

addressLine · string

Dòng địa chỉ của khách hàng.

city · string

Thành phố của khách hàng.

state · string

Bang/tỉnh của khách hàng.

zipCode · string

Mã ZIP/mã bưu chính của khách hàng.

disableFullName · boolean

Tắt trường họ tên đầy đủ.

disableFirstName · boolean

Tắt trường tên.

disableLastName · boolean

Tắt trường họ.

disableEmail · boolean

Tắt trường email.

disableCountry · boolean

Tắt trường quốc gia.

disableAddressLine · boolean

Tắt dòng địa chỉ.

disableCity · boolean

Tắt trường thành phố.

disableState · boolean

Tắt trường bang.

disableZipCode · boolean

Tắt trường mã ZIP.

paymentCurrency · string

Chỉ định currency thanh toán (ví dụ: USD).

showCurrencySelector · boolean

Hiển thị bộ chọn currency.

paymentAmount · integer

Chỉ định số tiền thanh toán (ví dụ: 1000 cho $10.00).

showDiscounts · boolean

Hiển thị các trường giảm giá.

metadata_* · string

Mọi query parameter bắt đầu bằng metadata_ sẽ được truyền dưới dạng metadata.

Nếu thiếu productId, handler sẽ trả về response 400. Query parameter không hợp lệ cũng dẫn đến response 400.

​

Định dạng response

Checkout static trả về response JSON với URL checkout:

{
  "checkout_url": "https://checkout.dodopayments.com/..."
}

Dynamic Checkout (POST)

• Gửi các tham số dưới dạng JSON body trong request POST.
• Hỗ trợ cả thanh toán một lần và thanh toán định kỳ.
• Để xem danh sách đầy đủ các field được hỗ trợ trong POST body, tham khảo:
  • Request body cho sản phẩm thanh toán một lần
  • Request body cho sản phẩm subscription

​

Định dạng response

Checkout dynamic trả về response JSON với URL checkout:

{
  "checkout_url": "https://checkout.dodopayments.com/..."
}

Checkout Sessions (POST)

Checkout sessions cung cấp trải nghiệm checkout được lưu trữ an toàn hơn, xử lý toàn bộ luồng thanh toán cho cả giao dịch mua một lần và subscription, đồng thời cho phép tùy chỉnh toàn diện.

Tham khảo Hướng dẫn tích hợp Checkout Sessions để biết thêm chi tiết và xem danh sách đầy đủ các field được hỗ trợ.

​

Định dạng response

Checkout sessions trả về response JSON với URL checkout:

{
  "checkout_url": "https://checkout.dodopayments.com/session/..."
}

​

Customer Portal Route Handler

Customer Portal Route Handler cho phép bạn tích hợp liền mạch Customer Portal của Dodo Payments vào ứng dụng máy chủ Bun.

​

Query Parameters

customer_id · string · bắt buộc

ID khách hàng cho portal session (ví dụ: ?customer_id=cus_123).

send_email · boolean

Nếu được đặt thành true, sẽ gửi email cho khách hàng kèm liên kết portal.

Trả về 400 nếu thiếu customer_id.

​

Webhook Route Handler

• Method: Chỉ hỗ trợ request POST. Các method khác sẽ trả về 405.
• Xác minh chữ ký: Xác minh chữ ký webhook bằng webhookKey. Trả về 401 nếu xác minh thất bại.
• Xác thực payload: Được xác thực bằng Zod. Trả về 400 nếu payload không hợp lệ.
• Xử lý lỗi:
  • 401: Chữ ký không hợp lệ
  • 400: Payload không hợp lệ
  • 500: Lỗi nội bộ trong quá trình xác minh
• Định tuyến sự kiện: Gọi event handler phù hợp dựa trên loại payload.

​

Event Handler webhook được hỗ trợ

Typescript

onPayload?: (payload: WebhookPayload) => Promise<void>;
onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>;
onPaymentFailed?: (payload: WebhookPayload) => Promise<void>;
onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>;
onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>;
onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>;
onRefundFailed?: (payload: WebhookPayload) => Promise<void>;
onDisputeOpened?: (payload: WebhookPayload) => Promise<void>;
onDisputeExpired?: (payload: WebhookPayload) => Promise<void>;
onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>;
onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>;
onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>;
onDisputeWon?: (payload: WebhookPayload) => Promise<void>;
onDisputeLost?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>;
onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>;
onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>;
onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>;
onDunningStarted?: (payload: WebhookPayload) => Promise<void>;
onDunningRecovered?: (payload: WebhookPayload) => Promise<void>;
onCreditAdded?: (payload: WebhookPayload) => Promise<void>;
onCreditDeducted?: (payload: WebhookPayload) => Promise<void>;
onCreditExpired?: (payload: WebhookPayload) => Promise<void>;
onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>;
onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>;
onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>;
onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>;
onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>;

---

​

Prompt cho LLM

You are an expert Bun developer assistant. Your task is to guide a user through integrating the @dodopayments/bun adapter into their existing Bun project.

The @dodopayments/bun adapter provides handlers for Dodo Payments' Checkout, Customer Portal, and Webhook functionalities, designed for Bun's native server with Bun.serve().

First, install the necessary package:

bun add @dodopayments/bun

Here's how you should structure your response:

    Ask the user which functionalities they want to integrate.

"Which parts of the @dodopayments/bun adapter would you like to integrate into your project? You can choose one or more of the following:
1. Checkout (static, dynamic, or session-based)
2. Customer Portal
3. Webhooks"

    Based on the user's selection, provide step-by-step integration instructions.

For each selected functionality, show:

    The environment variables required
    The exact code to add to their server file
    Where to place the code in their Bun.serve() configuration

Provide complete, working examples that the user can copy and paste directly into their project.

    Environment Variables Setup

Always include instructions for setting up the .env file:

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
DODO_PAYMENTS_RETURN_URL=your-return-url

Remind the user to never commit their .env file to version control.

    For Checkout Integration

If the user selects Checkout, ask which type they need:

    Static checkout (GET requests with query parameters)
    Dynamic checkout (POST requests with JSON body)
    Checkout sessions (POST requests with product cart)

Provide the appropriate handler code for their selection.

    For Customer Portal Integration

Provide a complete example showing how to integrate the customer portal handler into their Bun server.

    For Webhook Integration

Provide a complete example showing how to integrate the webhook handler with available event handlers for granular control.

    Full Example

If the user wants to integrate all three functionalities, provide a complete Bun server example that combines all handlers.

```typescript
import { Checkout, CustomerPortal, Webhooks } from "@dodopayments/bun";

const staticCheckoutHandler = Checkout({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "static",
});

const sessionCheckoutHandler = Checkout({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "session",
});

const customerPortalHandler = CustomerPortal({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
});

const webhookHandler = Webhooks({
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
  onPaymentSucceeded: async (payload) => {
    console.log("Payment succeeded:", payload);
    // Your business logic here
  },
  onSubscriptionActive: async (payload) => {
    console.log("Subscription activated:", payload);
    // Your business logic here
  },
});

Bun.serve({
  port: 3000,
  fetch(request) {
    const url = new URL(request.url);
    
    // Checkout routes
    if (url.pathname === "/api/checkout") {
      if (request.method === "GET") {
        return staticCheckoutHandler(request);
      }
      if (request.method === "POST") {
        return sessionCheckoutHandler(request);
      }
    }
    
    // Customer portal route
    if (url.pathname === "/api/customer-portal" && request.method === "GET") {
      return customerPortalHandler(request);
    }
    
    // Webhook route
    if (url.pathname === "/api/webhook/dodo-payments" && request.method === "POST") {
      return webhookHandler(request);
    }
    
    return new Response("Not Found", { status: 404 });
  },
});

console.log("Server running on http://localhost:3000");

Additional Guidance:
• Explain that the handlers are Bun-native and work seamlessly with Bun.serve()
• Highlight the use of Web Standard Request and Response objects
• Mention that error handling is built-in and returns appropriate HTTP status codes
• Provide links to the Dodo Payments documentation for more details