Trigger Checkout Settlement — POST /api/checkout/pay

Settlement trigger used by the customer checkout page. Calling it attempts to settle a payment that is currently in a payable state. The route holds the real settlement API key server-side — no secret is ever exposed to the browser — and forwards the request to the internal settlement engine using the caller’s reference. This endpoint is public — no authentication is required — and is rate-limited to 30 requests per minute under the payments bucket. Only payments in PENDING or SETTLEMENT_ERROR status can be triggered this way.

Endpoint

POST https://flarehq.xyz/api/checkout/pay

Request

Headers

Header	Value
`x-api-key`	Not required — this endpoint is public. No authentication is needed.
`Content-Type`	`application/json` — required

Body Parameters

string

required

The payment reference to settle (e.g. arc_ref_k7x2m9lp4d8f1q2z). The payment must exist and be in PENDING or SETTLEMENT_ERROR status.

Response

The response mirrors what the internal settlement engine returns. The success shape depends on the settlement path taken.

boolean

true when the payment settled successfully.

string

Which settlement path ran:

"ONCHAIN_SCA_TRANSFER" — USDC moved from the payer’s Circle wallet directly to the merchant on Arc.
"CCTP_BRIDGE" — USDC was settled cross-chain via CCTP.

object

The updated payment record from the ledger after settlement.

string

The Arc Mainnet transaction hash for the on-chain transfer or redemption.

string

Present only for "ONCHAIN_SCA_TRANSFER" settlements — the Circle developer-controlled wallet transaction ID that performed the transfer.

Examples

curl -X POST https://flarehq.xyz/api/checkout/pay \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "arc_ref_k7x2m9lp4d8f1q2z"
  }'

const res = await fetch('https://flarehq.xyz/api/checkout/pay', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ reference: 'arc_ref_k7x2m9lp4d8f1q2z' }),
});

const { success, settlementType, transaction, arcTxHash, circleTxId } = await res.json();

Success Response — On-chain SCA Transfer

{
  "success": true,
  "settlementType": "ONCHAIN_SCA_TRANSFER",
  "transaction": {
    "reference": "arc_ref_k7x2m9lp4d8f1q2z",
    "status": "SUCCESS",
    "arcTxHash": "0x4c8e9f2a..."
  },
  "arcTxHash": "0x4c8e9f2a...",
  "circleTxId": "5f2a9d81-..."
}

Success Response — CCTP Bridge

{
  "success": true,
  "settlementType": "CCTP_BRIDGE",
  "transaction": {
    "reference": "arc_ref_k7x2m9lp4d8f1q2z",
    "status": "REDEEMED_AND_MINTED",
    "arcTxHash": "0x7b31a4d0..."
  },
  "arcTxHash": "0x7b31a4d0..."
}

Error Responses

{
  "success": false,
  "error": "reference is required."
}

{
  "success": false,
  "error": "Payment reference not found."
}

{
  "success": false,
  "error": "Payment is not in a payable state.",
  "status": "SUCCESS"
}

{
  "success": false,
  "error": "Rate limit exceeded. Too many requests."
}

Notes

Only payments in PENDING or SETTLEMENT_ERROR status are accepted. A payment that is already processing, settled, or failed is rejected with HTTP 409 and its current status is echoed back in the response body.

This route never exposes the settlement API key to the browser — it is held server-side and attached only to the internal call. Treat this endpoint as a browser-safe trigger; all ownership, expiry, and idempotency checks are enforced by the settlement engine.

If a settlement returns an error, the payment is marked SETTLEMENT_ERROR and remains payable — retry the same POST /api/checkout/pay call with the same reference to resume it.

Overview

Payments

Escrow

Streaming

CCTP Bridge

Checkout

x402

Agents

Jobs

Merchant

Consumer

Payroll

Trigger Checkout Settlement — POST /api/checkout/pay

Endpoint

Request

Headers

Body Parameters

Response

Examples

Success Response — On-chain SCA Transfer

Success Response — CCTP Bridge

Error Responses

Notes

​Endpoint

​Request

​Headers

​Body Parameters

​Response

​Examples

​Success Response — On-chain SCA Transfer

​Success Response — CCTP Bridge

​Error Responses

​Notes

Endpoint

Request

Headers

Body Parameters

Response

Examples

Success Response — On-chain SCA Transfer

Success Response — CCTP Bridge

Error Responses

Notes