How to Integrate Mayar.id Payments Into Your Product

https://your-app.com/api/mayar-webhook?token=SOME_LONG_RANDOM_SECRET

MAYAR_API_KEY=...
MAYAR_API_BASE=https://api.mayar.club/hl/v2   # https://api.mayar.id/hl/v2 in production
MAYAR_WEBHOOK_TOKEN=...                        # the same secret as ?token=
APP_URL=https://your-app.com

-- What the customer has.
CREATE TABLE seats (
  id                 TEXT PRIMARY KEY,
  owner_id           TEXT NOT NULL,
  status             TEXT NOT NULL DEFAULT 'pending',  -- pending | active | inactive
  amount_idr         INTEGER NOT NULL,
  current_period_end TIMESTAMP,                        -- paid until
  created_at         TIMESTAMP NOT NULL DEFAULT now()
);
 
-- One row per Mayar invoice: a first purchase, or a monthly renewal.
CREATE TABLE billing_orders (
  id                   TEXT PRIMARY KEY,
  owner_id             TEXT NOT NULL,
  kind                 TEXT NOT NULL,            -- purchase | renewal
  quantity             INTEGER NOT NULL,
  amount_idr           INTEGER NOT NULL,
  seat_ids             JSON NOT NULL,            -- which seats this invoice pays for
  customer_email       TEXT NOT NULL,
  customer_name        TEXT NOT NULL,
  customer_mobile      TEXT NOT NULL,
  mayar_invoice_id     TEXT,
  mayar_transaction_id TEXT,
  invoice_url          TEXT,
  invoice_expires_at   TIMESTAMP,
  status               TEXT NOT NULL DEFAULT 'pending',  -- pending | paid | expired | failed
  paid_at              TIMESTAMP
);
 
CREATE INDEX billing_orders_tx ON billing_orders (mayar_transaction_id);

const BASE = (process.env.MAYAR_API_BASE ?? 'https://api.mayar.club/hl/v2').replace(/\/$/, '')
 
async function mayarFetch<T>(path: string, init?: RequestInit): Promise<T> {
  const res = await fetch(`${BASE}${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.MAYAR_API_KEY}`,
      'Content-Type': 'application/json',
    },
  })
  const body = await res.json()
  if ((body.statusCode ?? res.status) >= 400) {
    // Validation errors put the readable message in data, e.g. "The 'mobile' field is required."
    const detail = Array.isArray(body.data) ? body.data.map((d: { message: string }) => d.message).join(', ') : ''
    throw new Error(detail || body.messages || 'Mayar request failed')
  }
  return body.data as T
}
 
export async function createInvoice(input: {
  name: string
  email: string
  mobile: string
  quantity: number
  rateIdr: number
  itemDescription: string
  expiredAt: Date
  redirectUrl: string
  orderId: string
}) {
  const data = await mayarFetch<{ id: string; transactionId: string; link: string }>(
    '/invoices/create',
    {
      method: 'POST',
      body: JSON.stringify({
        name: input.name,
        email: input.email,
        mobile: input.mobile,
        description: input.itemDescription,
        expiredAt: input.expiredAt.toISOString(),
        redirectUrl: input.redirectUrl,
        items: [{ quantity: input.quantity, rate: input.rateIdr, description: input.itemDescription }],
        extraData: { orderId: input.orderId },
      }),
    },
  )
  return { invoiceId: data.id, transactionId: data.transactionId, link: data.link }
}
 
export function getInvoice(invoiceId: string) {
  return mayarFetch<{ status: string }>(`/invoices/${invoiceId}`)
}
 
export const isPaid = (status?: string) =>
  ['paid', 'success'].includes((status ?? '').toLowerCase())

const PRICE_IDR = 100_000
 
export async function createCheckout(db: Db, user: User, quantity: number, mobile: string) {
  // 1. Write it down before calling Mayar, so the webhook has something to find.
  const order = await db.transaction(async (tx) => {
    const seats = await insertPendingSeats(tx, user.id, quantity, PRICE_IDR)
    return insertOrder(tx, {
      ownerId: user.id,
      kind: 'purchase',
      quantity,
      amountIdr: quantity * PRICE_IDR,
      seatIds: seats.map((s) => s.id),
      customer: { email: user.email, name: user.name, mobile },
    })
  })
 
  // 2. One invoice for everything they're buying.
  try {
    const invoice = await createInvoice({
      name: user.name,
      email: user.email,
      mobile,
      quantity,
      rateIdr: PRICE_IDR,
      itemDescription: 'Seat (1 month)',
      expiredAt: new Date(Date.now() + 24 * 60 * 60 * 1000), // payable for 24 hours
      redirectUrl: `${process.env.APP_URL}/dashboard?billing=success`,
      orderId: order.id,
    })
    await saveInvoiceOnOrder(db, order.id, invoice)
    return { checkoutUrl: invoice.link }
  } catch (error) {
    // Mayar said no: mark the order failed so you don't keep pending seats forever.
    await markOrderFailed(db, order.id)
    throw error
  }
}

