---
title: "Create a payment link"
method: POST
path: "/gateway/payment-links"
tags: ["Payment Links"]
---

# Create a 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`

Creates a reusable, shareable payment link.

## Request body

- PaymentLinkCreateRequest
  - `amount` number, 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.
  - `description` string
  - `name` string: Product name, for the catalog-style link surfaces. Separate from `description`.
  - `imageUrl` string, 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`.
  - `trialPeriodDays` integer: 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.
  - `maxUses` integer: 1 for single-use, N for a limited quantity, omitted for unlimited.
  - `taxRateId` string, uuid: Must belong to your organization.
  - `checkoutFields` CheckoutField[]
    - `key` string, required
    - `label` string, required
    - `type` 'text' | 'email' | 'tel' | 'select', required
    - `required` boolean, required
    - `placeholder` string
    - `options` string[]: For `type: select` only.
  - `webhookUrl` string, uri
  - `successUrl` string, uri
  - `cancelUrl` string, uri
  - `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 `201`

Payment link created.

- PaymentLink
  - `id` string, uuid, required: Payment link UUID.
  - `org_id` string, uuid, required
  - `user_id` string, uuid, required
  - `secure_link_id` string, required: Public ID used in the checkout URL.
  - `amount` number, required: Currency units.
  - `currency` string, required: Settlement currency or token.
  - `description` string, nullable, required
  - `metadata` object, required: Your custom data.
  - `checkout_fields` CheckoutField[], required
    - `key` string, required
    - `label` string, required
    - `type` 'text' | 'email' | 'tel' | 'select', required
    - `required` boolean, required
    - `placeholder` string
    - `options` string[]: For `type: select` only.
  - `webhook_url` string, nullable, required
  - `success_url` string, nullable, required
  - `cancel_url` string, nullable, required
  - `tax_rate_id` string, uuid, nullable, required
  - `status` 'active' | 'cancelled', required
  - `payment_count` integer, required: Successful payments against this link so far.
  - `supported_networks` string[], required
  - `expires_at` string, date-time, nullable, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `name` string, nullable, required
  - `image_url` string, nullable, required
  - `max_uses` integer, 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
  - `checkoutUrl` string, required: Full URL to share with buyers. Computed, camelCase, no snake_case equivalent.
  - `sellerMode` 'mor' | 'crypto', required

## Other responses

- `400`: A required field is missing, out of range, or the wrong type. `ValidationPipe` also rejects any field not in the documented schema.
- `401`: Missing or invalid `x-api-key`.
- `403`: The key is valid but the resource belongs to a different organization.

---

[API](https://skmtc.dev/agentaos/apis/agentaos-gateway-api.md) · [All operations](https://skmtc.dev/agentaos/apis/agentaos-gateway-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentaos/apis/agentaos-gateway-api/revisions/3a8ad3c6b965?raw)