Payment Link Checkout

What it is

Payment Link Checkout is a flexible payment flow where your service creates an order, generates a Payment Link for the exact amount, and returns it to the AI agent. The agent (or any other agent) pays the link via FluxA Wallet, then notifies your service. Your service verifies the payment through the FluxA API and fulfills the order.

Unlike the Monetize Gateway, this mode gives you full control over pricing, order lifecycle, and business logic.

How it works

AI Agent            Your Service             FluxA API
   |                     |                      |
   |-- POST /order ----->|                      |
   |                     |-- create payment --->|
   |                     |   link (amount, desc) |
   |                     |<-- pl_xxx + url ------|
   |<-- order + url -----|                      |
   |                     |                      |
   |-- pay link via FluxA Wallet -------------->|
   |<-- payment success ------------------------|
   |                     |                      |
   |-- POST /confirm --->|                      |
   |                     |-- GET pl_xxx ------->|
   |                     |   /payments          |
   |                     |<-- paid: true -------|
   |<-- order fulfilled -|                      |

Agent-to-agent (A2A) flow

Payment Link Checkout also supports agent-to-agent payments. Agent B can pay a link created by Agent A's service — the payer does not have to be the same agent that placed the order.

Agent A (buyer)      Your Service        FluxA API       Agent B (payer)
   |                     |                   |                  |
   |-- POST /order ----->|                   |                  |
   |                     |-- create link --->|                  |
   |<-- order + url -----|                   |                  |
   |                     |                   |                  |
   |-- forward url to Agent B ------------------------------>  |
   |                     |                   |                  |
   |                     |                   |<-- pay link -----|
   |                     |                   |-- success ------>|
   |                     |                   |                  |
   |-- POST /confirm --->|                   |                  |
   |                     |-- verify -------->|                  |
   |<-- order fulfilled -|                   |                  |

This is useful for scenarios like:

Delegation — Agent A places the order, Agent B (a payment agent) handles the payment.
Sponsorship — a third-party agent pays on behalf of the buyer.
Marketplace — a broker agent coordinates between buyer and seller agents.

Step-by-step integration

Step 1 — Agent places an order

The AI agent calls your service to create an order. Your API can accept any parameters relevant to your business (product ID, quantity, configuration, etc.).

bash

curl -X POST https://your-service.com/api/orders \
  -H "Content-Type: application/json" \
  -d '{
    "product": "premium-report",
    "quantity": 1
  }'

Step 2 — Your service creates a payment link

On your backend, calculate the order total and call the FluxA Payment Link API to generate a collection link.

bash

curl -X POST https://walletapi.fluxapay.xyz/api/payment-links \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $YOUR_AGENT_JWT" \
  -d '{
    "amount": "5000000",
    "currency": "USDC",
    "network": "base",
    "description": "Order #1234 — Premium Report",
    "maxUses": 1,
    "expiresAt": "2025-06-01T00:00:00.000Z"
  }'

The response includes:

linkId — e.g. pl_a1b2c3d4
url — the hosted payment page URL

TIP

Set maxUses: 1 for one-time orders to prevent double payments. Use expiresAt to auto-expire unpaid orders.

Step 3 — Return order data with payment link

Your API responds to the agent with the order details and the payment link URL.

json

{
  "orderId": "order_1234",
  "status": "pending_payment",
  "total": "5.00 USDC",
  "paymentUrl": "https://agentwallet.fluxapay.xyz/paymentlink/pl_a1b2c3d4",
  "expiresAt": "2025-06-01T00:00:00.000Z"
}

The agent (or any other agent with access to the URL) can now pay this link.

Step 4 — Agent pays the payment link

The AI agent pays the link through FluxA Wallet. This can happen via:

Browser / wallet UI — the agent opens the paymentUrl and pays.
API (x402 flow) — the agent calls the payment link URL, receives a 402 response, signs a payment via FluxA Wallet, and submits it. See Payment Link (Agent Guide) for details.

Step 5 — Agent confirms payment to your service

After paying, the agent notifies your service that payment is complete.

bash

curl -X POST https://your-service.com/api/orders/order_1234/confirm

Step 6 — Your service verifies payment

Your backend verifies that the payment link has actually been paid by querying the FluxA API.

bash

curl https://walletapi.fluxapay.xyz/api/payment-links/pl_a1b2c3d4/payments \
  -H "Authorization: Bearer $YOUR_AGENT_JWT"

Check the response for a payment with status: "succeeded":

json

{
  "payments": [
    {
      "id": 1,
      "amount": "5000000",
      "currency": "USDC",
      "status": "succeeded",
      "txHash": "0x...",
      "createdAt": "2025-05-15T10:30:00.000Z"
    }
  ]
}

WARNING

Always verify payment server-side. Never trust the agent's claim that it has paid — always check the payment status via the FluxA API before fulfilling the order.

