Create Payment Link — POST /api/merchant/payment-link

A merchant payment link is a persistent, shareable URL that points to the same hosted checkout flow as initialize, but it stays valid for 24 hours instead of the 120-minute initialize session — closer to an invoice than a quick P2P request. Each link creates a PENDING payment log record on Arc Mainnet using the merchant’s verified payout wallet, and its arc_ref_... reference can be verified or tracked through webhooks. Unlike most FlareHQ payment routes, this endpoint authenticates with the merchant dashboard session cookie only — it does not accept an x-api-key header. You must be signed in to the FlareHQ merchant dashboard when you call it.

Endpoint

POST https://flarehq.xyz/api/merchant/payment-link

Request

Headers

Header	Value
`Cookie`	`merchant_token=...` — dashboard session, required

Body Parameters

string

required

Payment amount denominated in USDC as a decimal string (e.g. "25.00"). Must parse to a number greater than 0.

string

default:"USDC"

Currency code for the link. Defaults to "USDC". Recorded on the ledger for receipts and dashboard exports.

string

Free-form note describing what the link is for (e.g. "Consulting invoice"). Returned as-is in the response.

string

Publicly reachable HTTPS URL that FlareHQ will POST to when the linked payment changes status. If omitted, no webhook is attached to the payment log.

Response

boolean

true when the payment link was created.

string

Unique payment reference with the prefix arc_ref_. Store it to verify payment status and correlate webhook events.Example: "arc_ref_k7x2m9lp4d8f1q2z"

string

Fully-qualified hosted checkout URL for this link. Share this with your customer.Example: "https://flarehq.xyz/checkout/arc_ref_k7x2m9lp4d8f1q2z"

number

The amount as a float — e.g. 25.

string

The currency code, e.g. "USDC".

string | null

The description you supplied, or null if omitted.

string

The merchant’s verified business name, resolved server-side from your merchant record.

string

Fixed value "24 hours" — the link’s lifetime.

Examples

curl -X POST https://flarehq.xyz/api/merchant/payment-link \
  -H "Cookie: merchant_token=YOUR_DASHBOARD_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "25.00",
    "currency": "USDC",
    "description": "Consulting invoice",
    "webhookUrl": "https://yoursite.com/webhooks/flarehq"
  }'

const res = await fetch('https://flarehq.xyz/api/merchant/payment-link', {
  method: 'POST',
  headers: {
    'Cookie': 'merchant_token=YOUR_DASHBOARD_SESSION',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: '25.00',
    currency: 'USDC',
    description: 'Consulting invoice',
  }),
});

const { success, reference, checkoutUrl } = await res.json();
// Share checkoutUrl with your customer

Success Response

{
  "success": true,
  "reference": "arc_ref_k7x2m9lp4d8f1q2z",
  "checkoutUrl": "https://flarehq.xyz/checkout/arc_ref_k7x2m9lp4d8f1q2z",
  "amount": 25,
  "currency": "USDC",
  "description": "Consulting invoice",
  "merchant": "Acme Corp",
  "expiresIn": "24 hours"
}

Error Responses

{
  "success": false,
  "error": "Not authenticated."
}

{
  "success": false,
  "error": "Valid amount is required."
}

{
  "success": false,
  "error": "Your payout wallet is not set up yet. Visit your dashboard to finish wallet setup before creating payment links."
}

List Payment Links (GET)

Endpoint

GET https://flarehq.xyz/api/merchant/payment-link

Request

The same merchant_token cookie is required. No query parameters are supported — the endpoint returns the 100 most recent payment logs for your merchant, ordered newest first.

Response

boolean

true when the list was retrieved.

array

Array of the merchant’s recent payment logs, newest first. Each entry contains:

Show links[].fields

string

The arc_ref_... payment reference.

number

Payment amount as a float — e.g. 25.

string

Currency code, e.g. "USDC".

string

Ledger status, e.g. "PENDING", "SUCCESS", "FAILED", or "EXPIRED".

string

Hosted checkout URL: https://flarehq.xyz/checkout/{reference}.

string

ISO 8601 timestamp when the link was created.

Example Response

{
  "success": true,
  "links": [
    {
      "reference": "arc_ref_k7x2m9lp4d8f1q2z",
      "amount": 25,
      "currency": "USDC",
      "status": "PENDING",
      "checkoutUrl": "https://flarehq.xyz/checkout/arc_ref_k7x2m9lp4d8f1q2z",
      "createdAt": "2026-08-15T10:30:00.000Z"
    }
  ]
}

Notes

Payment links expire 24 hours after creation. After expiry the underlying payment transitions to EXPIRED and the checkout URL becomes inactive — create a fresh link to retry.

Payment links are authenticated by the merchant dashboard cookie, not an API key, so they are best used from the merchant dashboard or server-side code that holds the session. For automated API-key callers, use initialize instead.

You cannot create a payment link until your payout wallet is configured. If the merchant record has no walletAddress, the API returns HTTP 400 — complete wallet setup in your FlareHQ dashboard first. Requests are also rate-limited; the route rejects bursts with the shared payments rate-limit response.

Overview

Payments

Escrow

Streaming

CCTP Bridge

Checkout

x402

Agents

Jobs

Merchant

Consumer

Payroll

Create Payment Link — POST /api/merchant/payment-link

Endpoint

Request

Headers

Body Parameters

Response

Examples

Success Response

Error Responses

List Payment Links (GET)

Endpoint

Request

Response

Example Response

Notes

​Endpoint

​Request

​Headers

​Body Parameters

​Response

​Examples

​Success Response

​Error Responses

​List Payment Links (GET)

​Endpoint

​Request

​Response

​Example Response

​Notes

Endpoint

Request

Headers

Body Parameters

Response

Examples

Success Response

Error Responses

List Payment Links (GET)

Endpoint

Request

Response

Example Response

Notes