Skip to main content
POST
/
v1
/
payment-links
Create payment link
curl --request POST \
  --url https://api.meum.io/v1/payment-links \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "Summer fundraiser",
  "amount_mode": "fixed_amount",
  "amount": "25.00",
  "allow_multiple_payments": true,
  "public_visible": true
}
'
{
  "id": "<string>",
  "public_id": "<string>",
  "public_url": "https://pay.meum.io/plpub_c9a9bb730611077574c828af5af5fed1",
  "title": "Summer fundraiser",
  "description": "<string>",
  "image_url": "<string>",
  "amount": "25.00",
  "currency": "USD",
  "min_amount": "<string>",
  "max_amount": "<string>",
  "suggested_amounts": [
    10,
    25,
    50
  ],
  "allow_multiple_payments": true,
  "public_visible": true,
  "expires_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "stats": {
    "total_payments": "12",
    "paid_payments": "10",
    "total_volume": "250.00"
  }
}

Authorizations

​
Authorization
string
header
required

Store-scoped API key. Prefix with sk_live_. Example: Authorization: Bearer sk_live_EXAMPLE_DO_NOT_USE

Headers

​
Idempotency-Key
string

Optional. Unique key (1–128 characters) so retrying the same request does not create duplicates. If you send the same key again, you get the original response. Omit if you do not need retry safety.

Required string length: 1 - 128
Example:

"pl_create_demo_001"

Body

application/json
​
title
string
required

Required. Name shown on the checkout page and in your dashboard (1–200 characters). Example: "Summer fundraiser".

Required string length: 1 - 200
​
amount_mode
enum<string>
required

How pricing works on this Pay Link:

  • fixed_amount: you set the price; the customer pays exactly that amount
  • customer_defined_amount: the customer chooses how much to pay (within min/max you set)
Available options:
fixed_amount,
customer_defined_amount
​
description
string

Optional. Longer text for payers (max 2000 characters). Omit if not needed.

Maximum string length: 2000
​
image_url
string | null

Optional. HTTPS image URL for checkout (logo or product photo). Omit for no image.

Maximum string length: 2048
​
amount
string | null

Required when amount_mode is fixed_amount. Price as a decimal string (e.g. "25.00"). Omit when customers choose their own amount.

Example:

"25.00"

​
min_amount
string | null

Optional. Lowest amount a customer can pay when amount_mode is customer_defined_amount. Omit to allow any positive amount (subject to platform limits).

​
max_amount
string | null

Optional. Highest amount a customer can pay when amount_mode is customer_defined_amount. Omit for no upper cap (subject to platform limits).

​
suggested_amounts
(number | null)[]

Optional. Quick-pick buttons on checkout (e.g. [10, 25, 50]). Omit for a free-form amount field only.

​
allow_multiple_payments
boolean
default:true

Optional. true (default): many customers can pay through this link. false: treat as one-time use after the first successful payment.

​
public_visible
boolean
default:true

Optional. true (default): anyone with the link URL can pay. false: hide from public checkout (API-only use).

​
expires_at
string<date-time> | null

Optional. When the link stops accepting payments (UTC, e.g. 2025-09-01T14:31:44.171Z). Omit for no expiration.

​
success_url
string<uri>

Optional. Where to send the customer after a successful payment. Only works if redirect URLs are enabled for Pay Links on your account.

​
metadata
object

Optional. Custom key-value data stored on the link and copied to invoices from it. Omit if not needed.

Response

Payment link created

Merchant-facing Pay Link resource with configuration and stats.

​
id
string

Merchant resource ID (plink_...). Use in API paths and webhooks.

Pattern: ^(inv_|txn_|plink_|wh_|whd_|evt_|int_)[0-9a-z]{20,32}$
​
public_id
string

Buyer-facing token (plpub_...) embedded in public checkout URLs.

Pattern: ^plpub_[0-9a-z]{20,32}$
​
public_url
string<uri>

Shareable checkout page URL for this link.

Example:

"https://pay.meum.io/plpub_c9a9bb730611077574c828af5af5fed1"

​
title
string

Link title shown on checkout and in the merchant dashboard.

Example:

"Summer fundraiser"

​
description
string | null

Optional description for payers.

​
image_url
string<uri> | null

Optional image URL displayed on the checkout page.

​
amount_mode
enum<string>

How pricing works on this Pay Link:

  • fixed_amount: you set the price; the customer pays exactly that amount
  • customer_defined_amount: the customer chooses how much to pay (within min/max you set)
Available options:
fixed_amount,
customer_defined_amount
​
amount
string | null

Fixed price when amount_mode is fixed_amount.

Example:

"25.00"

​
currency
string

Currency for all amounts on this link.

Example:

"USD"

​
min_amount
string | null

Minimum payer-entered amount for variable-amount links.

​
max_amount
string | null

Maximum payer-entered amount for variable-amount links.

​
suggested_amounts
number[]

Suggested preset amounts shown as quick-select buttons on checkout.

Example:
[10, 25, 50]
​
allow_multiple_payments
boolean

When true, the link can generate multiple paid invoices over its lifetime.

​
public_visible
boolean

When true, the link is reachable via its public URL without extra auth.

​
status
enum<string>

Whether the Pay Link can accept payments right now:

  • active: open for payments
  • inactive: turned off by you; no new payments
  • expired: past its expiration date
  • completed: single-use link already paid, or usage limit reached
Available options:
active,
inactive,
expired,
completed
​
effective_status
enum<string>

Computed status accounting for expiry and usage limits.

Available options:
active,
inactive,
expired,
completed
​
expires_at
string<date-time> | null

After this time (UTC) the link no longer accepts payments. null if it never expires.

​
created_at
string<date-time>

When the link was created.

​
updated_at
string<date-time>

When the link was last modified.

​
stats
object

Aggregated payment metrics for a Pay Link.