{
  "event": "payment.received",
  "data": {
    "transactionId": "8abf3c04-0bf9-485a-a4b8-77395c7f9f68",
    "status": "SUCCESS",
    "productType": "invoice",
    "productId": "9d48c533-efab-42a2-898e-0e17f595e040",
    "amount": 100000,
    "customerEmail": "customer@example.com",
    "extraData": { "orderId": "78c93a35-fea1-4350-b12b-bc0294a30c98" }
  }
}

export async function POST(request: Request) {
  // 1. Is this really Mayar?
  const token = new URL(request.url).searchParams.get('token')
  if (token !== process.env.MAYAR_WEBHOOK_TOKEN) {
    return new Response('Unauthorized', { status: 401 })
  }
 
  const payload = await request.json().catch(() => null)
  if (payload?.event === 'payment.received' && isPaid(payload.data?.status)) {
    // 2. Which order is this?
    const order = await findOrderByTransactionId(db, payload.data.transactionId)
    if (order) {
      // 3. Ask Mayar directly before unlocking anything.
      const invoice = await getInvoice(order.mayarInvoiceId)
      if (isPaid(invoice.status)) await applyPaidOrder(db, order.id)
    }
  }
  return new Response('ok')
}

export async function applyPaidOrder(db: Db, orderId: string, now = new Date()) {
  // Only the first call flips pending → paid. Every later call matches no rows and stops here.
  const [order] = await db.update(orders)
    .set({ status: 'paid', paidAt: now })
    .where(and(eq(orders.id, orderId), inArray(orders.status, ['pending', 'expired'])))
    .returning()
  if (!order) return
 
  for (const seat of await getSeats(db, order.seatIds)) {
    // Paying early adds a month on top; paying late starts a fresh month from today.
    const from = seat.currentPeriodEnd && seat.currentPeriodEnd > now ? seat.currentPeriodEnd : now
    await db.update(seats)
      .set({ status: 'active', currentPeriodEnd: addDays(from, 30) })
      .where(eq(seats.id, seat.id))
  }
}

export async function billingSweep(db: Db, now = new Date()) {
  // 1. Backup for missed webhooks: ask Mayar about recent pending orders.
  for (const order of await pendingOrdersSince(db, hoursAgo(48))) {
    const invoice = await getInvoice(order.mayarInvoiceId).catch(() => null)
    if (invoice && isPaid(invoice.status)) await applyPaidOrder(db, order.id, now)
  }
 
  // 2. Invoices nobody paid in time: release their pending seats.
  await expireOverdueOrders(db, now)
 
  // 3. Seats whose paid month is over: switch them off.
  await expireLapsedSeats(db, now)
 
  // 4. Seats ending within 7 days: one renewal invoice per customer.
  for (const [ownerId, dueSeats] of await seatsDueForRenewal(db, now, days(7))) {
    const customer = await latestCustomerDetails(db, ownerId)   // email, name and phone from their last order
    const order = await insertOrder(db, { ownerId, kind: 'renewal', seats: dueSeats, customer })
    try {
      const invoice = await createInvoice({
        ...customer,
        quantity: dueSeats.length,
        rateIdr: dueSeats[0].amountIdr,
        itemDescription: 'Seat (1 month)',
        expiredAt: addDays(earliestEnd(dueSeats), 3),   // a few days of grace
        redirectUrl: `${process.env.APP_URL}/dashboard?billing=success`,
        orderId: order.id,
      })
      await saveInvoiceOnOrder(db, order.id, invoice)
    } catch {
      await markOrderFailed(db, order.id)   // the next run will try again
    }
  }
}

cloudflared tunnel --url http://localhost:3000 --http-host-header localhost:3000

# Claude Code
mkdir -p .claude/skills/mayar-id-payments
curl -fsSL https://ahmadrosid.com/blog/integrating-mayar-id-payments/SKILL.md -o .claude/skills/mayar-id-payments/SKILL.md
 
# Cursor
mkdir -p .cursor/skills/mayar-id-payments
curl -fsSL https://ahmadrosid.com/blog/integrating-mayar-id-payments/SKILL.md -o .cursor/skills/mayar-id-payments/SKILL.md