Step 7 — Fulfill the order

Once payment is verified, proceed with your business logic — deliver the product, activate the subscription, return the data, etc.

json

{
  "orderId": "order_1234",
  "status": "completed",
  "data": {
    "reportUrl": "https://your-service.com/reports/q1-ai-trends.pdf"
  }
}

Server-side example

Below is a simplified Node.js / Express implementation showing the complete flow.

const express = require('express')
const app = express()
app.use(express.json())

const FLUXA_API = 'https://walletapi.fluxapay.xyz'
const AGENT_JWT = process.env.AGENT_JWT

// In-memory order store (use a database in production)
const orders = new Map()

// Step 1 & 2 & 3: Create order + payment link
app.post('/api/orders', async (req, res) => {
  const { product, quantity } = req.body
  const amount = calculatePrice(product, quantity) // your pricing logic

  // Create a payment link via FluxA
  const plRes = await fetch(`${FLUXA_API}/api/payment-links`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${AGENT_JWT}`
    },
    body: JSON.stringify({
      amount: String(amount), // atomic units (6 decimals)
      currency: 'USDC',
      network: 'base',
      description: `Order — ${product} x${quantity}`,
      maxUses: 1,
      expiresAt: new Date(Date.now() + 3600_000).toISOString() // 1 hour
    })
  })
  const { paymentLink } = await plRes.json()

  const order = {
    orderId: `order_${Date.now()}`,
    product,
    quantity,
    amount,
    linkId: paymentLink.linkId,
    paymentUrl: paymentLink.url,
    status: 'pending_payment'
  }
  orders.set(order.orderId, order)

  res.json({
    orderId: order.orderId,
    status: order.status,
    total: `${(amount / 1_000_000).toFixed(2)} USDC`,
    paymentUrl: order.paymentUrl
  })
})

// Step 5 & 6 & 7: Confirm + verify + fulfill
app.post('/api/orders/:orderId/confirm', async (req, res) => {
  const order = orders.get(req.params.orderId)
  if (!order) return res.status(404).json({ error: 'Order not found' })
  if (order.status === 'completed') return res.json({ orderId: order.orderId, status: 'completed' })

  // Verify payment via FluxA API
  const pmtRes = await fetch(
    `${FLUXA_API}/api/payment-links/${order.linkId}/payments`,
    { headers: { 'Authorization': `Bearer ${AGENT_JWT}` } }
  )
  const { payments } = await pmtRes.json()
  const paid = payments.some(p => p.status === 'succeeded')

  if (!paid) {
    return res.status(402).json({
      error: 'Payment not completed',
      paymentUrl: order.paymentUrl
    })
  }

  order.status = 'completed'

  res.json({
    orderId: order.orderId,
    status: 'completed',
    data: { /* your fulfillment data */ }
  })
})

Agent-side prompt example

Below is an example prompt you can embed in your service's documentation or agent instructions, so that AI agents know how to interact with your Payment Link Checkout flow.

TIP

This example assumes the agent has the FluxA Agent Wallet skill installed. If not, the agent should install it first:

npx skills add -s fluxa-agent-wallet -y -g FluxA-Agent-Payment/FluxA-AI-Wallet-MCP

Or read the skill instructions at https://fluxapay.xyz/skill.md.

text

** Prerequisites **
You must install the FluxA Agent Wallet skill:
https://fluxapay.xyz/skill.md

** Payment instructions **
All prices are in USDC. Payments use FluxA Payment Links:
- When you create an order, you receive a `paymentUrl`
- Open the paymentUrl and pay with your FluxA Wallet
  (x402 protocol, zero gas fees)
- After payment, call the service's confirm endpoint to
  complete the order

** Your task **
Purchase a premium report from https://your-service.com.

** Step 1 — Place the order **
Call the service to create an order:

POST https://your-service.com/api/orders
Content-Type: application/json

{ "product": "premium-report", "quantity": 1 }

The response includes:
- orderId — your order reference
- paymentUrl — a FluxA Payment Link URL to pay

** Step 2 — Pay the payment link **
Open the paymentUrl. The FluxA skill handles the x402
payment flow automatically:
1. GET the paymentUrl → receives 402 with payment details
2. Sign payment using your mandate via FluxA Wallet
3. Retry with X-Payment header → payment completes

If you don't have a mandate yet, create one first using
the fluxa-agent-wallet skill (mandate-create), then pay.

** Step 3 — Confirm payment **
After payment succeeds, notify the service:

POST https://your-service.com/api/orders/<orderId>/confirm

If the payment is verified, the service returns the order
result with your purchased content. If not yet settled,
it returns 402 with the paymentUrl — wait briefly and
retry the confirm.

** Step 4 — Report **
Summarize the result to the user:
- Order ID and status
- Amount paid (USDC)
- Delivered content or next steps

Handling refunds

If your service needs to refund a payment (e.g. order cancellation, dispute), use the Refund API. Refunds use the x402 reverse payment flow — your service initiates a refund, pays the refund link via a mandate, and the funds settle back to the original payer onchain.

Refund flow

Your Service              FluxA API               Onchain
     |                        |                       |
     |-- POST initiate ------>|                       |
     |   (paymentId, amount)  |                       |
     |<-- refundUrl + plr_* --|                       |
     |                        |                       |
     |-- GET refundUrl ------>|                       |
     |<-- 402 (payTo=payer) --|                       |
     |                        |                       |
     |-- sign via mandate --->|                       |
     |-- GET + X-Payment ---->|-- settle to payer --->|
     |<-- 200 {txHash} -------|                       |

Server-side refund example

// Refund endpoint on your service
app.post('/api/orders/:orderId/refund', async (req, res) => {
  const order = orders.get(req.params.orderId)
  if (!order || order.status !== 'completed') {
    return res.status(400).json({ error: 'Order not refundable' })
  }

  // Step 1: Find the payment record
  const pmtRes = await fetch(
    `${FLUXA_API}/api/payment-links/${order.linkId}/payments`,
    { headers: { 'Authorization': `Bearer ${AGENT_JWT}` } }
  )
  const { payments } = await pmtRes.json()
  const payment = payments.find(p => p.settlementStatus === 'settled')
  if (!payment) return res.status(400).json({ error: 'No settled payment found' })

  // Step 2: Initiate refund
  const refundRes = await fetch(`${FLUXA_API}/api/payment-links/refunds/initiate`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${AGENT_JWT}`
    },
    body: JSON.stringify({
      paymentId: payment.id,
      reason: req.body.reason || 'Order cancelled'
    })
  })
  const refund = await refundRes.json()

  // Step 3: Pay the refund link via x402 (using your mandate)
  // ... same x402 flow as paying a payment link ...

  order.status = 'refunded'
  res.json({ orderId: order.orderId, status: 'refunded', refundId: refund.refundId })
})

