Verify USDC Payment Status — GET /api/payments/verify

After redirecting a customer through the hosted checkout page — or after receiving a webhook event — call this endpoint to confirm the canonical status of a payment. The response includes the on-chain Arc transaction hash (arcTxHash) once the transfer has settled, letting you cross-reference settlement on the Arc testnet explorer. This is the authoritative source of truth for payment completion; do not rely solely on webhook delivery for settlement confirmation.

Endpoint

GET https://flarehq.xyz/api/payments/verify/{reference}

Request

Headers

Header	Value
`Authorization`	`Bearer fhq_sec_...` — required

Path Parameters

string

required

The arc_ref_... reference string returned by POST /api/payments/initialize. This value uniquely identifies the payment session on the FlareHQ ledger.Example: arc_ref_k7x2m9lp4d8f1q2z

Response

boolean

true when the request was processed successfully (the payment record was found and read without error). Note that status: true does not mean the payment is complete — check data.status for the settlement state.

string

Human-readable description of the current payment state. Examples:

"Verification successful (Cached Testnet Ledger)" — payment is settled and result is cached.
"Payment is pending block confirmation" — payment has been submitted but not yet finalized on-chain.

object

Full payment record at the time of the request.

Show data fields

string

Unique identifier of the payment record.

string

The arc_ref_... reference — mirrors the path parameter you supplied.

number

Payment amount in USDC as a floating-point number (e.g. 25.0).

string

Currency code, e.g. "USDC".

string

Settlement chain identifier, e.g. "Arc Testnet".

string

Current settlement state of the payment. Possible values:

Value	Meaning
`PENDING`	Session created; payer has not yet completed checkout
`SUCCESS`	Payment confirmed and settled on-chain
`FAILED`	Payment attempt was made but did not succeed
`EXPIRED`	Session passed its 120-minute expiry without settlement

string

High-level settlement descriptor: "Successful" for SUCCESS status, "Pending" for all other states.

string | null

On-chain transaction hash of the USDC transfer on the Arc testnet. This value is null until the payment has been confirmed on-chain. Once populated, you can view the transaction at https://testnet.arcscan.app/tx/{arcTxHash}.

string

Email address or wallet address of the payer. Defaults to "autonomous-agent@bot.network" for agent-initiated payments.

string

Merchant or business display name associated with this payment.

string | null

Merchant’s on-chain SCA payout address. null if the merchant has not configured a wallet.

string

ISO 8601 timestamp of when the payment record was created (not necessarily when it settled — check arcTxHash for on-chain confirmation time).

Examples

curl https://flarehq.xyz/api/payments/verify/arc_ref_k7x2m9lp4d8f1q2z \
  -H "Authorization: Bearer fhq_sec_test_..."

const reference = 'arc_ref_k7x2m9lp4d8f1q2z';

const res = await fetch(
  `https://flarehq.xyz/api/payments/verify/${reference}`,
  {
    headers: {
      Authorization: 'Bearer fhq_sec_test_...',
    },
  }
);

const { status, data } = await res.json();

if (status && data.status === 'SUCCESS') {
  console.log('Payment confirmed. Tx hash:', data.arcTxHash);
} else {
  console.log('Payment state:', data.status);
}

import requests

reference = "arc_ref_k7x2m9lp4d8f1q2z"
headers = {"Authorization": "Bearer fhq_sec_test_..."}

resp = requests.get(
    f"https://flarehq.xyz/api/payments/verify/{reference}",
    headers=headers,
)
body = resp.json()

if body["status"] and body["data"]["status"] == "SUCCESS":
    print("Settled. Tx hash:", body["data"]["arcTxHash"])

PENDING Response

{
  "status": true,
  "message": "Payment is pending block confirmation",
  "data": {
    "id": "cm3x9f2a0000108l47bqg9d1e",
    "reference": "arc_ref_k7x2m9lp4d8f1q2z",
    "amount": 25.0,
    "currency": "USDC",
    "chain": "Arc Testnet",
    "gateway_response": "Pending",
    "status": "PENDING",
    "sender_email": "customer@example.com",
    "merchant": "Acme Store",
    "merchantSCA": "0xDeFe5678...",
    "paid_at": "2025-01-15T10:32:00.000Z",
    "arcTxHash": null
  }
}

SUCCESS Response (with on-chain hash)

{
  "status": true,
  "message": "Verification successful (Cached Testnet Ledger)",
  "data": {
    "id": "cm3x9f2a0000108l47bqg9d1e",
    "reference": "arc_ref_k7x2m9lp4d8f1q2z",
    "amount": 25.0,
    "currency": "USDC",
    "chain": "Arc Testnet",
    "gateway_response": "Successful",
    "status": "SUCCESS",
    "sender_email": "customer@example.com",
    "merchant": "Acme Store",
    "merchantSCA": "0xDeFe5678...",
    "paid_at": "2025-01-15T10:32:00.000Z",
    "arcTxHash": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890"
  }
}

Error Responses

{
  "status": false,
  "message": "Transaction reference not found."
}

{
  "status": false,
  "message": "Transaction reference token is missing."
}

Notes

Poll this endpoint after redirecting the customer back from the checkout page, or use it to confirm a payment.completed webhook event before fulfilling an order. Webhooks can fail due to network issues — always treat the verify response as the authoritative settlement record.

Once data.arcTxHash is non-null, you can view the on-chain transaction at https://testnet.arcscan.app/tx/{arcTxHash}. This is useful for debugging and for providing customers with a verifiable settlement receipt.

Avoid polling this endpoint more frequently than every 3–5 seconds for a single reference. All payment endpoints share a rate limit of 30 requests per minute. If you are waiting for settlement, consider setting a webhookUrl during initialization instead of polling continuously.

Overview

Payments

Escrow

Streaming

x402

Agents

Verify USDC Payment Status — GET /api/payments/verify

Endpoint

Request

Headers

Path Parameters

Response

Examples

PENDING Response

SUCCESS Response (with on-chain hash)

Error Responses

Notes

​Endpoint

​Request

​Headers

​Path Parameters

​Response

​Examples

​PENDING Response

​SUCCESS Response (with on-chain hash)

​Error Responses

​Notes

Endpoint

Request

Headers

Path Parameters

Response

Examples

PENDING Response

SUCCESS Response (with on-chain hash)

Error Responses

Notes