Checkout, payment links, and sessions

ArcenPay gives you four checkout paths depending on whether your customer is a human user in a browser or an autonomous AI agent.

Checkout paths

Path	How it works	When to use
Hosted payment link	A unique URL at `/pay/[slug]` that human customers visit. No frontend code required.	One-time payments, add-on purchases, invoice collection.
ArcenEmbed checkout	`ArcenEmbed` renders an in-app checkout flow with plan selection and wallet connection.	Full recurring subscription checkout inside your React app.
Public checkout session	Created server-side and resolved client-side via `GET /api/v1/public/checkout/:sessionId`.	Programmatic checkout with server-controlled pricing/parameters.
Agentic payment link (`/spec`)	Dual-mode payment endpoint providing structured JSON spec at `GET /pay/[slug]/spec`.	Autonomous AI agents, MCP tool callers, and non-interactive workflows.

Payment links & Agentic `/spec`

Payment links are created in the dashboard under Catalog → Payment Links or programmatically via the Node.js SDK, the REST API, or the Agent SDK. Each link has:

Field	Description
`kind`	`ADDON` (for add-on purchases), `INVOICE` (for invoice payment), or `CUSTOM` (one-time fixed amount).
`name`	Display name shown on the payment page and in agent specs.
`amount`	Fixed amount for `CUSTOM` links (in token units, e.g. `25.00` USDC).
`acceptedToken`	Token address the link accepts (for example, USDC on Base, Stellar, Solana, or Arc, or USDT on BOT Chain).
`recipientWallet`	Wallet address that receives the payment.
`successUrl` / `cancelUrl`	Where to redirect human users after payment completes.
`companyId`	Optional — ties the payment to a specific customer company.
`expiresAt`	Optional expiry timestamp.

Dual-mode resolution: Human UI vs Agent Spec

Every ArcenPay payment link (/pay/[slug]) operates in dual-mode:

Human Browsers: Visiting /pay/[slug] in a browser renders an interactive checkout interface that connects wallets (RainbowKit / WalletConnect) and approves tokens.
AI Agents & MCP Tools: Querying GET /pay/[slug]/spec returns the machine-readable payment parameters:

curl -s https://app.arcenpay.com/pay/my-setup-fee/spec

{
  "type": "agentic_payment_link",
  "version": "1.0",
  "id": "pl_123456789",
  "slug": "my-setup-fee",
  "name": "Acme Setup Fee",
  "description": null,
  "status": "ACTIVE",
  "isAgentic": true,
  "amount": "25.000000",
  "amountAtomic": "25000000",
  "currency": "USDC",
  "acceptedToken": "0x3600000000000000000000000000000000000000",
  "chainId": 5042002,
  "chainFamily": "evm",
  "recipientWallet": "0xMerchantWallet...",
  "sessionUrl": "https://api.arcenpay.com/api/v1/public/payment-links/my-setup-fee/session",
  "confirmUrl": "https://api.arcenpay.com/api/v1/public/payment-links/my-setup-fee/confirm"
}

Autonomous payment execution via Agent SDK

AI agents resolve and pay links directly using ArcenAgent:

import { ArcenAgent } from "@arcenpay/agent";

const agent = new ArcenAgent({
  privateKey: process.env.AGENT_PRIVATE_KEY!,
  rpcUrl: "https://rpc.botchain.ai",
  chainId: 677,
});

// Resolves /spec, validates policy against ArcenAuth mandates, and executes on-chain payment
const receipt = await agent.payPaymentLink("my-setup-fee");
console.log("Confirmed payment tx:", receipt.txHash);

Creating payment links with the Node SDK

Create and manage payment links server-side with @arcenpay/node — the browser SDK has no creation API because it can’t hold API keys. createPaymentLink() returns the hosted checkoutUrl you hand to human customers in your React app:

// server-side (API route / route handler) — @arcenpay/node
import { ArcenClient } from "@arcenpay/node";

const client = new ArcenClient({ apiKey: process.env.ARCENPAY_API_KEY! });

const { paymentLink } = await client.createPaymentLink({
  kind: "CUSTOM",
  name: "Setup fee",
  amount: 25,
  chainId: 5042002,
  acceptedToken: "USDC", // symbol or token address
  recipientWallet: "0x7b2aF4D3e1c6E9f0A5b8dC1e2F3A4B5C6D7E8F90",
  isAgentic: true,       // enables the machine-readable /spec endpoint
});

// paymentLink.checkoutUrl → https://app.arcenpay.com/pay/… (share with humans)
// paymentLink.agenticSpecUrl → https://app.arcenpay.com/api/v1/public/payment-links/…/spec

// client (React) — redirect humans to the hosted checkout returned by the backend
window.location.href = checkoutUrl;

Manage links via listPaymentLinks(), getPaymentLink(), and updatePaymentLink() (deactivate/archive). Autonomous AI merchants can create links directly with @arcenpay/agent → agent.createPaymentLink().

Checkout sessions

Checkout sessions represent a single purchase flow. Create a session server-side and pass the session ID to your frontend or render it in ArcenEmbed.

POST /api/v1/checkout-sessions
Authorization: Bearer sk_live_xxxxxxxx

{
  "paymentLinkId": "pl_abc123",
  "companyId": "cm_abc123",
  "successUrl": "https://myapp.com/billing/success"
}

Resolve a session’s current state:

GET /api/v1/checkout-sessions/:id

The public checkout endpoint lets customers resolve sessions without authentication:

GET /api/v1/public/checkout/:sessionId
PATCH /api/v1/public/checkout/:sessionId
POST /api/v1/public/checkout/:sessionId/confirm

Session purposes

Checkout sessions track their purpose via the purpose field, which mirrors the kind of payment link that created the session:

Purpose	Description
`CUSTOM`	A fixed-amount charge from a `CUSTOM` payment link.
`ADDON`	An add-on purchase from an `ADDON` payment link.
`INVOICE`	Payment of an existing invoice from an `INVOICE` payment link.

Session status lifecycle

A checkout session moves through these states:

Status	Meaning
`PENDING`	Session created, awaiting payment.
`PAID`	Payment confirmed and applied on-chain.
`EXPIRED`	Session expired without completion.
`CANCELLED`	Session cancelled before payment.
`FAILED`	Payment or on-chain verification failed.

Next steps

Payment links guide — step-by-step guide to creating and using payment links
Embedded components — use ArcenEmbed for in-app checkout
Subscriptions — understand what happens after a checkout succeeds

Get started

Core concepts

Guides

Integrations

Checkout, payment links, and sessions

Checkout paths

Payment links & Agentic `/spec`

Dual-mode resolution: Human UI vs Agent Spec

Autonomous payment execution via Agent SDK

Creating payment links with the Node SDK

Checkout sessions

Session purposes

Session status lifecycle

Next steps

​Checkout paths

​Payment links & Agentic /spec

​Dual-mode resolution: Human UI vs Agent Spec

​Autonomous payment execution via Agent SDK

​Creating payment links with the Node SDK

​Checkout sessions

​Session purposes

​Session status lifecycle

​Next steps

Checkout paths

Payment links & Agentic `/spec`

Dual-mode resolution: Human UI vs Agent Spec

Autonomous payment execution via Agent SDK

Creating payment links with the Node SDK

Checkout sessions

Session purposes

Session status lifecycle

Next steps