HitPay Integration

Payment gateway integration for APAC businesses using Next.js and JavaScript/TypeScript. Supports card payments via redirect and QR-based payments (PayNow, GrabPay, etc.) via embedded QR codes.

When to Apply

Reference this skill when:

• Integrating HitPay payment gateway
• Creating payment checkout flows
• Implementing QR code payments (PayNow, GrabPay, ShopeePay)
• Handling payment webhooks
• Processing refunds

Step 1: Determine Payment Methods

Ask which payment methods the customer wants to support:

Card-Only Methods

• card (Visa, Mastercard, Amex)

QR-Only Methods

• paynow_online (Singapore)
• grabpay_direct
• shopee_pay
• wechat
• alipay
• fpx (Malaysia)
• promptpay (Thailand)
• truemoney (Thailand)
• vietqr (Vietnam)
• qris (Indonesia)
• upi (India)
• gcash (Philippines)

Step 2: Choose Frontend Approach

API Basics

Authentication

typescript
1const headers = {
2  'X-BUSINESS-API-KEY': process.env.HITPAY_API_KEY,
3  'Content-Type': 'application/json',
4};

Get API keys from Settings → Payment Gateway → API Keys in your HitPay dashboard.

Frontend Option A: Redirect (Cards)

Best for card payments or when you want HitPay to handle the full checkout UI.

Flow

1. Backend creates payment request
2. Frontend redirects to response.url
3. Customer pays on HitPay hosted page
4. Customer returns to your redirect_url
5. Backend confirms via webhook

Next.js API Route

typescript
1// app/api/payments/create/route.ts
2import { NextResponse } from 'next/server';
3
4export async function POST(request: Request) {
5  const { amount, currency, orderId } = await request.json();
6
7  const response = await fetch('https://api.sandbox.hit-pay.com/v1/payment-requests', {
8    method: 'POST',
9    headers: {
10      'X-BUSINESS-API-KEY': process.env.HITPAY_API_KEY!,
11      'Content-Type': 'application/json',
12    },
13    body: JSON.stringify({
14      amount,
15      currency,
16      payment_methods: ['card'],
17      reference_number: orderId,
18      redirect_url: `${process.env.NEXT_PUBLIC_APP_URL}/payment/complete`,
19      webhook: `${process.env.NEXT_PUBLIC_APP_URL}/api/webhooks/hitpay`,
20    }),
21  });
22
23  const data = await response.json();
24  return NextResponse.json({ url: data.url, paymentRequestId: data.id });
25}

Frontend Component

typescript
1// components/CheckoutButton.tsx
2'use client';
3
4export function CheckoutButton({ amount, currency, orderId }: Props) {
5  const handleCheckout = async () => {
6    const response = await fetch('/api/payments/create', {
7      method: 'POST',
8      headers: { 'Content-Type': 'application/json' },
9      body: JSON.stringify({ amount, currency, orderId }),
10    });
11
12    const { url } = await response.json();
13    window.location.href = url; // Redirect to HitPay
14  };
15
16  return <button onClick={handleCheckout}>Pay with Card</button>;
17}

Frontend Option B: Embedded QR Code

Best for QR-based payments where customer stays on your site.

Flow

1. Backend creates payment request with generate_qr: true
2. Frontend renders QR code from response.qr_code_data
3. Customer scans with payment app
4. Frontend polls for status or listens for webhook
5. Backend confirms via webhook

Next.js API Route

typescript
1// app/api/payments/create-qr/route.ts
2import { NextResponse } from 'next/server';
3
4export async function POST(request: Request) {
5  const { amount, currency, orderId, paymentMethod } = await request.json();
6
7  const response = await fetch('https://api.sandbox.hit-pay.com/v1/payment-requests', {
8    method: 'POST',
9    headers: {
10      'X-BUSINESS-API-KEY': process.env.HITPAY_API_KEY!,
11      'Content-Type': 'application/json',
12    },
13    body: JSON.stringify({
14      amount,
15      currency,
16      payment_methods: [paymentMethod],
17      generate_qr: true,
18      reference_number: orderId,
19      webhook: `${process.env.NEXT_PUBLIC_APP_URL}/api/webhooks/hitpay`,
20    }),
21  });
22
23  const data = await response.json();
24  return NextResponse.json({
25    paymentRequestId: data.id,
26    qrCodeData: data.qr_code_data,
27  });
28}

Frontend Component

