medusa-payment-doit 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -6,6 +6,23 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-10-25
+
+### Changed
+
+- Peer dependencies widened to `^2.19.0` for the `@medusajs/*` packages (and `^4.2.1` for `@medusajs/ui`, which has
+  its own versioning), so the plugin installs on newer Medusa 2.x releases without overrides. Development still uses
+  the 2.19.0 lock.
+- The npm package now includes `examples/nextjs-starter` (components, `starter.patch` and its README), so the
+  storefront example is available in `node_modules/medusa-payment-doit/examples/nextjs-starter` without cloning
+  the repository.
+- npm keywords for the Medusa integrations directory: `medusa-plugin-integration`, `medusa-plugin-payment`.
+
+### Added
+
+- CI matrix running the unit and E2E suites on Medusa 2.19.0 and 2.22.0, with the package built on the locked
+  2.19.0 toolchain. `scripts/use-medusa-version.mjs` switches a checkout to another Medusa release for this.
+
 ## [0.1.0] - 2026-10-25
 
 First public beta (`npm install medusa-payment-doit@beta`). Requires Medusa 2.19.x.
@@ -37,5 +54,6 @@ First public beta (`npm install medusa-payment-doit@beta`). Requires Medusa 2.19
 - Example components for the Medusa Next.js Starter (`examples/nextjs-starter`).
 - E2E suites against a mock doit.id and an opt-in sandbox suite; CI on every push and pull request.
 
-[Unreleased]: https://github.com/haustex/pg-medusa-doit/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/haustex/pg-medusa-doit/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/haustex/pg-medusa-doit/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/haustex/pg-medusa-doit/releases/tag/v0.1.0

package/README.md