---
name: mayar-id-payments
description: "Add Mayar.id (Indonesian payment gateway) payments to a SaaS: invoice checkout for any quantity, payment.received webhook, and self-managed monthly renewals in IDR. Use when the user mentions Mayar, mayar.id, mayar.club, Indonesian payments, QRIS, virtual account or e-wallet billing, or selling seats/slots/plans monthly in Rupiah."
---
 
# Mayar.id payments for a SaaS
 
Mayar is an Indonesian payment gateway: prices in Rupiah, QRIS, bank virtual accounts and e-wallets. Full guide: https://ahmadrosid.com/blog/integrating-mayar-id-payments
 
## When to use
 
- Monthly paid access in IDR (seats, workspaces, plans, credit packs) through Mayar.
- Wiring Mayar's `payment.received` webhook into what a customer can use.
 
## When not to use
 
- One-off sales with nothing to unlock later: a Mayar payment link is enough.
 
## Non-negotiables
 
1. Use `POST /invoices/create` (plural) with `items[{quantity, rate, description}]`. Avoid Mayar Membership when a customer may buy more than one: it allows one registration per email per tier and has no quantity.
2. Send the customer's real email, unmodified.
3. Insert pending seats and a `billing_orders` row before calling Mayar. If Mayar errors, mark the order failed and its seats inactive.
4. Save `id` (invoice), `transactionId` and `link` from the response. The webhook's `data.transactionId` equals that `transactionId`.
5. Unlock only after `payment.received` with `data.status: "SUCCESS"` AND `GET /invoices/{invoiceId}` reporting `paid`. Never on the redirect back.
6. Apply an order exactly once with a conditional `pending|expired → paid` update.
7. Check the webhook's `?token=` shared secret; Mayar does not sign requests.
8. `mobile` is required (at least 10 characters). Ask at checkout only if the account has no phone; store it on the order for renewals.
9. Set `redirectUrl` to the app's dashboard with a "payment received" message, and `extraData.orderId` to the local order id.
10. Run one background sweep every ~10 minutes on a single instance: poll pending orders from the last 48 h, expire overdue orders, expire lapsed seats, then send one renewal invoice per customer for seats ending within 7 days.
 
## Environment
 
| Variable | Purpose |
|---|---|
| `MAYAR_API_KEY` | Read & Write key; needed by the web app and the background job |
| `MAYAR_API_BASE` | `https://api.mayar.club/hl/v2` (sandbox) or `https://api.mayar.id/hl/v2` (production) |
| `MAYAR_WEBHOOK_TOKEN` | Shared secret in the webhook URL's `?token=` |
| `APP_URL` | Base for `redirectUrl` |
 
## Build order
 
1. Schema: `seats` (`pending|active|inactive`, `current_period_end`) and `billing_orders` (`kind`, `quantity`, `seat_ids`, customer email/name/mobile, Mayar invoice and transaction ids, `invoice_url`, `invoice_expires_at`, `status`, `paid_at`).
2. Client: `mayarFetch` (Bearer auth, unwrap `data`, surface `data[].message` on validation errors), `createInvoice`, `getInvoice`.
3. Checkout: quantity picker with a live total, phone field when needed, redirect to `link`.
4. Webhook route: token check → find order by transaction id → `getInvoice` → apply once → 200.
5. Background sweep with the four steps above, settling payments before expiring anything.
6. Dashboard banner for a pending renewal, linking to `invoice_url`.
7. Tests: N seats in one order, Mayar error releases seats, duplicate webhook, fake unpaid webhook, renewal paid early and late, one renewal per customer, expiry.
 
## API shapes
 
```http
POST {MAYAR_API_BASE}/invoices/create
Authorization: Bearer {MAYAR_API_KEY}
 
{
  "name": "...", "email": "...", "mobile": "081234567890",
  "description": "...", "expiredAt": "2026-10-19T04:22:45.000Z",
  "redirectUrl": "https://app.example/dashboard?billing=success",
  "items": [{ "quantity": 3, "rate": 100000, "description": "Seat (1 month)" }],
  "extraData": { "orderId": "..." }
}
→ data: { id, transactionId, link, expiredAt, extraData }
 
GET {MAYAR_API_BASE}/invoices/{id}
→ data: { status: "unpaid" | "paid", transactionId, ... }
```
 
Webhook `payment.received` for an invoice: `data.transactionId` (same as create), `data.productId` (invoice id), `data.productType: "invoice"`, `data.status: "SUCCESS"`, `data.extraData`.
 
## Output expectations
 
1. Propose a file map for this repo first (client, checkout, webhook route, schema/migration, background job, UI).
2. Use the repo's existing stack and keep Mayar code in one billing module.
3. Finish with the env vars to set for each process and the exact webhook URL to register.