Astro Minimal Boilerplate - Dodo Payments Documentation

Ikhtisar

Boilerplate Astro minimal menyediakan titik awal yang siap digunakan untuk mengintegrasikan Dodo Payments dengan aplikasi Astro Anda. Template ini mencakup sesi checkout, penanganan webhook, portal pelanggan, dan komponen UI modern untuk membantu Anda mulai menerima pembayaran dengan cepat.

Boilerplate ini menggunakan Astro 5 dengan TypeScript, Tailwind CSS 4, dan adapter @dodopayments/astro.

Fitur

Quick Setup - Mulai dalam kurang dari 5 menit
Payment Integration - Alur checkout yang telah dikonfigurasi sebelumnya menggunakan @dodopayments/astro
Modern UI - Halaman harga bertema gelap yang bersih dengan Tailwind CSS
Webhook Handler - Endpoint webhook siap pakai untuk event pembayaran
Customer Portal - Manajemen langganan satu klik
TypeScript - Sepenuhnya bertipe dengan tipe minimal dan fokus
Pre-filled Checkout - Menunjukkan cara meneruskan data pelanggan untuk meningkatkan UX

Prasyarat

Sebelum Anda mulai, pastikan Anda memiliki:

Node.js versi LTS (diperlukan untuk Astro 5)
Akun Dodo Payments (untuk mengakses API dan Kunci Webhook dari dasbor)

Memulai dengan Cepat

Clone the Repository

git clone https://github.com/dodopayments/dodo-astro-minimal-boilerplate.git
cd dodo-astro-minimal-boilerplate

Install Dependencies

npm install

Get API Credentials

Daftar di Dodo Payments dan dapatkan kredensial Anda dari dasbor:

Kunci API: Dasbor → Pengembang → Kunci API
Kunci Webhook: Dasbor → Pengembang → Webhook

Pastikan Anda berada dalam Test Mode saat mengembangkan!

Configure Environment Variables

Buat file .env di direktori root:

cp .env.example .env

Perbarui nilai dengan kredensial Dodo Payments Anda:

DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_key_here
DODO_PAYMENTS_RETURN_URL=http://localhost:4321/
DODO_PAYMENTS_ENVIRONMENT=test_mode

Jangan pernah meng-commit file .env Anda ke kontrol versi. File tersebut sudah termasuk dalam .gitignore.

Add Your Products

Perbarui src/lib/products.ts dengan ID produk Anda yang sebenarnya dari Dodo Payments:

export const products: Product[] = [
  {
    product_id: "pdt_001", // Replace with your product ID
    name: "Basic Plan",
    description: "Get access to basic features and support",
    price: 9999, // in cents
    features: [
      "Access to basic features",
      "Email support",
      "1 Team member",
      "Basic analytics",
    ],
  },
  // ... add more products
];

Run the Development Server

npm run dev

Buka http://localhost:4321 untuk melihat halaman harga Anda!

Struktur Proyek

src/
├── components/
│   ├── Footer.astro           # Reusable footer
│   ├── Header.astro           # Navigation header
│   └── ProductCard.astro      # Product pricing card
├── layouts/
│   └── Layout.astro           # Root layout
├── lib/
│   └── products.ts            # Product definitions
├── pages/
│   ├── index.astro            # Pricing page (home)
│   └── api/
│       ├── checkout.ts        # Checkout session handler
│       ├── customer-portal.ts # Customer portal redirect
│       └── webhook.ts         # Webhook event handler
└── styles/
    └── global.css             # Global styles with Tailwind

Kustomisasi

Perbarui Informasi Produk

Sunting src/lib/products.ts untuk mengubah:

ID Produk (dari dasbor Dodo Anda)
Harga
Fitur
Deskripsi

Isi Data Pelanggan

Di src/components/ProductCard.astro, gantilah nilai yang dikodekan langsung dengan data pengguna Anda yang sebenarnya:

customer: {
  name: "John Doe",
  email: "john@example.com",
},

Perbarui Portal Pelanggan

Di src/components/Header.astro, gantilah ID pelanggan yang dikodekan langsung dengan ID pelanggan aktual dari sistem otentikasi atau basis data Anda:

