Accept USDC Payments with FlareHQ Hosted Checkout Page

FlareHQ’s hosted checkout gives you a fully pre-built USDC payment page with zero front-end work. Your server creates a checkout session, receives a unique URL at flarehq.xyz/checkout/{reference}, and redirects your customer there to complete payment on Arc testnet. When the payment settles — or the customer cancels — FlareHQ bounces them back to whichever URLs you supply.

How It Works

Request Parameters

string

required

Payment amount as a decimal string, e.g. "15.00". USDC has 6 decimal places; values are validated to two decimal places by the API.

string

required

Must be "USDC". Arc testnet payments are denominated in USDC only.

string

required

The 0x wallet address that will receive the USDC on Arc testnet (chain ID 5042002).

string

Short description shown to the customer on the checkout page, e.g. "Pro Subscription".

string

required

Full URL to redirect the customer to after a successful payment.

string

required

Full URL to redirect the customer to if they abandon or cancel checkout.

object

Arbitrary key-value pairs stored alongside the payment record. Use this to attach your internal identifiers — order IDs, customer IDs, plan names — so you can reconcile webhooks without a separate lookup.

string

URL that FlareHQ will POST payment lifecycle events to. See Webhook Events below.

Response Fields

boolean

true when the session was created successfully.

string

Unique session identifier in the format arc_ref_.... Use this to poll status or correlate webhook events.

string

The full hosted checkout URL — https://flarehq.xyz/checkout/{reference}. Redirect your customer here immediately after creation. Returned as session.url by the SDK.

string

Initial status of the session. Always "ready" on creation.

string

ISO 8601 timestamp 120 minutes from creation. The session is invalid after this time and the checkout page will show an expiry error.

Example Response

{
  "success": true,
  "reference": "arc_ref_k7x9mq2z1a8b",
  "url": "https://flarehq.xyz/checkout/arc_ref_k7x9mq2z1a8b",
  "status": "ready",
  "expiresAt": "2025-01-15T14:30:00.000Z"
}

Webhook Events

FlareHQ delivers a POST request to your webhookUrl when payment status changes. Verify requests by checking the x-flarehq-signature header against your webhook secret.

Event	Fired when
`payment.completed`	USDC successfully transferred to the recipient address
`payment.failed`	Customer’s wallet rejected the transaction or an onchain error occurred

Example Payload — `payment.completed`

{
  "event": "payment.completed",
  "reference": "arc_ref_k7x9mq2z1a8b",
  "amount": "15.00",
  "currency": "USDC",
  "recipient": "0x3500000000000000000000000000000000008004",
  "metadata": { "customerId": "usr_123" },
  "txHash": "0xabc123...",
  "completedAt": "2025-01-15T13:12:44.000Z"
}

Full Next.js Example

The following API route creates a checkout session and returns the redirect URL to your front-end in a single request.

src/app/api/checkout/route.ts

import { NextRequest, NextResponse } from 'next/server';
import { FlareHQ } from '@flarehq/sdk';

const flarehq = new FlareHQ({ apiKey: process.env.FLAREHQ_SECRET_KEY! });

export async function POST(req: NextRequest) {
  const { customerId, plan } = await req.json();

  const session = await flarehq.checkout.createSession({
    amount: '15.00',
    currency: 'USDC',
    recipient: '0x3500000000000000000000000000000000008004',
    description: `${plan} Subscription`,
    successUrl: `${process.env.NEXT_PUBLIC_BASE_URL}/success`,
    cancelUrl: `${process.env.NEXT_PUBLIC_BASE_URL}/pricing`,
    metadata: { customerId, plan },
    webhookUrl: `${process.env.NEXT_PUBLIC_BASE_URL}/api/webhooks/flarehq`,
  });

  return NextResponse.json({ url: session.url });
}

Use the metadata field to attach your own order or customer IDs to every session. When the payment.completed webhook fires, that metadata comes back in the payload — so you can fulfil the order without an extra database lookup.

Session Expiry

Checkout sessions expire 120 minutes after creation. If a customer returns to the link after it expires, they will see an error. Create a new session on demand — don’t generate sessions ahead of time and cache the URLs.

Get Started

Payments

x402 Protocol

Agentic Finance

Developer Guide

Accept USDC Payments with FlareHQ Hosted Checkout Page

How It Works

Request Parameters

Response Fields

Example Response

Webhook Events

Example Payload — `payment.completed`

Full Next.js Example

Session Expiry

​How It Works

​Request Parameters

​Response Fields

​Example Response

​Webhook Events

​Example Payload — payment.completed

​Full Next.js Example

​Session Expiry

How It Works

Request Parameters

Response Fields

Example Response

Webhook Events

Example Payload — `payment.completed`

Full Next.js Example

Session Expiry