Skip to main content
POST
Create a payment link
You do not pass a settlement mode. The server sets it from your account (card and bank by default) and returns it on the response.

Authorizations

x-api-key
string
header
required

Your secret key, from app.agentaos.ai -> Settings -> Developers -> API Keys. The key's prefix is both its identity and its environment: sk_test_... (sandbox, free, no verification) or sk_live_... (real money, requires business verification). A missing or invalid key returns 401.

Body

application/json
amount
number
required

Amount in currency units, e.g. 49.99.

Required range: 0.01 <= x <= 1000000
currency
enum<string>

Defaults to your org's settlement currency. A fiat code is mapped to your org's default settlement token internally; the link stores the resolved token.

Available options:
EUR,
USD,
EURC,
EURe,
USDC
description
string
Maximum string length: 1000
name
string

Product name, for the catalog-style link surfaces. Separate from description.

Maximum string length: 120
imageUrl
string<uri>

HTTPS only.

Maximum string length: 2048
type
enum<string>
default:one_time

A subscription link requires billingInterval and settles on the card/bank rail (Merchant of Record); it can't be a crypto-settlement link.

Available options:
one_time,
subscription
billingInterval
enum<string>

Required when type is subscription, must be omitted for one_time.

Available options:
month,
year
maxUses
integer

1 for single-use, N for a limited quantity, omitted for unlimited.

Required range: 1 <= x <= 100000
taxRateId
string<uuid>

Must belong to your organization.

checkoutFields
object[]
webhookUrl
string<uri>
Maximum string length: 2048
successUrl
string<uri>
Maximum string length: 2048
cancelUrl
string<uri>
Maximum string length: 2048
expiresAt
string<date-time>
metadata
object

Arbitrary key-value data, returned unchanged on webhooks. Up to 8KB serialized.

supportedNetworks
string[]

CAIP-2 network IDs (e.g. eip155:8453), for crypto-settlement links. Ignored (and taken from your key's configuration instead) if your API key is scoped to specific networks.

Response

Payment link created.

id
string<uuid>
required

Payment link UUID.

org_id
string<uuid>
required
user_id
string<uuid>
required

Public ID used in the checkout URL.

amount
number
required

Currency units.

currency
string
required

Settlement currency or token.

description
string | null
required
metadata
object
required

Your custom data.

checkout_fields
object[]
required
webhook_url
string | null
required
success_url
string | null
required
cancel_url
string | null
required
tax_rate_id
string<uuid> | null
required
status
enum<string>
required
Available options:
active,
cancelled
payment_count
integer
required

Successful payments against this link so far.

supported_networks
string[]
required
expires_at
string<date-time> | null
required
created_at
string<date-time>
required
updated_at
string<date-time>
required
name
string | null
required
image_url
string | null
required
max_uses
integer | null
required

null means unlimited.

seller_mode
enum<string>
required

mor (card + bank) or crypto (on-chain). The snake_case column equivalent of the computed sellerMode.

Available options:
mor,
crypto
type
enum<string>
required
Available options:
one_time,
subscription
billing_interval
enum<string> | null
required
Available options:
month,
year,
null
environment
enum<string>
required
Available options:
test,
live
checkoutUrl
string
required

Full URL to share with buyers. Computed, camelCase, no snake_case equivalent.

sellerMode
enum<string>
required
Available options:
mor,
crypto