Payment Links

Create a payment link

Creates a reusable, shareable payment link.

post/gateway/payment-links

Request

  • Base URL: https://api.agentaos.ai/api/v1
  • URL: https://api.agentaos.ai/api/v1/gateway/payment-links
  • Auth: API key in header x-api-key

Request body

amountnumber required

Amount in currency units, e.g. 49.99.

currency'EUR' | 'USD' | 'EURC' | 'EURe' | 'USDC'

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.

descriptionstring
namestring

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

imageUrlstring uri

HTTPS only.

type'one_time' | 'subscription'

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

billingInterval'month' | 'year'

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

trialPeriodDaysinteger

Free-trial length in days. Subscription links only. The buyer's card is saved with nothing due today; the first charge happens when the trial ends.

maxUsesinteger

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

taxRateIdstring uuid

Must belong to your organization.

webhookUrlstring uri
successUrlstring uri
cancelUrlstring uri
expiresAtstring date-time
metadataobject

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

supportedNetworksstring[]

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.

idstring uuid required

Payment link UUID.

org_idstring uuid required
user_idstring uuid required
secure_link_idstring required

Public ID used in the checkout URL.

amountnumber required

Currency units.

currencystring required

Settlement currency or token.

descriptionstring nullable required
metadataobject required

Your custom data.

webhook_urlstring nullable required
success_urlstring nullable required
cancel_urlstring nullable required
tax_rate_idstring uuid nullable required
status'active' | 'cancelled' required
payment_countinteger required

Successful payments against this link so far.

supported_networksstring[] required
expires_atstring date-time nullable required
created_atstring date-time required
updated_atstring date-time required
namestring nullable required
image_urlstring nullable required
max_usesinteger nullable required

null means unlimited.

seller_mode'mor' | 'crypto' required

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

type'one_time' | 'subscription' required
billing_interval'month' | 'year' | 'null' nullable required
environment'test' | 'live' required
checkoutUrlstring required

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

sellerMode'mor' | 'crypto' required

Changes

No recorded changes to this operation across all 1 revision of this API.