Skip to main content
POST
Create a merchant-scoped payment link

Authorizations

x-api-key
string
header
required

Headers

Idempotency-Key
string
required

1–255 printable ASCII characters without spaces. Reuse for retries; replay responses carry Idempotency-Replayed: true.

Example:

"0b6f2c1e-4c7a-4a43-9a51-6a4b1d7e9f10"

Body

application/json
amount
string
required

Positive decimal string in major units, within the currency exponent.

Pattern: ^(0|[1-9]\d{0,19})(\.\d{1,18})?$
Example:

"12.34"

currency
string
required
Example:

"EUR"

description
string
Maximum string length: 500
Example:

"Order payment"

expiresAt
string<date-time>

ISO-8601 timestamp with explicit Z or ±hh:mm offset.

failureUrl
string
Maximum string length: 2048
Example:

"https://shop.example.com/failure"

maxUses
number

Defaults to 1 for a single-use link; unlimited when reusable and omitted.

Required range: 1 <= x <= 1000000
metadata
object

JSON object, at most 16 KiB.

reusable
boolean
default:false
successUrl
string
Maximum string length: 2048
Example:

"https://shop.example.com/success"

Response

Link created, or the stored answer for a replayed Idempotency-Key

amount
string
required
Pattern: ^(0|[1-9]\d{0,19})(\.\d{1,18})?$
Example:

"12.34"

createdAt
string<date-time>
required
currency
string
required
Example:

"EUR"

description
string | null
required
expired
boolean
required
expiresAt
string<date-time> | null
required
failureUrl
string | null
required
id
string
required
Example:

"pl_01j9a6d6dqevssvyw7s97pkrga"

isActive
boolean
required
livemode
boolean
required

The live/test mode inherited from the authenticated API key.

Example:

true

maxUses
number | null
required
merchantId
string
required
metadata
object
required
reusable
boolean
required
slug
string
required
Pattern: ^[A-Za-z0-9]{24}$
status
enum<string>
required
Available options:
ACTIVE,
INACTIVE,
EXPIRED,
EXHAUSTED
successUrl
string | null
required
url
string | null
required

Null when hosted checkout is disabled.

Example:

"https://pay.example.com/l/aBcDeFgHiJkLmNoPqRsTuVwX"

usesCount
number
required