Developer documentation

npm install @vitix/pay# .env.localVITIX_API_KEY=vx_test_••••••••••••••••••••••••••••••••VITIX_WEBHOOK_SECRET=whsec_••••••••••••••••••••••••••••••••••••••••••=

import { VitixPay } from "@vitix/pay";const vitix = new VitixPay(process.env.VITIX_API_KEY!);// On your server, when the customer picks an amountconst checkout = await vitix.checkouts.create(  {    amount: 2000,                 // $20.00, in cents    currency: "usd",              // or "vnd" (amount in đồng)    customer: { id: "user_42", email: "[email protected]" },    reference: "topup_8f1c",      // your own id, echoed on the payment    success_url: "https://app.example.com/billing/success?cs={CHECKOUT_ID}",    cancel_url: "https://app.example.com/billing",  },  { idempotencyKey: "topup_8f1c" },);// Send the customer to the hosted checkout pageredirect(checkout.url);

{  "id": "cs_live_0aWdSNgZbvGU0BjvCISLh07o",  "object": "checkout",  "livemode": true,  "status": "open",  "payment_status": "unpaid",  "amount": 600000,  "currency": "vnd",  "amount_usd": 2308,  "description": "Acme credits",  "customer": { "id": "user_42", "email": "[email protected]", "name": "Ana Nguyen" },  "reference": "topup_8f1c",  "metadata": { "plan": "pro" },  "success_url": "https://app.example.com/billing/success?cs={CHECKOUT_ID}",  "cancel_url": "https://app.example.com/billing",  "url": "https://vitix.net/pay?cs=cs_live_0aWdSNgZbvGU0BjvCISLh07o",  "payment": null,  "expires_at": "2026-10-14T07:32:45.000Z",  "completed_at": null,  "created_at": "2026-10-14T06:32:45.156Z"}

// app/billing/success/page.tsx (Next.js, server component)import { VitixPay } from "@vitix/pay";export default async function Success({ searchParams }: { searchParams: Promise<{ cs?: string }> }) {  const { cs } = await searchParams;  const vitix = new VitixPay(process.env.VITIX_API_KEY!);  const checkout = await vitix.checkouts.retrieve(cs!);  if (checkout.payment_status === "paid") {    return <p>Thanks! ${(checkout.amount_usd / 100).toFixed(2)} was added to your account.</p>;  }  // The webhook may still be on its way: show a pending state and poll, never credit here.  return <p>Confirming your payment…</p>;}

// app/api/vitix/webhook/route.tsimport { Webhooks, WebhookSignatureError } from "@vitix/pay";export async function POST(req: Request) {  const body = await req.text();  let event;  try {    event = await Webhooks.constructEvent(body, req.headers, process.env.VITIX_WEBHOOK_SECRET!);  } catch (err) {    if (err instanceof WebhookSignatureError) return new Response("Invalid signature", { status: 400 });    throw err;  }  if (event.type === "payment.succeeded") {    const payment = event.data.object;    // Idempotent: use event.id (or payment.id) as the unique key of your ledger row.    await creditCustomer({ userId: payment.customer!.id, usdCents: payment.amount_usd, key: payment.id });  }  return new Response("ok");}