TIP

Partial refunds are supported — pass an amount field to initiate to refund less than the full payment. The system prevents over-refunding by tracking cumulative refunds per payment.

Method	Endpoint	Description
`POST`	`/api/payment-links`	Create a payment link
`GET`	`/api/payment-links/:linkId`	Get link details and status
`GET`	`/api/payment-links/:linkId/payments`	Verify payments received
`PATCH`	`/api/payment-links/:linkId`	Update link (extend expiry, etc.)
`DELETE`	`/api/payment-links/:linkId`	Cancel a link
`GET`	`/api/received-payments`	List all received payments
`POST`	`/api/payment-links/refunds/initiate`	Initiate a refund
`GET`	`/api/payment-links/refunds`	List refunds
`POST`	`/api/payment-links/refunds/:id/cancel`	Cancel a pending refund

Best practices

Always verify server-side — never trust the agent's claim of payment. Always call GET /api/payment-links/:linkId/payments and check for status: "succeeded" before fulfilling.
Set maxUses: 1 for one-time orders to prevent double payments.
Set expiresAt to auto-expire unpaid orders and keep your payment links clean.
Use description to include the order ID or context — this helps with reconciliation and makes the payment page informative.
Idempotent confirmation — your /confirm endpoint should be safe to call multiple times. If the order is already fulfilled, return the existing result.
Handle expiry — if the payment link expires before the agent pays, return an error with instructions to create a new order.
A2A payments — when designing for agent-to-agent scenarios, make sure your confirm endpoint doesn't assume the payer is the same agent that placed the order.

Next steps

Payment Link (Agent Guide) — how agents create and manage payment links
Payment Links API — full API reference
Monetize Gateway — zero-code alternative for fixed-price APIs

Payment Link Checkout ​

What it is ​

How it works ​

Agent-to-agent (A2A) flow ​

Step-by-step integration ​

Step 1 — Agent places an order ​

Step 2 — Your service creates a payment link ​

Step 3 — Return order data with payment link ​

Step 4 — Agent pays the payment link ​

Step 5 — Agent confirms payment to your service ​

Step 6 — Your service verifies payment ​

Step 7 — Fulfill the order ​

Server-side example ​

Agent-side prompt example ​

Handling refunds ​

Refund flow ​

Server-side refund example ​

Related APIs ​

Best practices ​

Next steps ​

Payment Link Checkout

What it is

How it works

Agent-to-agent (A2A) flow

Step-by-step integration

Step 1 — Agent places an order

Step 2 — Your service creates a payment link

Step 3 — Return order data with payment link

Step 4 — Agent pays the payment link

Step 5 — Agent confirms payment to your service

Step 6 — Your service verifies payment

Step 7 — Fulfill the order

Server-side example

Agent-side prompt example

Handling refunds

Refund flow

Server-side refund example

Related APIs

Best practices

Next steps