const CUSTOMER_ID = "cus_001"; // Replace with actual customer ID

Anda dapat menyelesaikan pembelian uji untuk mendapatkan ID pelanggan untuk pengujian.

Peristiwa Webhook

Boilerplate ini menunjukkan penanganan event webhook di src/pages/api/webhook.ts:

onSubscriptionActive - Dipicu ketika sebuah langganan menjadi aktif
onSubscriptionCancelled - Dipicu ketika sebuah langganan dibatalkan

Tambahkan logika bisnis Anda di dalam penangan ini:

onSubscriptionActive: async (payload) => {
  // Grant access to your product
  // Update user database
  // Send welcome email
},

Tambahkan lebih banyak peristiwa webhook sesuai kebutuhan. Untuk pengembangan lokal, Anda dapat menggunakan alat seperti ngrok untuk membuat terowongan aman ke server lokal Anda dan menggunakannya sebagai URL webhook Anda.

Penyebaran

Boilerplate ini menggunakan output statis dengan rendering sesuai permintaan untuk rute API. Anda perlu menginstal adapter untuk platform penyebaran Anda:

Platform	Panduan
Vercel	Deploy to Vercel
Netlify	Deploy to Netlify
Cloudflare	Deploy to Cloudflare

Lihat panduan penyebaran Astro untuk semua platform.

Perbarui URL Webhook

Setelah penyebaran, perbarui URL webhook Anda di Dasbor Dodo Payments:

https://your-domain.com/api/webhook

Juga ingat untuk memperbarui variabel lingkungan DODO_PAYMENTS_WEBHOOK_KEY di lingkungan produksi Anda agar sesuai dengan kunci penandatanganan webhook untuk domain yang Anda deploy.

Pemecahan Masalah

Module not found or build errors

Hapus node_modules dan pasang kembali dependensi:

rm -rf node_modules package-lock.json
npm install

Checkout redirect fails

Penyebab umum:

ID produk tidak valid - pastikan ada di dasbor Dodo Anda
Kunci API atau pengaturan lingkungan yang salah di .env
Periksa konsol browser dan terminal untuk melihat kesalahan

Webhooks not receiving events

Untuk pengujian lokal, gunakan ngrok untuk mengekspos server Anda:

ngrok http 4321

Perbarui URL webhook di dasbor Dodo Anda ke URL ngrok. Ingat untuk memperbarui file .env Anda dengan kunci verifikasi webhook yang benar.

Customer portal link doesn't work

Ganti CUSTOMER_ID yang dikodekan langsung di src/components/Header.astro dengan ID pelanggan nyata dari dasbor Dodo Anda.Atau integrasikan sistem otentikasi dan basis data Anda untuk mengambil ID pelanggan secara dinamis.

Build fails with adapter error

Boilerplate ini menggunakan output statis dengan rute API sesuai permintaan. Anda perlu menginstal adapter untuk deployment:Lihat panduan deployment Astro untuk detail.

Pelajari Lebih Lanjut

Dukungan

Butuh bantuan dengan boilerplate?

Bergabunglah dengan komunitas Discord kami untuk pertanyaan dan diskusi
Periksa repositori GitHub untuk masalah dan pembaruan
Hubungi tim dukungan kami untuk bantuan

​Ikhtisar

​Fitur

​Prasyarat

​Memulai dengan Cepat

​Struktur Proyek

​Kustomisasi

​Perbarui Informasi Produk

​Isi Data Pelanggan

​Perbarui Portal Pelanggan

​Peristiwa Webhook

​Penyebaran

​Perbarui URL Webhook

​Pemecahan Masalah

​Pelajari Lebih Lanjut

​Dukungan

Ikhtisar

Fitur

Prasyarat

Memulai dengan Cepat

Struktur Proyek

Kustomisasi

Perbarui Informasi Produk

Isi Data Pelanggan

Perbarui Portal Pelanggan

Peristiwa Webhook

Penyebaran

Perbarui URL Webhook

Pemecahan Masalah

Pelajari Lebih Lanjut

Dukungan