Hono Adaptor - Dodo Payments Documentation

Checkout Handler

Integrasikan checkout Dodo Payments ke dalam aplikasi Hono Anda.

Customer Portal

Izinkan pelanggan mengelola langganan dan detail.

Webhooks

Terima dan proses peristiwa webhook Dodo Payments.

Instalasi

Install the package

Jalankan perintah berikut di root proyek Anda:

npm install @dodopayments/hono

Set up environment variables

Buat file .env di root proyek Anda:

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_RETURN_URL=https://yourapp.com/success
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode""

Jangan pernah commit file .env atau rahasia Anda ke kontrol versi.

Contoh Pengelola Rute

Semua contoh mengasumsikan Anda menggunakan Hono App Router.

Checkout Handler
Customer Portal Handler
Webhook Handler

Gunakan handler ini untuk mengintegrasikan checkout Dodo Payments ke dalam aplikasi Hono Anda. Mendukung alur statis (GET), dinamis (POST), dan sesi (POST).

  // route.ts
  import { Checkout } from '@dodopayments/hono';
  import Hono from 'hono'

  const app = new Hono()

  app.get(
  "/api/checkout",
  Checkout({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY,
      environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
      returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
      type: 'static'
  })
  );

  app.post(
  "/api/checkout",
  Checkout({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY,
      environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
      returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
      type: 'dynamic'
  })
  );
  
  app.post(
  "/api/checkout",
  Checkout({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY,
      environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
      returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
      type: 'session'
  })
  );

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

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": "test@example.com",
  	"name": "test"
},
"metadata": {},
"payment_link": true,
  "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
  "quantity": 1,
  "billing_currency": "USD",
  "discount_codes": ["IKHZ23M9GQ"],
  "return_url": "https://example.com",
  "trial_period_days": 10
}'

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_QMDuvLkbVzCRWRQjLNcs",
    "quantity": 1
  }
],
"customer": {
  "email": "test@example.com",
  "name": "test"
},
"return_url": "https://example.com/success"
}'

Gunakan handler ini untuk memungkinkan pelanggan mengelola langganan dan detail mereka melalui portal pelanggan Dodo Payments.

// route.ts
import { Checkout } from '@dodopayments/hono';
import Hono from 'hono'

const app = new Hono()
app.get(
    "/api/customer-portal",
    CustomerPortal({
        bearerToken: process.env.DODO_PAYMENTS_API_KEY,
        environment: process.env.DODO_PAYMENTS_ENVIRONMENT
    })
);

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

Gunakan handler ini untuk menerima dan memproses peristiwa webhook Dodo Payments secara aman di aplikasi Hono Anda.

// route.ts
import Hono from 'hono'
import { Webhooks } from '@dodopayments/hono'

const app = new Hono()
app.post(
"/api/webhooks",
    Webhooks({
        webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
        onPayload: async (payload) => {
        // Handle Payload Here
        console.log(payload)
        }
    })
);

Pengelola Rute Checkout

Dodo Payments mendukung tiga jenis alur pembayaran untuk mengintegrasikan pembayaran ke situs web Anda, adaptor ini mendukung semua jenis alur pembayaran.

Tautan Pembayaran Statis: URL yang dapat dibagikan secara instan untuk pengumpulan pembayaran cepat tanpa kode.
Tautan Pembayaran Dinamis: Menghasilkan tautan pembayaran secara programatis dengan detail kustom menggunakan API atau SDK.
Sesi Checkout: Buat pengalaman checkout yang aman dan dapat disesuaikan dengan keranjang produk dan detail pelanggan yang telah dikonfigurasi sebelumnya.

Static Checkout (GET)

Supported Query Parameters

productId

string

wajib

Pengidentifikasi produk (misalnya ?productId=pdt_nZuwz45WAs64n3l07zpQR).

quantity

integer

Jumlah produk.

fullName

string

Nama lengkap pelanggan.

firstName

string

Nama depan pelanggan.

lastName

string

Nama belakang pelanggan.

string

Alamat email pelanggan.

country

string

Negara pelanggan.

addressLine

string

Baris alamat pelanggan.

city

string

Kota pelanggan.

state

string

Negara bagian/provinsi pelanggan.

zipCode

string

Kode pos pelanggan.

disableFullName

boolean

Nonaktifkan bidang nama lengkap.

disableFirstName

boolean

Nonaktifkan bidang nama depan.

disableLastName

boolean

Nonaktifkan bidang nama belakang.

disableEmail

boolean

Nonaktifkan bidang email.

disableCountry

boolean

Nonaktifkan bidang negara.

disableAddressLine

boolean

Nonaktifkan bidang baris alamat.

disableCity

boolean

Nonaktifkan bidang kota.

disableState

boolean

Nonaktifkan bidang negara bagian.

disableZipCode

boolean

Nonaktifkan bidang kode pos.

paymentCurrency

string

Tentukan mata uang pembayaran (misalnya USD).

showCurrencySelector

boolean

Tampilkan pemilih mata uang.