@@ -5,7 +5,7 @@
 
 [![npm](https://img.shields.io/npm/v/medusa-payment-doit/beta?label=npm%40beta)](https://www.npmjs.com/package/medusa-payment-doit)
 [![CI](https://github.com/haustex/pg-medusa-doit/actions/workflows/ci.yml/badge.svg)](https://github.com/haustex/pg-medusa-doit/actions/workflows/ci.yml)
-[![Medusa](https://img.shields.io/badge/Medusa-2.19-7c3aed)](https://medusajs.com)
+[![Medusa](https://img.shields.io/badge/Medusa-2.19%20%E2%80%93%202.22-7c3aed)](https://medusajs.com)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
 ```bash
@@ -32,7 +32,7 @@ More: [settings](https://raw.githubusercontent.com/haustex/pg-medusa-doit/main/d
 
 ### Features
 
-- **Payment provider** for Medusa 2.19: QRIS, Virtual Account (8 banks), the doit.id hosted page (`any`), and bank
+- **Payment provider** for Medusa 2.19+: QRIS, Virtual Account (8 banks), the doit.id hosted page (`any`), and bank
   transfer (`transfer`, see [Limitations](#limitations)). Amounts are whole rupiah, exactly as Medusa stores them.
 - **Credentials in the Admin**, encrypted with AES-256-GCM. Falls back to provider options or env vars.
 - **Webhooks**: signature checked on the raw body (HMAC-SHA256, ±5 min), deduplicated by event id in the database,
@@ -50,7 +50,7 @@ More: [settings](https://raw.githubusercontent.com/haustex/pg-medusa-doit/main/d
 
 ### Requirements
 
-- Medusa **2.19.x**, Node 20.19+ or 22.12+
+- Medusa **2.19 or newer 2.x** (tested in CI on 2.19.0 and 2.22.0), Node 20.19+ or 22.12+
 - Redis for the event bus, workflow engine and locking (strongly recommended; webhooks are processed in the worker)
 - A doit.id account: `pb_test_…` key for the sandbox, `pb_live_…` for production
 
@@ -162,7 +162,8 @@ for the status, 20/min per cart and 30/min per IP for methods (in memory, per se
 once per 10 seconds per payment.
 
 **Medusa Next.js Starter:** copy-in components and a patch in
-[`examples/nextjs-starter`](examples/nextjs-starter/README.md).
+[`examples/nextjs-starter`](examples/nextjs-starter/README.md), also shipped in the npm package
+(`node_modules/medusa-payment-doit/examples/nextjs-starter`).
 
 Switching method creates a new invoice. Switching back to a method whose invoice is still open (same cart, same amount,
 VA with ≥5 minutes left, QRIS whose QR is still issued) reuses that invoice.
@@ -211,7 +212,7 @@ Report vulnerabilities privately: see [SECURITY.md](SECURITY.md).
 
 ### Fitur
 
-- **Payment provider** untuk Medusa 2.19: QRIS, Virtual Account (8 bank), halaman bayar hosted doit.id (`any`), dan
+- **Payment provider** untuk Medusa 2.19+: QRIS, Virtual Account (8 bank), halaman bayar hosted doit.id (`any`), dan
   transfer bank (`transfer`, lihat [Batasan](#batasan)). Nominal rupiah utuh, persis seperti disimpan Medusa.
 - **Kredensial di Admin**, terenkripsi AES-256-GCM, dengan cadangan dari options provider atau env.
 - **Webhook**: signature dicek pada raw body (HMAC-SHA256, ±5 menit), dedupe per event id di database, diproses worker
@@ -228,7 +229,7 @@ Report vulnerabilities privately: see [SECURITY.md](SECURITY.md).
 
 ### Kebutuhan
 
-- Medusa **2.19.x**, Node 20.19+ atau 22.12+
+- Medusa **2.19 atau 2.x yang lebih baru** (dites di CI pada 2.19.0 dan 2.22.0), Node 20.19+ atau 22.12+
 - Redis untuk event bus, workflow engine, dan locking (sangat disarankan; webhook diproses di worker)
 - Akun doit.id: key `pb_test_…` untuk sandbox, `pb_live_…` untuk produksi
 
@@ -314,7 +315,8 @@ Aturan akses: cart harus milik sales channel publishable key, dan cart customer
 methods 20/menit per cart dan 30/menit per IP (di memori, per proses server). doit.id dibaca paling sering sekali per
 10 detik per pembayaran.
 
-**Medusa Next.js Starter:** komponen dan patch di [`examples/nextjs-starter`](examples/nextjs-starter/README.md).
+**Medusa Next.js Starter:** komponen dan patch di [`examples/nextjs-starter`](examples/nextjs-starter/README.md),
+ikut di paket npm (`node_modules/medusa-payment-doit/examples/nextjs-starter`).
 
 Ganti metode membuat invoice baru. Kembali ke metode yang invoice-nya masih aktif (cart dan nominal sama, VA sisa ≥5
 menit, QRIS yang QR-nya masih terbit) memakai ulang invoice itu.

package/examples/nextjs-starter/README.md

@@ -0,0 +1,109 @@
+# doit.id checkout for the Medusa Next.js Starter
+
+Drop-in files for [`nextjs-starter-medusa`](https://github.com/medusajs/nextjs-starter-medusa)
+(tested against commit `9818886`, Next.js 15, Medusa 2.19; the store endpoints it uses run in CI on Medusa 2.19 and 2.22) that add a doit.id payment step:
+
+- **Pick a method**: QRIS or a Virtual Account bank. Only methods doit.id has active for your key are
+  listed, each with the fee and the total to pay for this cart (`GET /store/doit/methods`). Methods outside their
+  amount limits are shown disabled. Who pays the fee is set per method in the doit.id portal, not by the plugin.
+- **QRIS**: renders `qr_content` as an SVG QR code ([`qrcode.react`](https://www.npmjs.com/package/qrcode.react), no canvas, no network).
+- **Virtual Account**: shows the number with a copy button.
+- **Countdown** to `expires_at`.
+- **Polling** of `GET /store/doit/carts/:id/payment`. When the payment is paid, the order is placed and the
+  shopper lands on the starter's confirmation page. This works even when webhooks can't reach you
+  (e.g. on localhost).
+- **Hosted page**: a link to doit.id's `hosted_url`. Set `NEXT_PUBLIC_DOIT_REDIRECT_TO_HOSTED=true` to send
+  shoppers there straight away. They come back to the review step through `return_url`.
+
+The styling is plain: the starter's Tailwind tokens and `@medusajs/ui`, with no logos or brand colours. All
+text is in [`labels.ts`](src/modules/checkout/components/doit-payment/labels.ts) (Indonesian), so you can
+restyle or translate it in one place.
+
+| QRIS | Virtual Account |
+| --- | --- |
+| ![QRIS](https://raw.githubusercontent.com/haustex/pg-medusa-doit/main/docs/screenshots/storefront-qris.jpg) | ![VA](https://raw.githubusercontent.com/haustex/pg-medusa-doit/main/docs/screenshots/storefront-va.jpg) |
+
+## Install
+
+1. Install and configure the plugin in your Medusa backend (see the main README). Enable the provider
+   `pp_doit_doit` in your IDR region.
+2. In the storefront:
+
+   ```bash
+   npm install qrcode.react@^4.2.0
+   ```
+
+3. Copy `src/` from this folder over your storefront's `src/` (it is also in the npm package:
+   `node_modules/medusa-payment-doit/examples/nextjs-starter/src`). It only adds new files:
+
+   ```
+   src/lib/data/doit.ts                                     server actions (SDK calls)
+   src/modules/checkout/components/doit-payment/index.tsx   isDoit, DoitPaymentButton
+   src/modules/checkout/components/doit-payment/rail-picker.tsx
+   src/modules/checkout/components/doit-payment/payment-panel.tsx
+   src/modules/checkout/components/doit-payment/labels.ts   all shopper-facing text
+   src/modules/checkout/components/doit-payment/format.ts   rupiah + countdown helpers
+   ```
+
+4. Wire it into three starter files. Either apply the patch:
+
+   ```bash
+   git apply path/to/examples/nextjs-starter/starter.patch
+   ```
+
+   or make the same changes by hand:
+
+   **`src/lib/constants.tsx`**: add the provider to `paymentInfoMap`:
+
+   ```tsx
+   pp_doit_doit: { title: "QRIS / Virtual Account", icon: <CreditCard /> },
+   ```
+
+   **`src/modules/checkout/components/payment/index.tsx`**: show the method picker and pass the choice
+   when the session is created:
+
+   ```tsx
+   import { DoitChoice, selectDoitMethod } from "@lib/data/doit"
+   import { DoitRailPicker, isDoit } from "@modules/checkout/components/doit-payment"
+
+   const [doitChoice, setDoitChoice] = useState<DoitChoice | null>(/* from activeSession.data */)
+
+   // in handleSubmit, before the generic initiatePaymentSession call:
+   if (isDoit(selectedPaymentMethod)) {
+     const res = await selectDoitMethod(cart, selectedPaymentMethod, doitChoice!,
+       `${window.location.origin}${pathname}?step=review`)
+     if (!res.ok) throw new Error(res.message)
+   } else if (!checkActiveSession) { /* starter code */ }
+
+   // under the <RadioGroup>:
+   {isDoit(selectedPaymentMethod) && (
+     <DoitRailPicker cartId={cart.id} value={doitChoice} onChange={setDoitChoice} />
+   )}
+   ```
+
+   **`src/modules/checkout/components/payment-button/index.tsx`**: add a case to the switch:
+
+   ```tsx
+   case isDoit(paymentSession?.provider_id):
+     return <DoitPaymentButton cart={cart} notReady={notReady} />
+   ```
+
+## How it behaves
+
+| Backend `next_action` | Panel |
+| --- | --- |
+| `wait` | Shows QR / VA, countdown, hosted link; polls again after `poll_after_ms` (5 s). Pauses while the tab is hidden. |
+| `complete_cart` | Payment is paid: calls the starter's `placeOrder()`, which completes the cart and redirects. |
+| `view_order` | The webhook already completed the cart: `placeOrder()` returns that same order and redirects. |
+| `retry` | Expired or failed: offers "Buat tagihan baru" (new invoice with the same method). |
+
+When `qr_expired` is true (the QR image lives about 10 minutes, shorter than the invoice), the panel replaces the QR with
+a button to the hosted page, where doit.id issues a new QR.
+
+The status endpoint only answers for a cart that belongs to the publishable key's sales channel. If the
+cart belongs to a registered customer, that customer has to be logged in. Requests are rate limited
+(40/min per cart, 120/min per IP), and the backend reads doit.id at most once per 10 s per payment. A
+shopper who changes method gets a new invoice; switching back to a method whose invoice is still open reuses it. An
+abandoned invoice is not cancelled at doit.id (there is no cancel endpoint) and simply expires.
+
+Community plugin, not an official doit.id product.

package/examples/nextjs-starter/src/lib/data/doit.ts

@@ -0,0 +1,140 @@
+"use server"
+
+import { sdk } from "@lib/config"
+import { HttpTypes } from "@medusajs/types"
+import { revalidateTag } from "next/cache"
+import { getAuthHeaders, getCacheTag } from "./cookies"
+
+/** What the shopper picked: QRIS, or a VA / transfer bank. */
+export type DoitChoice = {
+  rail: "qris" | "va" | "transfer" | "any"
+  va_bank?: string | null
+}
+
+export type DoitMethod = {
+  code: string
+  label: string
+  rail: "qris" | "va" | "transfer"
+  bank: string | null
+  fee_payer: string | null
+  fee_amount: number | null
+  total_amount: number | null
+  /** false: the cart total is outside this method's limits; show it disabled with `limit` */
+  within_limits: boolean | null
+  limit: string | null
+}
+
+export type DoitMethods = {
+  provider_id: string
+  amount: number | null
+  default: { rail: DoitChoice["rail"]; va_bank: string | null }
+  methods: DoitMethod[]
+  source: "doit" | "unavailable"
+}
+
+export type DoitPaymentStatus = {
+  cart_id: string
+  payment_session_id: string
+  order_id: string | null
+  /** wait: keep polling · complete_cart: paid, place the order · view_order: done · retry: expired / failed */
+  next_action: "wait" | "complete_cart" | "view_order" | "retry"
+  poll_after_ms: number | null
+  /** the QRIS image (≈10 min) expired before the invoice: send the shopper to hosted_url */
+  qr_expired: boolean
+  payment: {
+    id: string | null
+    status: "pending" | "paid" | "expired" | "failed" | "refunded" | null
+    rail: string | null
+    va_bank: string | null
+    va_number: string | null
+    qr_content: string | null
+    hosted_url: string | null
+    expires_at: string | null
+    paid_at: string | null
+    amount: number | null
+    fee_amount: number | null
+    fee_payer: "merchant" | "customer" | null
+    total_amount: number | null
+    environment: string | null
+  }
+}
+
+export type DoitResult<T> = { ok: true; data: T } | { ok: false; status: number; message: string }
+
+function toError(e: any): { ok: false; status: number; message: string } {
+  return { ok: false, status: e?.status ?? 0, message: e?.message ?? "Gagal menghubungi server." }
+}
+
+/** Methods doit.id has active for this store, with the fee for the cart total. Cached by the backend for 5 minutes. */
+export async function listDoitMethods(cartId: string): Promise<DoitResult<DoitMethods>> {
+  try {
+    const data = await sdk.client.fetch<DoitMethods>("/store/doit/methods", {
+      method: "GET",
+      query: { cart_id: cartId },
+      headers: { ...(await getAuthHeaders()) },
+      cache: "no-store",
+    })
+    return { ok: true, data }
+  } catch (e) {
+    return toError(e)
+  }
+}
+
+/** Status for the "waiting for payment" panel. Safe to poll: the backend throttles reads of doit.id. */
+export async function getDoitPaymentStatus(cartId: string): Promise<DoitResult<DoitPaymentStatus>> {
+  try {
+    const data = await sdk.client.fetch<DoitPaymentStatus>(`/store/doit/carts/${cartId}/payment`, {
+      method: "GET",
+      headers: { ...(await getAuthHeaders()) },
+      cache: "no-store",
+    })
+    return { ok: true, data }
+  } catch (e) {
+    return toError(e)
+  }
+}
+
+/**
+ * Creates (or replaces) the cart's doit payment session for the chosen
+ * method. A session with the same rail / bank that is still pending is kept,
+ * so going back and forth in the checkout does not create new invoices.
+ */
+export async function selectDoitMethod(
+  cart: HttpTypes.StoreCart,
+  providerId: string,
+  choice: DoitChoice,
+  returnUrl?: string,
+  { force = false }: { force?: boolean } = {}
+): Promise<DoitResult<null>> {
+  const current = cart.payment_collection?.payment_sessions?.find(
+    (s) => s.provider_id === providerId && s.status === "pending"
+  )
+  const same =
+    current &&
+    current.data?.status === "pending" &&
+    (current.data?.requested_rail ?? current.data?.rail) === choice.rail &&
+    (choice.rail === "qris" || choice.rail === "any" || current.data?.va_bank === choice.va_bank)
+  if (same && !force) {
+    return { ok: true, data: null }
+  }
+
+  try {
+    await sdk.store.payment.initiatePaymentSession(
+      cart,
+      {
+        provider_id: providerId,
+        data: {
+          rail: choice.rail,
+          ...(choice.va_bank ? { va_bank: choice.va_bank } : {}),
+          ...(returnUrl ? { return_url: returnUrl } : {}),
+        },
+      },
+      {},
+      { ...(await getAuthHeaders()) }
+    )
+    revalidateTag(await getCacheTag("carts"))
+    return { ok: true, data: null }
+  } catch (e) {
+    return toError(e)
+  }
+}

package/examples/nextjs-starter/src/modules/checkout/components/doit-payment/format.ts

@@ -0,0 +1,22 @@
+import { convertToLocale } from "@lib/util/money"
+
+/** Rupiah as stored by Medusa and doit.id (Rp150.000 = 150000): no scaling. */
+export function rupiah(amount: number | null | undefined): string {
+  return convertToLocale({
+    amount: amount ?? 0,
+    currency_code: "idr",
+    locale: "id-ID",
+    minimumFractionDigits: 0,
+    maximumFractionDigits: 0,
+  })
+}
+
+/** "02:14:05" / "14:05" until `until`; "00:00" when past. */
+export function remaining(until: number, now: number): string {
+  const total = Math.max(0, Math.floor((until - now) / 1000))
+  const h = Math.floor(total / 3600)
+  const m = Math.floor((total % 3600) / 60)
+  const s = total % 60
+  const pad = (n: number) => String(n).padStart(2, "0")
+  return h > 0 ? `${pad(h)}:${pad(m)}:${pad(s)}` : `${pad(m)}:${pad(s)}`
+}

package/examples/nextjs-starter/src/modules/checkout/components/doit-payment/index.tsx

@@ -0,0 +1,40 @@
+"use client"
+
+import { HttpTypes } from "@medusajs/types"
+import { Button } from "@medusajs/ui"
+import { doitLabels } from "./labels"
+import DoitPaymentPanel from "./payment-panel"
+
+export { default as DoitRailPicker } from "./rail-picker"
+export { default as DoitPaymentPanel } from "./payment-panel"
+export { doitLabels }
+
+/** True for any doit.id provider registered in Medusa (pp_doit_<id>). */
+export const isDoit = (providerId?: string) => !!providerId?.startsWith("pp_doit_")
+
+/**
+ * Drop-in for the review step's PaymentButton: once address, email and
+ * shipping are set, shows the payment panel instead of a "Place order" button.
+ * The order is placed automatically when doit.id reports the payment as paid.
+ */
+export function DoitPaymentButton({
+  cart,
+  notReady,
+  redirectToHosted = process.env.NEXT_PUBLIC_DOIT_REDIRECT_TO_HOSTED === "true",
+}: {
+  cart: HttpTypes.StoreCart
+  notReady: boolean
+  redirectToHosted?: boolean
+}) {
+  const session = cart.payment_collection?.payment_sessions?.find(
+    (s) => isDoit(s.provider_id) && s.status === "pending"
+  )
+  if (notReady || !session) {
+    return (
+      <Button disabled size="large">
+        {doitLabels.payButton}
+      </Button>
+    )
+  }
+  return <DoitPaymentPanel cart={cart} providerId={session.provider_id} redirectToHosted={redirectToHosted} />
+}

package/examples/nextjs-starter/src/modules/checkout/components/doit-payment/labels.ts

@@ -0,0 +1,55 @@
+// All shopper-facing text of the doit.id checkout in one place. Edit or
+// translate freely; nothing else in these components hard-codes copy.
+export const doitLabels = {
+  methodTitle: "QRIS / Virtual Account",
+  chooseMethod: "Pilih cara bayar",
+  qris: "QRIS",
+  qrisHint: "Semua e-wallet dan m-banking",
+  va: "Virtual Account",
+  transfer: "Transfer bank",
+  anyMethod: "Pilih di halaman pembayaran",
+  feeByCustomer: (fee: string) => `+ biaya ${fee}`,
+  noFee: "Tanpa biaya tambahan",
+  totalWithFee: (total: string) => `Total ${total}`,
+  outsideLimit: (limit: string | null) => (limit ? `Tidak tersedia: ${limit}` : "Tidak tersedia untuk nominal ini"),
+  feeNote: "Biaya layanan ditetapkan doit.id per metode. Total yang dibayar tampil sebelum kamu memilih.",
+  methodsUnavailable: "Daftar metode tidak bisa dimuat. Metode bawaan toko akan dipakai.",
+  loading: "Memuat…",
+  payButton: "Bayar",
+
+  payTitle: "Selesaikan pembayaran",
+  totalToPay: "Total dibayar",
+  includesFee: (fee: string) => `Termasuk biaya ${fee}`,
+  scanQris: "Pindai kode QR ini dengan aplikasi e-wallet atau m-banking.",
+  vaNumber: (bank: string) => `Nomor Virtual Account ${bank}`,
+  vaHint: "Transfer tepat sesuai total ke nomor ini dari m-banking, internet banking, atau ATM.",
+  copy: "Salin",
+  copied: "Tersalin",
+  expiresIn: "Sisa waktu",
+  expired: "Waktu pembayaran habis",
+  openHosted: "Buka halaman pembayaran",
+  qrExpired: "Kode QR sudah tidak berlaku. Lanjutkan pembayaran di halaman doit.id untuk membuat kode baru.",
+  continueHosted: "Lanjutkan di halaman pembayaran",
+
+  waiting: "Menunggu pembayaran… halaman ini diperbarui otomatis.",
+  paid: "Pembayaran diterima. Membuat pesanan…",
+  failed: "Pembayaran gagal atau kedaluwarsa.",
+  newInvoice: "Buat tagihan baru",
+  testMode: "Mode uji (sandbox): tidak ada uang sungguhan.",
+  errorGeneric: "Status pembayaran belum bisa diperiksa. Mencoba lagi…",
+}
+
+export const bankNames: Record<string, string> = {
+  bmri: "Mandiri",
+  bnia: "BNI",
+  brin: "BRI",
+  cimb: "CIMB Niaga",
+  permata: "Permata",
+  maybank: "Maybank",
+  danamon: "Danamon",
+  bsyi: "BSI",
+  bca: "BCA",
+  mandiri: "Mandiri",
+  bni: "BNI",
+  bsi: "BSI",
+}

package/examples/nextjs-starter/src/modules/checkout/components/doit-payment/payment-panel.tsx

@@ -0,0 +1,227 @@
+"use client"
+
+import { placeOrder } from "@lib/data/cart"
+import { DoitPaymentStatus, getDoitPaymentStatus, selectDoitMethod } from "@lib/data/doit"
+import { HttpTypes } from "@medusajs/types"
+import { Button, Heading, Text, clx } from "@medusajs/ui"
+import { useRouter } from "next/navigation"
+import { QRCodeSVG } from "qrcode.react"
+import { useCallback, useEffect, useRef, useState } from "react"
+import { remaining, rupiah } from "./format"
+import { bankNames, doitLabels as t } from "./labels"
+
+type Props = {
+  cart: HttpTypes.StoreCart
+  providerId: string
+  /** Send the shopper straight to doit.id's hosted payment page instead of showing QR / VA here. */
+  redirectToHosted?: boolean
+}
+
+const ERROR_RETRY_MS = 10_000
+
+/**
+ * "Waiting for payment" panel: QRIS code or VA number, countdown to
+ * expires_at, a link to the hosted page, and polling of
+ * GET /store/doit/carts/:id/payment. Once doit.id reports the payment as paid
+ * it places the order (the starter's placeOrder redirects to the confirmation
+ * page; if the webhook completed the cart first, Medusa returns that order).
+ */
+export default function DoitPaymentPanel({ cart, providerId, redirectToHosted = false }: Props) {
+  const router = useRouter()
+  const [state, setState] = useState<DoitPaymentStatus | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [busy, setBusy] = useState(false)
+  const [now, setNow] = useState(() => Date.now())
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const placing = useRef(false)
+  const redirected = useRef(false)
+
+  const finish = useCallback(async () => {
+    if (placing.current) return
+    placing.current = true
+    try {
+      await placeOrder(cart.id) // redirects to /[countryCode]/order/[id]/confirmed
+    } catch (e: any) {
+      placing.current = false
+      setError(e?.message ?? t.errorGeneric)
+    }
+  }, [cart.id])
+
+  const poll = useCallback(async () => {
+    if (timer.current) clearTimeout(timer.current)
+    const res = await getDoitPaymentStatus(cart.id)
+    let next: number | null = ERROR_RETRY_MS
+    if (res.ok) {
+      setState(res.data)
+      setError(null)
+      next = res.data.poll_after_ms
+      if (res.data.next_action === "complete_cart" || res.data.next_action === "view_order") {
+        next = null
+        void finish()
+      }
+    } else {
+      setError(t.errorGeneric)
+      // 429: the backend asks to slow down
+      next = res.status === 429 ? ERROR_RETRY_MS * 3 : ERROR_RETRY_MS
+    }
+    if (next !== null && document.visibilityState === "visible") {
+      timer.current = setTimeout(poll, next)
+    }
+  }, [cart.id, finish])
+
+  useEffect(() => {
+    void poll()
+    const onVisible = () => {
+      if (document.visibilityState === "visible") void poll()
+    }
+    document.addEventListener("visibilitychange", onVisible)
+    return () => {
+      document.removeEventListener("visibilitychange", onVisible)
+      if (timer.current) clearTimeout(timer.current)
+    }
+  }, [poll])
+
+  useEffect(() => {
+    const id = setInterval(() => setNow(Date.now()), 1000)
+    return () => clearInterval(id)
+  }, [])
+
+  const p = state?.payment
+  useEffect(() => {
+    if (redirectToHosted && p?.hosted_url && state?.next_action === "wait" && !redirected.current) {
+      redirected.current = true
+      window.location.assign(p.hosted_url)
+    }
+  }, [redirectToHosted, p?.hosted_url, state?.next_action])
+
+  const newInvoice = async () => {
+    if (!p?.rail) return
+    setBusy(true)
+    const res = await selectDoitMethod(
+      cart,
+      providerId,
+      { rail: p.rail as "qris" | "va" | "transfer", va_bank: p.va_bank },
+      window.location.href,
+      { force: true }
+    )
+    setBusy(false)
+    if (!res.ok) {
+      setError(res.message)
+      return
+    }
+    router.refresh()
+    void poll()
+  }
+
+  if (!state) {
+    return (
+      <Text className="txt-medium text-ui-fg-subtle" data-testid="doit-panel-loading">
+        {error ?? t.loading}
+      </Text>
+    )
+  }
+
+  const expiresAt = p?.expires_at ? new Date(p.expires_at).getTime() : null
+  const isExpired = expiresAt !== null && expiresAt <= now
+  const total = p?.total_amount ?? p?.amount
+  const customerFee = p?.fee_payer === "customer" && p.fee_amount ? p.fee_amount : 0
+  const done = state.next_action === "complete_cart" || state.next_action === "view_order"
+  const retry = state.next_action === "retry"
+
+  return (
+    <div className="flex flex-col gap-y-6 rounded-rounded border border-ui-border-base p-6" data-testid="doit-payment-panel">
+      <div className="flex flex-col gap-y-1">
+        <Heading level="h3" className="txt-xlarge">{t.payTitle}</Heading>
+        {p?.environment === "test" && <Text className="txt-small text-ui-fg-muted">{t.testMode}</Text>}
+      </div>
+
+      <div className="flex flex-col gap-y-1">
+        <Text className="txt-small text-ui-fg-subtle">{t.totalToPay}</Text>
+        <Text className="text-2xl font-semibold text-ui-fg-base" data-testid="doit-total">{rupiah(total)}</Text>
+        {customerFee > 0 && <Text className="txt-small text-ui-fg-subtle">{t.includesFee(rupiah(customerFee))}</Text>}
+      </div>
+
+      {!done && !retry && state.qr_expired && p?.hosted_url && (
+        <div className="flex flex-col items-start gap-y-3" data-testid="doit-qr-expired">
+          <Text className="txt-medium text-ui-fg-base max-w-sm">{t.qrExpired}</Text>
+          <Button asChild variant="primary">
+            <a href={p.hosted_url}>{t.continueHosted}</a>
+          </Button>
+        </div>
+      )}
+
+      {!done && !retry && p?.qr_content && (
+        <div className="flex flex-col items-start gap-y-3">
+          <div className="rounded-rounded border border-ui-border-base bg-white p-3" data-testid="doit-qris">
+            <QRCodeSVG value={p.qr_content} size={220} level="M" marginSize={2} title="QRIS" />
+          </div>
+          <Text className="txt-small text-ui-fg-subtle max-w-sm">{t.scanQris}</Text>
+        </div>
+      )}
+
+      {!done && !retry && p?.va_number && (
+        <div className="flex flex-col gap-y-2" data-testid="doit-va">
+          <Text className="txt-small text-ui-fg-subtle">{t.vaNumber(bankNames[p.va_bank ?? ""] ?? (p.va_bank ?? "").toUpperCase())}</Text>
+          <div className="flex items-center gap-x-3">
+            <span className="font-mono text-2xl tracking-wider text-ui-fg-base" data-testid="doit-va-number">{p.va_number}</span>
+            <CopyButton value={p.va_number} />
+          </div>
+          <Text className="txt-small text-ui-fg-subtle max-w-sm">{t.vaHint}</Text>
+        </div>
+      )}
+
+      {!done && !retry && expiresAt !== null && (
+        <div className="flex items-baseline gap-x-2" data-testid="doit-countdown">
+          <Text className="txt-small text-ui-fg-subtle">{isExpired ? t.expired : t.expiresIn}</Text>
+          {!isExpired && (
+            <Text className="font-mono txt-medium-plus text-ui-fg-base" suppressHydrationWarning>
+              {remaining(expiresAt, now)}
+            </Text>
+          )}
+        </div>
+      )}
+
+      <div className={clx("flex items-center gap-x-2 txt-small", retry ? "text-ui-fg-error" : "text-ui-fg-subtle")} data-testid="doit-status">
+        {!done && !retry && <span className="inline-block h-2 w-2 animate-pulse rounded-full bg-ui-fg-interactive" />}
+        <span>{done ? t.paid : retry ? t.failed : t.waiting}</span>
+      </div>
+
+      {error && <Text className="txt-small text-ui-fg-error">{error}</Text>}
+
+      <div className="flex flex-wrap items-center gap-3">
+        {retry && (
+          <Button onClick={newInvoice} isLoading={busy} data-testid="doit-new-invoice">{t.newInvoice}</Button>
+        )}
+        {!done && !retry && p?.hosted_url && (
+          <a href={p.hosted_url} target="_blank" rel="noopener noreferrer" className="txt-small text-ui-fg-interactive hover:text-ui-fg-interactive-hover underline" data-testid="doit-hosted-link">
+            {t.openHosted}
+          </a>
+        )}
+      </div>
+    </div>
+  )
+}
+
+function CopyButton({ value }: { value: string }) {
+  const [copied, setCopied] = useState(false)
+  const copy = async () => {
+    try {
+      await navigator.clipboard.writeText(value)
+    } catch {
+      // Older browsers / non-secure origins: fall back to a hidden textarea.
+      const el = document.createElement("textarea")
+      el.value = value
+      document.body.appendChild(el)
+      el.select()
+      document.execCommand("copy")
+      el.remove()
+    }
+    setCopied(true)
+    setTimeout(() => setCopied(false), 2000)
+  }
+  return (
+    <Button variant="secondary" size="small" onClick={copy} data-testid="doit-copy-va">
+      {copied ? t.copied : t.copy}
+    </Button>
+  )
+}

package/examples/nextjs-starter/src/modules/checkout/components/doit-payment/rail-picker.tsx

@@ -0,0 +1,122 @@
+"use client"
+
+import { DoitChoice, DoitMethod, listDoitMethods } from "@lib/data/doit"
+import { Text, clx } from "@medusajs/ui"
+import { useEffect, useState } from "react"
+import { rupiah } from "./format"
+import { bankNames, doitLabels as t } from "./labels"
+
+type Props = {
+  cartId: string
+  value: DoitChoice | null
+  onChange: (choice: DoitChoice) => void
+}
+
+const keyOf = (c: { rail: string; va_bank?: string | null; bank?: string | null }) =>
+  `${c.rail}:${c.va_bank ?? c.bank ?? ""}`
+
+/**
+ * Lists the methods doit.id has active for this store (QRIS, VA banks,
+ * transfer banks) with the fee for this cart, and reports the choice.
+ */
+export default function DoitRailPicker({ cartId, value, onChange }: Props) {
+  const [methods, setMethods] = useState<DoitMethod[] | null>(null)
+  const [unavailable, setUnavailable] = useState(false)
+
+  useEffect(() => {
+    let active = true
+    listDoitMethods(cartId).then((res) => {
+      if (!active) return
+      if (!res.ok || res.data.source !== "doit" || !res.data.methods.length) {
+        setUnavailable(true)
+        setMethods([])
+        if (res.ok && !value) {
+          onChange({ rail: res.data.default.rail, va_bank: res.data.default.va_bank })
+        }
+        return
+      }
+      setMethods(res.data.methods)
+      if (!value) {
+        const preferred =
+          res.data.methods.find((m) => m.within_limits !== false && keyOf(m) === keyOf(res.data.default)) ??
+          res.data.methods.find((m) => m.within_limits !== false) ??
+          res.data.methods[0]
+        onChange({ rail: preferred.rail, va_bank: preferred.bank })
+      }
+    })
+    return () => {
+      active = false
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [cartId])
+
+  if (methods === null) {
+    return <Text className="txt-small text-ui-fg-subtle">{t.loading}</Text>
+  }
+  if (unavailable) {
+    return <Text className="txt-small text-ui-fg-subtle">{t.methodsUnavailable}</Text>
+  }
+
+  const groups: { title: string; items: DoitMethod[] }[] = [
+    { title: t.qris, items: methods.filter((m) => m.rail === "qris") },
+    { title: t.va, items: methods.filter((m) => m.rail === "va") },
+    { title: t.transfer, items: methods.filter((m) => m.rail === "transfer") },
+  ].filter((g) => g.items.length)
+
+  return (
+    <div className="flex flex-col gap-y-4" data-testid="doit-rail-picker">
+      <Text className="txt-medium-plus text-ui-fg-base">{t.chooseMethod}</Text>
+      {groups.map((group) => (
+        <fieldset key={group.title} className="flex flex-col gap-y-2">
+          {/* QRIS is a single option that already says "QRIS" */}
+          {group.items[0].rail !== "qris" && (
+            <legend className="txt-small text-ui-fg-subtle mb-1">{group.title}</legend>
+          )}
+          <div className="grid grid-cols-1 small:grid-cols-2 gap-2">
+            {group.items.map((m) => {
+              const selected = value ? keyOf(value) === keyOf(m) : false
+              const disabled = m.within_limits === false
+              const customerFee = m.fee_payer === "customer" && m.fee_amount ? m.fee_amount : 0
+              const fee = disabled ? t.outsideLimit(m.limit) : customerFee ? t.feeByCustomer(rupiah(customerFee)) : t.noFee
+              return (
+                <label
+                  key={m.code}
+                  className={clx(
+                    "flex items-center justify-between gap-x-3 rounded-rounded border px-4 py-3",
+                    disabled ? "cursor-not-allowed opacity-50" : "cursor-pointer hover:shadow-borders-interactive-with-active",
+                    selected ? "border-ui-border-interactive" : "border-ui-border-base"
+                  )}
+                  data-testid={`doit-method-${m.code}`}
+                >
+                  <span className="flex items-center gap-x-3">
+                    <input
+                      type="radio"
+                      name="doit-method"
+                      className="accent-ui-fg-interactive"
+                      checked={selected}
+                      disabled={disabled}
+                      onChange={() => onChange({ rail: m.rail, va_bank: m.bank })}
+                    />
+                    <span className="flex flex-col">
+                      <span className="txt-compact-medium text-ui-fg-base">
+                        {m.rail === "qris" ? t.qris : bankNames[m.bank ?? ""] ?? m.label}
+                      </span>
+                      {m.rail === "qris" && <span className="txt-small text-ui-fg-subtle">{t.qrisHint}</span>}
+                    </span>
+                  </span>
+                  <span className="flex flex-col items-end txt-small text-ui-fg-subtle whitespace-nowrap">
+                    <span>{fee}</span>
+                    {!disabled && customerFee > 0 && m.total_amount !== null && (
+                      <span className="text-ui-fg-base">{t.totalWithFee(rupiah(m.total_amount))}</span>
+                    )}
+                  </span>
+                </label>
+              )
+            })}
+          </div>
+        </fieldset>
+      ))}
+      <Text className="txt-small text-ui-fg-muted">{t.feeNote}</Text>
+    </div>
+  )
+}

package/examples/nextjs-starter/starter.patch

@@ -0,0 +1,123 @@
+diff --git a/src/lib/constants.tsx b/src/lib/constants.tsx
+index ce3bc60..0d609e8 100644
+--- a/src/lib/constants.tsx
++++ b/src/lib/constants.tsx
+@@ -34,6 +34,10 @@ export const paymentInfoMap: Record<
+     title: "Manual Payment",
+     icon: <CreditCard />,
+   },
++  pp_doit_doit: {
++    title: "QRIS / Virtual Account",
++    icon: <CreditCard />,
++  },
+   // Add more payment providers here
+ }
+ 
+diff --git a/src/modules/checkout/components/payment-button/index.tsx b/src/modules/checkout/components/payment-button/index.tsx
+index 04a83c9..6567904 100644
+--- a/src/modules/checkout/components/payment-button/index.tsx
++++ b/src/modules/checkout/components/payment-button/index.tsx
+@@ -2,6 +2,10 @@
+ 
+ import { isManual, isStripeLike } from "@lib/constants"
+ import { placeOrder } from "@lib/data/cart"
++import {
++  DoitPaymentButton,
++  isDoit,
++} from "@modules/checkout/components/doit-payment"
+ import { HttpTypes } from "@medusajs/types"
+ import { Button } from "@medusajs/ui"
+ import { useElements, useStripe } from "@stripe/react-stripe-js"
+@@ -35,6 +39,8 @@ const PaymentButton: React.FC<PaymentButtonProps> = ({
+           data-testid={dataTestId}
+         />
+       )
++    case isDoit(paymentSession?.provider_id):
++      return <DoitPaymentButton cart={cart} notReady={notReady} />
+     case isManual(paymentSession?.provider_id):
+       return (
+         <ManualTestPaymentButton notReady={notReady} data-testid={dataTestId} />
+diff --git a/src/modules/checkout/components/payment/index.tsx b/src/modules/checkout/components/payment/index.tsx
+index d96beeb..e806b99 100644
+--- a/src/modules/checkout/components/payment/index.tsx
++++ b/src/modules/checkout/components/payment/index.tsx
+@@ -3,6 +3,7 @@
+ import { RadioGroup } from "@headlessui/react"
+ import { isStripeLike, paymentInfoMap } from "@lib/constants"
+ import { initiatePaymentSession } from "@lib/data/cart"
++import { DoitChoice, selectDoitMethod } from "@lib/data/doit"
+ import { CheckCircleSolid, CreditCard } from "@medusajs/icons"
+ import { Button, Container, Heading, Text, clx } from "@medusajs/ui"
+ import ErrorMessage from "@modules/checkout/components/error-message"
+@@ -10,6 +11,10 @@ import PaymentContainer, {
+   StripeCardContainer,
+ } from "@modules/checkout/components/payment-container"
+ import Divider from "@modules/common/components/divider"
++import {
++  DoitRailPicker,
++  isDoit,
++} from "@modules/checkout/components/doit-payment"
+ import { usePathname, useRouter, useSearchParams } from "next/navigation"
+ import { useCallback, useEffect, useState } from "react"
+ 
+@@ -32,6 +37,16 @@ const Payment = ({
+     activeSession?.provider_id ?? ""
+   )
+ 
++  const [doitChoice, setDoitChoice] = useState<DoitChoice | null>(
++    activeSession && isDoit(activeSession.provider_id)
++      ? {
++          rail: (activeSession.data?.requested_rail ??
++            activeSession.data?.rail) as DoitChoice["rail"],
++          va_bank: activeSession.data?.va_bank as string | null,
++        }
++      : null
++  )
++
+   const searchParams = useSearchParams()
+   const router = useRouter()
+   const pathname = usePathname()
+@@ -79,7 +94,18 @@ const Payment = ({
+       const checkActiveSession =
+         activeSession?.provider_id === selectedPaymentMethod
+ 
+-      if (!checkActiveSession) {
++      if (isDoit(selectedPaymentMethod)) {
++        // New doit.id invoice only when the method changed; back here after the hosted page.
++        const res = await selectDoitMethod(
++          cart,
++          selectedPaymentMethod,
++          doitChoice!,
++          `${window.location.origin}${pathname}?step=review`
++        )
++        if (!res.ok) {
++          throw new Error(res.message)
++        }
++      } else if (!checkActiveSession) {
+         await initiatePaymentSession(cart, {
+           provider_id: selectedPaymentMethod,
+         })
+@@ -161,6 +187,15 @@ const Payment = ({
+                   </div>
+                 ))}
+               </RadioGroup>
++              {isDoit(selectedPaymentMethod) && (
++                <div className="mt-4">
++                  <DoitRailPicker
++                    cartId={cart.id}
++                    value={doitChoice}
++                    onChange={setDoitChoice}
++                  />
++                </div>
++              )}
+             </>
+           )}
+ 
+@@ -190,6 +225,7 @@ const Payment = ({
+             isLoading={isLoading}
+             disabled={
+               (isStripeLike(selectedPaymentMethod) && !cardComplete) ||
++              (isDoit(selectedPaymentMethod) && !doitChoice) ||
+               (!selectedPaymentMethod && !paidByGiftcard)
+             }
+             data-testid="submit-payment-button"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "medusa-payment-doit",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "doit.id payment gateway (QRIS, Virtual Account, bank transfer) for Medusa v2 — by Haus Kayu",
   "author": "Haus Kayu <dev@hauskayu.com> (https://hauskayu.com)",
   "license": "MIT",
@@ -15,6 +15,7 @@
   },
   "files": [
     ".medusa/server",
+    "examples/nextjs-starter",
     "CHANGELOG.md"
   ],
   "publishConfig": {
@@ -43,7 +44,9 @@
     "doit",
     "qris",
     "virtual-account",
-    "indonesia"
+    "indonesia",
+    "medusa-plugin-integration",
+    "medusa-plugin-payment"
   ],
   "scripts": {
     "build": "medusa plugin:build",
@@ -85,14 +88,14 @@
     "yalc": "^1.0.0-pre.53"
   },
   "peerDependencies": {
-    "@medusajs/admin-sdk": "2.19.0",
-    "@medusajs/cli": "2.19.0",
-    "@medusajs/framework": "2.19.0",
-    "@medusajs/icons": "2.19.0",
-    "@medusajs/js-sdk": "2.19.0",
-    "@medusajs/medusa": "2.19.0",
-    "@medusajs/test-utils": "2.19.0",
-    "@medusajs/ui": "4.2.1"
+    "@medusajs/admin-sdk": "^2.19.0",
+    "@medusajs/cli": "^2.19.0",
+    "@medusajs/framework": "^2.19.0",
+    "@medusajs/icons": "^2.19.0",
+    "@medusajs/js-sdk": "^2.19.0",
+    "@medusajs/medusa": "^2.19.0",
+    "@medusajs/test-utils": "^2.19.0",
+    "@medusajs/ui": "^4.2.1"
   },
   "engines": {
     "node": "^20.19.0 || >=22.12.0"