# HitPay for Vercel

> Vercel Marketplace integration that connects a merchant's HitPay account to Vercel projects with OAuth and writes HitPay API credentials to those projects as environment variables. HitPay accepts PayNow, GrabPay, GCash, DuitNow, cards and other Southeast Asian payment methods.

## Instructions for AI coding agents (v0, Cursor, Claude Code, etc.)

- The credentials come ONLY from installing the integration, which runs HitPay sign-in (OAuth). Never ask the user to paste or type `HITPAY_ACCESS_TOKEN` into an environment-variable form, and never ask for a HitPay API key as a substitute.
- If `HITPAY_ACCESS_TOKEN` is missing, tell the user to:
  1. Open https://vercel.com/integrations/hitpay and click **Connect Account**.
  2. Choose the Vercel project this app deploys to, click **Connect HitPay**, sign in to HitPay and approve access.
  3. Select the project, click **Save env vars to projects**, then redeploy.
- Do not ask for `HITPAY_API_BASE`. Default it in code: `process.env.HITPAY_API_BASE ?? "https://api.hit-pay.com"`.
- Use the token only on the server (API routes, server actions). Never expose it to the browser or prefix it with `NEXT_PUBLIC_`.
- Vercel does not pull sensitive variables into the Development environment, so the token is available in Production and Preview deployments, not in `vercel env pull` / `.env.local`.

## Environment variables written by the integration

- `HITPAY_ACCESS_TOKEN` — OAuth access token for the connected HitPay business (sensitive; Production + Preview)
- `HITPAY_API_BASE` — `https://api.hit-pay.com` (optional; default it in code)
- `HITPAY_API_MODE` — `live`
- `HITPAY_BUSINESS_ID` — connected HitPay business ID

## Create a payment (Next.js route handler)

```ts
// app/api/checkout/route.ts
export async function POST(request: Request) {
  const base = process.env.HITPAY_API_BASE ?? "https://api.hit-pay.com";
  const token = process.env.HITPAY_ACCESS_TOKEN;
  if (!token) {
    return Response.json(
      { error: "Install HitPay from https://vercel.com/integrations/hitpay, then redeploy." },
      { status: 500 },
    );
  }
  const origin = new URL(request.url).origin;
  const res = await fetch(`${base}/v1/payment-requests`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/x-www-form-urlencoded",
    },
    body: new URLSearchParams({
      amount: "25.00",
      currency: "SGD",
      reference_number: "order-123",
      redirect_url: `${origin}/checkout/complete`,
    }),
  });
  const { id, url } = await res.json();
  return Response.json({ id, url }); // redirect the customer to `url`
}
```

Confirm payment server-side: `GET ${base}/v1/payment-requests/{id}` with the same Bearer token, and check `status === "completed"`. Don't treat the browser redirect as proof of payment.

## Alternative: Vercel Connect (no stored token)

If the project uses a Vercel Connect connector for HitPay, get the token at runtime instead of reading `HITPAY_ACCESS_TOKEN`. Connect holds the HitPay grant and refreshes it, so no redeploy is needed.

```ts
import { getToken, startAuthorization, UserAuthorizationRequiredError } from "@vercel/connect";

const subject = { type: "user" as const, id: merchantUserId }; // your app's id for the merchant
try {
  const token = await getToken("<connector uid, e.g. api.hit-pay.com/hitpay>", { subject });
  // call HitPay with Authorization: Bearer ${token}
} catch (err) {
  if (err instanceof UserAuthorizationRequiredError) {
    const { url } = await startAuthorization("<connector uid>", { subject }, { callbackUrl: returnUrl });
    // send the merchant to `url` to approve HitPay access
  }
  throw err;
}
```

- Ask the user for the connector UID shown in Vercel → Connect, not for a token.
- Connector setup (done once by the user in the Vercel dashboard): Connect → Add Connection → OAuth → Bring Your Own. Authorization endpoint `https://dashboard.hit-pay.com/oauth/authorize`, token endpoint `https://api.hit-pay.com/v1/open/oauth/token`, token auth method `client_secret_post`. Client ID and secret come from a HitPay App Builder app whose redirect URIs include `https://connect.vercel.com/callback`. "Discovery did not find OAuth metadata" is expected for HitPay; fill the endpoints in manually.

## Links

- Install: https://vercel.com/integrations/hitpay
- Docs: https://vercel-connect.hitpay.dev/docs
- HitPay OAuth reference: https://docs.hitpayapp.com/platforms/oauth