typescript
1// components/QRPayment.tsx
2'use client';
3
4import { useEffect, useRef } from 'react';
5import QRCode from 'qrcode';
6
7export function QRPayment({ amount, currency, orderId, paymentMethod }: Props) {
8  const canvasRef = useRef<HTMLCanvasElement>(null);
9
10  useEffect(() => {
11    const createQR = async () => {
12      const response = await fetch('/api/payments/create-qr', {
13        method: 'POST',
14        headers: { 'Content-Type': 'application/json' },
15        body: JSON.stringify({ amount, currency, orderId, paymentMethod }),
16      });
17
18      const { qrCodeData } = await response.json();
19
20      if (canvasRef.current && qrCodeData) {
21        await QRCode.toCanvas(canvasRef.current, qrCodeData, { width: 256 });
22      }
23    };
24
25    createQR();
26  }, [amount, currency, orderId, paymentMethod]);
27
28  return (
29    <div>
30      <canvas ref={canvasRef} />
31      <p>Scan with your payment app</p>
32    </div>
33  );
34}

Frontend Option C: Payment Method Selector

Best for supporting both cards and QR methods.

Frontend Component

typescript
1// components/PaymentMethodSelector.tsx
2'use client';
3
4import { useState } from 'react';
5import { QRPayment } from './QRPayment';
6
7const PAYMENT_METHODS = [
8  { id: 'card', label: 'Credit/Debit Card', type: 'redirect' },
9  { id: 'paynow_online', label: 'PayNow', type: 'qr' },
10  { id: 'grabpay_direct', label: 'GrabPay', type: 'qr' },
11  { id: 'shopee_pay', label: 'ShopeePay', type: 'qr' },
12];
13
14export function PaymentMethodSelector({ amount, currency, orderId }: Props) {
15  const [selected, setSelected] = useState<string | null>(null);
16
17  const handlePayment = async (method: typeof PAYMENT_METHODS[0]) => {
18    if (method.type === 'redirect') {
19      const response = await fetch('/api/payments/create', {
20        method: 'POST',
21        headers: { 'Content-Type': 'application/json' },
22        body: JSON.stringify({ amount, currency, orderId }),
23      });
24      const { url } = await response.json();
25      window.location.href = url;
26    } else {
27      setSelected(method.id);
28    }
29  };
30
31  if (selected) {
32    return (
33      <QRPayment
34        amount={amount}
35        currency={currency}
36        orderId={orderId}
37        paymentMethod={selected}
38      />
39    );
40  }
41
42  return (
43    <div>
44      <h3>Select Payment Method</h3>
45      {PAYMENT_METHODS.map((method) => (
46        <button key={method.id} onClick={() => handlePayment(method)}>
47          {method.label}
48        </button>
49      ))}
50    </div>
51  );
52}

Webhook Handling

Always verify webhook signatures before processing. See references/webhook-events.md for details.

typescript
1// app/api/webhooks/hitpay/route.ts
2import { NextResponse } from 'next/server';
3import crypto from 'crypto';
4
5export async function POST(request: Request) {
6  const body = await request.text();
7  const signature = request.headers.get('Hitpay-Signature');
8
9  // Verify signature
10  const expectedSignature = crypto
11    .createHmac('sha256', process.env.HITPAY_SALT!)
12    .update(body)
13    .digest('hex');
14
15  if (signature !== expectedSignature) {
16    return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
17  }
18
19  const payload = JSON.parse(body);
20
21  // Process payment confirmation
22  if (payload.status === 'completed') {
23    // Mark order as paid
24    await markOrderAsPaid(payload.reference_number);
25  }
26
27  return NextResponse.json({ received: true });
28}

Checking Payment Status

See references/payment-request-api.md for the full API reference.

typescript
1// app/api/payments/[id]/route.ts
2export async function GET(
3  request: Request,
4  { params }: { params: { id: string } }
5) {
6  const response = await fetch(
7    `https://api.sandbox.hit-pay.com/v1/payment-requests/${params.id}`,
8    {
9      headers: {
10        'X-BUSINESS-API-KEY': process.env.HITPAY_API_KEY!,
11      },
12    }
13  );
14
15  const data = await response.json();
16  return NextResponse.json(data);
17}

Refunds

See references/refunds.md for full details.

typescript
1// app/api/payments/[id]/refund/route.ts
2export async function POST(
3  request: Request,
4  { params }: { params: { id: string } }
5) {
6  const { amount } = await request.json();
7
8  const response = await fetch(
9    `https://api.sandbox.hit-pay.com/v1/payment-requests/${params.id}/refund`,
10    {
11      method: 'POST',
12      headers: {
13        'X-BUSINESS-API-KEY': process.env.HITPAY_API_KEY!,
14        'Content-Type': 'application/json',
15      },
16      body: JSON.stringify({ amount }),
17    }
18  );
19
20  const data = await response.json();
21  return NextResponse.json(data);
22}

Environment Variables

bash
1# .env.local
2HITPAY_API_KEY=your_api_key
3HITPAY_SALT=your_webhook_salt
4NEXT_PUBLIC_APP_URL=http://localhost:3000

Test Cards (Sandbox)

Resources

• Sandbox Dashboard: https://dashboard.sandbox.hit-pay.com
• Production Dashboard: https://dashboard.hit-pay.com
• API Docs: https://docs.hitpayapp.com