paymentAmount

integer

Tentukan jumlah pembayaran (misalnya 1000 untuk $10,00).

showDiscounts

boolean

Tampilkan bidang diskon.

metadata_*

string

Setiap parameter kueri yang dimulai dengan metadata_ akan diteruskan sebagai metadata.

Jika productId hilang, handler mengembalikan respons 400. Parameter kueri yang tidak valid juga menghasilkan respons 400.

Format Respons

Checkout statis mengembalikan respons JSON dengan URL checkout:

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

Dynamic Checkout (POST)

Kirim parameter sebagai body JSON dalam permintaan POST.
Mendukung pembayaran satu kali dan berulang.
Untuk daftar lengkap bidang body POST yang didukung, lihat:
- Request body for a One Time Payment Product
- Request body for a Subscription Product

Format Respons

Checkout dinamis mengembalikan respons JSON dengan URL checkout:

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

Checkout Sessions (POST)

Sesi checkout menyediakan pengalaman checkout yang lebih aman dan dihosting yang menangani seluruh alur pembayaran untuk pembelian satu kali maupun langganan dengan kontrol kustomisasi penuh.Lihat Panduan Integrasi Sesi Checkout untuk detail lebih lanjut dan daftar lengkap bidang yang didukung.

Format Respons

Sesi checkout mengembalikan respons JSON dengan URL checkout:

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

Pengelola Rute Portal Pelanggan

Pengelola Rute Portal Pelanggan memungkinkan Anda untuk mengintegrasikan portal pelanggan Dodo Payments ke dalam aplikasi Hono Anda dengan mulus.

Query Parameters

customer_id

string

wajib

ID pelanggan untuk sesi portal (misalnya ?customer_id=cus_123).

send_email

boolean

Jika disetel ke true, mengirim email kepada pelanggan dengan tautan portal.

Mengembalikan 400 jika customer_id hilang.

Pengelola Rute Webhook

Metode: Hanya permintaan POST yang didukung. Metode lain mengembalikan 405.
Verifikasi Tanda Tangan: Memverifikasi tanda tangan webhook menggunakan webhookKey. Mengembalikan 401 jika verifikasi gagal.
Validasi Payload: Divalidasi dengan Zod. Mengembalikan 400 untuk payload yang tidak valid.
Penanganan Kesalahan:
- 401: Tanda tangan tidak valid
- 400: Payload tidak valid
- 500: Kesalahan internal selama verifikasi
Pengarahan Acara: Memanggil pengelola acara yang sesuai berdasarkan jenis payload.

Handler Peristiwa Webhook yang Didukung

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>;
onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>;

Prompt untuk LLM

Anda adalah asisten pengembang Hono yang ahli. Tugas Anda adalah membimbing pengguna melalui integrasi adaptor @dodopayments/hono ke dalam proyek Hono mereka yang sudah ada.

Adaptor @dodopayments/hono menyediakan pengelola rute untuk Checkout Dodo Payments, Portal Pelanggan, dan fungsionalitas Webhook, dirancang untuk terhubung langsung ke aplikasi Hono.

Pertama, instal paket yang diperlukan. Gunakan manajer paket yang sesuai untuk proyek pengguna (npm, yarn, atau bun):

npm install @dodopayments/hono

---

Berikut adalah cara Anda harus menyusun respons Anda:

1. Tanyakan kepada pengguna fungsi mana yang ingin mereka integrasikan.

"Bagian mana dari adaptor @dodopayments/hono yang ingin Anda integrasikan ke dalam proyek Anda? Anda dapat memilih satu atau lebih dari yang berikut:

- Pengelola Rute Checkout (untuk menangani checkout produk)
- Pengelola Rute Portal Pelanggan (untuk mengelola langganan/detail pelanggan)
- Pengelola Rute Webhook (untuk menerima acara webhook Dodo Payments)
- Semua (integrasikan ketiga-tiganya)"

---

2. Berdasarkan pilihan pengguna, berikan langkah-langkah integrasi yang rinci untuk setiap fungsionalitas yang dipilih.

---

**Jika Pengelola Rute Checkout dipilih:**

**Tujuan**: Pengelola ini mengarahkan pengguna ke halaman checkout Dodo Payments.

**Integrasi**:
Buat dua rute di aplikasi Hono Anda — satu untuk checkout statis (GET) dan satu untuk checkout dinamis (POST).

import { Checkout } from '@dodopayments/hono';
import Hono from 'hono'

const app = new Hono()

app.get(
  "/api/checkout",
  Checkout({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    type: 'static'
  })
);

app.post(
  "/api/checkout",
  Checkout({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    type: 'session' // atau 'dynamic' untuk tautan dinamis
  })
);

Opsi Konfigurasi:

    bearerToken: Kunci API Dodo Payments Anda (disarankan untuk disimpan dalam variabel lingkungan DODO_PAYMENTS_API_KEY).

    returnUrl (opsional): URL untuk mengarahkan pengguna setelah checkout berhasil.

    environment: "test_mode" atau "live_mode"

    type: "static" (GET) atau "dynamic" (POST) atau "session" (POST)

