Payment Links

A payment link is a reusable product. Create one and share the URL anywhere: email, a landing page, a chat message. Every visitor who opens it gets their own checkout. One link can be paid many times.

Payment link vs. checkout: a payment link is a template you create once and share. A checkout is a single payment attempt, either created standalone or from a link. Opening a payment link’s URL creates a new checkout behind the scenes.

Without code

Do not want to touch the API? Create a product in the dashboard and share its link.

AgentaOS product builder with a name, price, and the generated shareable payment link — The product builder. Name it, price it, and your shareable payment link is generated as you type.

Create a product

Open the Products page and add a name, description, price, and an optional image.

Share the link

Click Share to copy the product’s payment link. Send it by email, social, or a QR code. Every visit starts a fresh checkout.

Prefer code? Create links programmatically below.

Create a payment link

SDK
cURL

import { AgentaOS } from '@agentaos/pay';

const agentaos = new AgentaOS(process.env.AGENTAOS_API_KEY!);

const link = await agentaos.paymentLinks.create({
  amount: 49.99,
  currency: 'EUR',
  description: 'Pro plan',
  successUrl: 'https://myshop.com/success',
  cancelUrl: 'https://myshop.com/cancel',
  webhookUrl: 'https://myshop.com/webhooks',
});

console.log(link.checkoutUrl);
// → https://app.agentaos.ai/pay/7rr6S9ml4BMp829wV5WeAA

curl -X POST https://api.agentaos.ai/api/v1/gateway/payment-links \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.99,
    "currency": "EUR",
    "description": "Pro plan",
    "successUrl": "https://myshop.com/success",
    "cancelUrl": "https://myshop.com/cancel",
    "webhookUrl": "https://myshop.com/webhooks"
  }'

There’s no CLI command to create a payment link yet. Create one from the SDK, the REST API, or the dashboard. The CLI’s agenta pay checkout creates a one-off checkout, not a reusable link.

amount is in currency units, not cents. 49.99 means €49.99. See the money model if you’re wiring this up against real numbers.

One-time vs. subscription

A payment link is type: 'one_time' by default: every payment is independent, and the link can be reused indefinitely. Set type: 'subscription' to turn it into a recurring plan. Subscription links require a billingInterval and a verified account that accepts card and bank; they can’t run in on-chain-only mode.

const plan = await agentaos.paymentLinks.create({
  amount: 29.99,
  currency: 'EUR',
  description: 'Pro plan, monthly',
  type: 'subscription',
  billingInterval: 'month', // 'month' | 'year', required for subscriptions
});

Creating a subscription link does not create a subscription. A subscription is created only when a buyer pays it at the hosted checkout. See Subscriptions for how the buyer-pays-in flow works and how to manage the result.

The checkout URL

Every payment link returns a checkoutUrl in the shape https://app.agentaos.ai/pay/{id}. Share it as-is: a button, an email, a QR code. Each visit starts a fresh checkout scoped to that link’s amount, currency, and configuration.

Custom checkout fields

Collect extra information from the buyer before they pay by passing checkoutFields. Each field renders on the hosted checkout page and is required or optional per field.

const link = await agentaos.paymentLinks.create({
  amount: 15.00,
  currency: 'EUR',
  description: 'Event ticket',
  checkoutFields: [
    { key: 'attendeeName', label: 'Attendee name', type: 'text', required: true },
    { key: 'company', label: 'Company', type: 'text', required: false },
    { key: 'ticketTier', label: 'Ticket tier', type: 'select', required: true, options: ['Standard', 'VIP'] },
  ],
});

Retrieve a payment link

SDK
cURL

const link = await agentaos.paymentLinks.retrieve('link-uuid');

curl https://api.agentaos.ai/api/v1/gateway/payment-links/link-uuid \
  -H "x-api-key: sk_live_..."

List payment links

Paginated: every list call returns { items, total, hasMore }.

SDK
cURL

const page = await agentaos.paymentLinks.list({ limit: 20, offset: 0 });
console.log(page.total, page.hasMore);

curl "https://api.agentaos.ai/api/v1/gateway/payment-links?limit=20&offset=0" \
  -H "x-api-key: sk_live_..."

Cancel a payment link

Cancelling stops new checkouts from being created against the link. It does not affect checkouts already in progress or subscriptions already running from it.

SDK
cURL

await agentaos.paymentLinks.cancel('link-uuid');

curl -X DELETE https://api.agentaos.ai/api/v1/gateway/payment-links/link-uuid \
  -H "x-api-key: sk_live_..."

Parameters

number

required

Amount in currency units (e.g. 49.99 = €49.99).

string

default:"org default"

EUR or USD.

string

Shown on the checkout page. Max 1000 characters.

string

default:"one_time"

one_time or subscription.

string

month or year. Required when type is subscription, omit otherwise.

string

Redirect the buyer here after payment. HTTPS only.

string

“Cancel” link on the checkout page. HTTPS only.

string

Server notification URL for payment events. HTTPS only.

string

UUID of a pre-created tax rate.

array

Custom fields to collect from the buyer at checkout. Each item has key, label, type (text | email | tel | select), required, and optionally placeholder or options (for select).

string

ISO 8601. The link stops accepting new checkouts after this time.

object

Custom key-value data, returned unchanged on every checkout created from this link. Max 8KB.

Response

string

Link UUID.

string

Shareable payment URL.

number

Amount in currency units.

string

Settlement currency.

string

active or cancelled.

string

mor (card + bank) or crypto (on-chain). Derived, never set by you.

string

one_time or subscription.

string | null

month or year for subscription links; null for one-time.

number

Times this link has been paid.

array

Custom fields configured on this link.

string | null

ISO 8601.

string

ISO 8601.

Next steps

Checkouts

A single payment attempt, standalone or created from a link.

Subscriptions

How a type: 'subscription' link turns into a running subscription.

Webhooks

Get notified the moment someone pays your link.

How Merchant of Record works

Why we can handle card, bank, and tax as your seller of record.

Getting Started

Build with AI agents

Sell

Merchant of Record

Webhooks

For customers

Legacy

Without code

Create a payment link

One-time vs. subscription

The checkout URL

Custom checkout fields

Retrieve a payment link

List payment links

Cancel a payment link

Parameters

Response

Next steps

Checkouts

Subscriptions

Webhooks

How Merchant of Record works

​Without code

​Create a payment link

​One-time vs. subscription

​The checkout URL

​Custom checkout fields

​Retrieve a payment link

​List payment links

​Cancel a payment link

​Parameters

​Response

​Next steps

Checkouts

Subscriptions

Webhooks

How Merchant of Record works

Without code

Create a payment link

One-time vs. subscription

The checkout URL

Custom checkout fields

Retrieve a payment link

List payment links

Cancel a payment link

Parameters

Response

Next steps