> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitpayapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# HitPay for Vercel

> Accept HitPay payments from your Vercel apps with the HitPay integration or Vercel Connect. No API keys to copy.

There are two ways to use HitPay from a Vercel project. Both use HitPay sign-in (OAuth), so there are no API keys to copy.

| | HitPay integration (recommended) | Vercel Connect |
| - | - | - |
| Setup | Install from the Vercel Marketplace and sign in to HitPay | Create your own HitPay app, then add a Vercel connector |
| How your app gets a token | Reads `HITPAY_ACCESS_TOKEN` from the project | Asks Vercel for one at runtime |
| Token stored in your project | Yes, as a sensitive environment variable | No |
| Token refresh | Yearly, then you redeploy | Automatic, no redeploy |
| HitPay scopes | Create and read payments | Any scopes HitPay approves for your app |
| Cost | Free | Vercel bills Connect per token request |

## Use the HitPay integration (recommended)

The [HitPay integration](https://vercel.com/integrations/hitpay) connects your HitPay account in a few clicks and writes a HitPay token to your projects as environment variables.

### Prerequisites

* A Vercel account or team
* A HitPay account where you're an **Owner** or **Admin**

<Steps>
  <Step title="Add the integration">
    Open the [HitPay integration on Vercel](https://vercel.com/integrations/hitpay) and click **Connect Account**. Choose your Vercel team and the projects to connect.
  </Step>

  <Step title="Connect your HitPay account">
    Vercel opens the HitPay setup page. Click **Connect HitPay**, sign in to HitPay, choose your business if you have more than one, and approve access.

    <Frame>
      <img src="https://mintcdn.com/hitpay/WytL9VZOyl9gOF-H/images/apis/guide/vercel/connect.png?fit=max&auto=format&n=WytL9VZOyl9gOF-H&q=85&s=273802806af466e070211b995d10339d" alt="Connect your HitPay account card showing a live connection and the approved access scopes" width="1920" height="1080" data-path="images/apis/guide/vercel/connect.png" />
    </Frame>
  </Step>

  <Step title="Choose your projects">
    Select the Vercel projects that should receive HitPay credentials, then click **Save env vars to projects**.

    <Frame>
      <img src="https://mintcdn.com/hitpay/WytL9VZOyl9gOF-H/images/apis/guide/vercel/projects.png?fit=max&auto=format&n=WytL9VZOyl9gOF-H&q=85&s=e3710f379c18ade89f8a1ec0a32be365" alt="Project picker with storefront and checkout-api selected" width="1920" height="1080" data-path="images/apis/guide/vercel/projects.png" />
    </Frame>
  </Step>

  <Step title="Redeploy">
    Click **Return to Vercel**, then redeploy your projects. Vercel only applies new environment variables to new deployments.

    <Frame>
      <img src="https://mintcdn.com/hitpay/WytL9VZOyl9gOF-H/images/apis/guide/vercel/env-vars.png?fit=max&auto=format&n=WytL9VZOyl9gOF-H&q=85&s=e6e5b396fc708242efaca9d3b1b594c5" alt="Environment variables written by the integration: HITPAY_ACCESS_TOKEN, HITPAY_API_BASE, HITPAY_API_MODE and HITPAY_BUSINESS_ID" width="1920" height="1080" data-path="images/apis/guide/vercel/env-vars.png" />
    </Frame>
  </Step>
</Steps>

Each project you select receives these environment variables:

| Variable | Value | Environments |
| - | - | - |
| `HITPAY_ACCESS_TOKEN` | OAuth access token for your HitPay business (sensitive) | Production, Preview |
| `HITPAY_API_BASE` | `https://api.hit-pay.com` (optional in code; default to this value) | All |
| `HITPAY_API_MODE` | `live` | All |
| `HITPAY_BUSINESS_ID` | Your HitPay business ID | All |

### What the integration's token can do

The integration requests `business:read`, `payments:read` and `payments:create`. Its token can:

* Read your business profile (`GET /v1/info`)
* Create payment requests
* Read payment requests and payments

It can't refund or cancel payments, or manage recurring billing, products, orders, invoices or customers. For those, use [Vercel Connect](#use-vercel-connect) with a HitPay app that has the [scopes](/platforms/oauth#scopes) you need.

### Manage the integration

**Change projects or reconnect**: In your Vercel dashboard, go to **Integrations**, open **HitPay**, and click **Configure**. Open it in the same browser you installed with.

**Token refresh**: Access tokens last one year. The integration refreshes them 30 days before they expire and updates `HITPAY_ACCESS_TOKEN` on your projects. Redeploy to pick up the new token.

**Uninstall**: Remove the integration from your Vercel dashboard. The integration deletes the HitPay environment variables it added to your projects.

## Use Vercel Connect

With [Vercel Connect](https://vercel.com/docs/connect), Vercel keeps your HitPay approval and gives your app a short-lived token when it needs one. Nothing secret is stored in your project, and refreshed tokens take effect without a redeploy. It takes more setup than the integration: you create your own HitPay app and a connector in your Vercel team. Use it if you need scopes the integration doesn't request, or don't want a token stored in your project.

### Prerequisites

* A Vercel account or team with access to [Vercel Connect](https://vercel.com/docs/connect)
* A HitPay account where you're an **Owner** or **Admin**

<Steps>
  <Step title="Create a HitPay app">
    In your HitPay dashboard, go to **Developers** > **App Builder** and click **New App**. Add `https://connect.vercel.com/callback` to **Redirect URIs**, then save the client ID and client secret. The secret is shown only once.
  </Step>

  <Step title="Request payment scopes">
    New apps only have `business:read`. In the app's detail panel, click **Request Scopes** and request the scopes you need, such as `payments`. Wait until HitPay approves the request before you continue. See [scopes](/platforms/oauth#scopes).
  </Step>

  <Step title="Add a HitPay connector in Vercel">
    In your Vercel dashboard, go to **Connect** > **Add Connection** > **OAuth** > **Bring Your Own**, and enter:

    | Field | Value |
    | - | - |
    | Server URL | `https://api.hit-pay.com` |
    | Authorization endpoint | `https://dashboard.hit-pay.com/oauth/authorize` |
    | Token endpoint | `https://api.hit-pay.com/v1/open/oauth/token` |
    | Client ID and secret | From your HitPay app |
    | Token auth method | `client_secret_post` |

    <Note>
      Vercel shows "Discovery did not find OAuth metadata for this server URL." This is expected. Fill in the endpoints yourself.
    </Note>
  </Step>

  <Step title="Connect your project">
    On the connector page, click **Connect Project** and choose the project that takes payments. Click **Test User Token**, sign in to HitPay and approve access to check that the connector works.
  </Step>

  <Step title="Get a token in your code">
    Install `@vercel/connect`. Request a token for the connector, and if the merchant hasn't approved HitPay access yet, send them to the approval URL:

    ```ts lib/hitpay-token.ts theme={"system"}
    import {
      getToken,
      startAuthorization,
      UserAuthorizationRequiredError,
    } from "@vercel/connect";

    const CONNECTOR = "api.hit-pay.com/hitpay"; // the connector UID shown in Vercel

    export async function hitpayToken(userId: string, returnUrl: string) {
      const subject = { type: "user" as const, id: userId };
      try {
        return { token: await getToken(CONNECTOR, { subject }) };
      } catch (err) {
        if (err instanceof UserAuthorizationRequiredError) {
          const { url } = await startAuthorization(CONNECTOR, { subject }, { callbackUrl: returnUrl });
          return { authorizeUrl: url };
        }
        throw err;
      }
    }
    ```

    `userId` is your app's ID for the merchant. Connect stores one HitPay approval per user ID.
  </Step>
</Steps>

Then call HitPay with the token, as in [Accept a payment](#accept-a-payment).

## Accept a payment

Call the HitPay API from your server with the token as a Bearer token. Requests and responses are the same as with an API key; only the `Authorization` header changes. Use the token server-side only.

<Steps>
  <Step title="Create a payment request">
    ```ts app/api/checkout/route.ts theme={"system"}
    export async function POST(request: Request) {
      const base = process.env.HITPAY_API_BASE ?? "https://api.hit-pay.com";
      // Vercel Connect: const { token } = await hitpayToken(userId, returnUrl);
      const token = process.env.HITPAY_ACCESS_TOKEN;
      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();
      // Store `id` with your order, then send the customer to `url`.
      return Response.json({ id, url });
    }
    ```
  </Step>

  <Step title="Send the customer to checkout">
    Redirect the customer to the returned `url`. HitPay's hosted checkout shows the payment methods enabled on your account, such as PayNow, GrabPay and cards.
  </Step>

  <Step title="Confirm the payment">
    When the customer returns to your `redirect_url`, read the payment request from HitPay and check that its `status` is `completed`:

    ```ts theme={"system"}
    const res = await fetch(`${base}/v1/payment-requests/${id}`, {
      headers: { Authorization: `Bearer ${token}` },
    });
    const { status } = await res.json(); // "completed" once paid
    ```

    <Warning>
      Don't treat the redirect itself as proof of payment. Always confirm the status with the API.
    </Warning>
  </Step>
</Steps>

You can also pass a `webhook` URL when you create the payment request to have HitPay notify your server when the payment completes.

Webhook registration, virtual accounts, static QR codes and terminals aren't available with OAuth tokens and still need a HitPay API key. See [Connect Merchant Accounts (OAuth)](/platforms/oauth).

<Note>
  Both options connect live HitPay accounts, so payments made while testing are real. Use a small amount and refund it from your HitPay dashboard.
</Note>

## Use with v0 and other AI coding tools

v0 can't run the integration's install flow or set up a Connect connector, so it may ask you to paste `HITPAY_ACCESS_TOKEN` or `HITPAY_API_BASE` into an environment variable form. Skip that form. Install the HitPay integration on the project your v0 chat deploys to, then deploy again.

You don't need `HITPAY_API_BASE`: the code above defaults it to `https://api.hit-pay.com`.

<Tip>
  Point your agent at [vercel-connect.hitpay.dev/llms.txt](https://vercel-connect.hitpay.dev/llms.txt). It tells AI coding tools how to get a HitPay token instead of asking you for credentials.
</Tip>

## Revoke access

In your HitPay dashboard, go to **Developers** > **Connected Apps** and remove the app. HitPay invalidates its tokens immediately, and API calls return `401 Unauthorized`. Send the merchant through approval again to reconnect.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The integration's setup page says this browser isn't authorized">
    The setup page only opens in the browser you installed the integration with. Open **Configure** from the integration in your Vercel dashboard in that browser, or reinstall the integration.
  </Accordion>

  <Accordion title="v0 asks you to enter HITPAY_ACCESS_TOKEN">
    Skip the form. Install the integration on the project the chat deploys to, then redeploy. See [Use with v0 and other AI coding tools](#use-with-v0-and-other-ai-coding-tools).
  </Accordion>

  <Accordion title="Your app can't find HITPAY_ACCESS_TOKEN">
    Redeploy the project. Environment variables only reach deployments created after they're added. `vercel env pull` doesn't download sensitive variables, so the integration's token isn't available locally.
  </Accordion>

  <Accordion title="API calls return 401 Unauthorized">
    The token was revoked or has expired. With the integration, open **Configure**, click **Reconnect**, save the env vars to your projects again, and redeploy. With Vercel Connect, send the merchant through approval again.
  </Accordion>

  <Accordion title="Connect shows an error after you approve access on HitPay">
    Check that `https://connect.vercel.com/callback` is in your HitPay app's redirect URIs, and that HitPay has approved the scopes you need. Only business Owners and Admins can approve access.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.