GET (checkout statis) mengharapkan parameter kuery:

    productId (wajib)

    quantity, kolom pelanggan (fullName, email, dll.), dan metadata (metadata_*) adalah opsional.

POST (checkout dinamis) mengharapkan body JSON dengan detail pembayaran (satu kali atau langganan). Referensi dokumen untuk skema POST lengkap:

    Pembayaran satu kali: https://docs.dodopayments.com/api-reference/payments/post-payments

    Langganan: https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions

POST (sesi checkout) - (Direkomendasikan) Pengalaman checkout yang lebih dapat disesuaikan. Mengembalikan JSON dengan checkout_url: Parameter dikirim sebagai body JSON. Mendukung pembayaran satu kali dan berulang. Mengembalikan: {"checkout_url": "https://checkout.dodopayments.com/session/..."}. Untuk daftar lengkap bidang yang didukung, lihat:

  Panduan Integrasi Sesi Checkout: https://docs.dodopayments.com/developer-resources/checkout-session

Jika Pengelola Rute Portal Pelanggan dipilih:

Tujuan: Rute ini memungkinkan pelanggan untuk mengelola langganan mereka melalui portal Dodo Payments.

Integrasi:

import { Checkout } from '@dodopayments/hono';
import Hono from 'hono'

const app = new Hono()
app.get(
  "/api/customer-portal",
  CustomerPortal({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT
  })
);

Parameter Kuery:

    customer_id (wajib): misalnya, ?customer_id=cus_123

    send_email (opsional): jika true, pelanggan akan dikirim email tautan portal

Mengembalikan 400 jika customer_id hilang.

Jika Pengelola Rute Webhook dipilih:

Tujuan: Memproses acara webhook yang masuk dari Dodo Payments untuk memicu acara di aplikasi Anda.

Integrasi:

import Hono from 'hono'
import { Webhooks } from '@dodopayments/hono'

const app = new Hono()
app.post(
  "/api/webhooks",
  Webhooks({
    webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
    onPayload: async (payload) => {
      // Tangani Payload Di Sini
      console.log(payload)
    }
  })
);

Fitur:

    Hanya metode POST yang diizinkan — yang lain mengembalikan 405

    Verifikasi tanda tangan dilakukan menggunakan webhookKey. Mengembalikan 401 jika tidak valid.

    Validasi payload berbasis Zod. Mengembalikan 400 jika skema tidak valid.

    Semua pengelola adalah fungsi async.

Pengelola Acara Webhook yang Didukung:

Anda dapat meneruskan salah satu pengelola berikut:

    onPayload

    onPaymentSucceeded

    onPaymentFailed

    onPaymentProcessing

    onPaymentCancelled

    onRefundSucceeded

    onRefundFailed

    onDisputeOpened, onDisputeExpired, onDisputeAccepted, onDisputeCancelled, onDisputeChallenged, onDisputeWon, onDisputeLost

    onSubscriptionActive, onSubscriptionOnHold, onSubscriptionRenewed, onSubscriptionPaused, onSubscriptionPlanChanged, onSubscriptionCancelled, onSubscriptionFailed, onSubscriptionExpired

    onLicenseKeyCreated

Pengaturan Variabel Lingkungan:

Pastikan untuk mendefinisikan variabel lingkungan ini di proyek Anda:

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_RETURN_URL=https://yourapp.com/success
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" atau "live_mode""

Gunakan ini di dalam kode Anda sebagai:

process.env.DODO_PAYMENTS_API_KEY
process.env.DODO_PAYMENTS_WEBHOOK_KEY

Catatan Keamanan: JANGAN mengkomit rahasia ke kontrol versi. Gunakan file .env secara lokal dan manajer rahasia di lingkungan penyebaran (misalnya, AWS, Vercel, Heroku, dll.).

Gunakan ini di dalam kode Anda sebagai:

process.env.DODO_PAYMENTS_API_KEY
process.env.DODO_PAYMENTS_WEBHOOK_KEY

Catatan Keamanan: Jangan mencatat rahasia ke kontrol versi. Gunakan file .env secara lokal dan pengelola rahasia di lingkungan penerapan (misalnya, AWS, Vercel, Heroku, dll.).

Checkout Handler

Customer Portal

Webhooks

​Instalasi

​Contoh Pengelola Rute

​Pengelola Rute Checkout

​Supported Query Parameters

​Format Respons

​Format Respons

​Format Respons

​Pengelola Rute Portal Pelanggan

​Query Parameters

​Pengelola Rute Webhook

​Handler Peristiwa Webhook yang Didukung

​Prompt untuk LLM

Instalasi

Contoh Pengelola Rute

Pengelola Rute Checkout

Supported Query Parameters

Format Respons

Format Respons

Format Respons

Pengelola Rute Portal Pelanggan

Query Parameters

Pengelola Rute Webhook

Handler Peristiwa Webhook yang Didukung

Prompt untuk LLM