Payment Links

Read the payment links created in the dashboard.

Read-only access to the payment links created in the dashboard. The url field is the exact public checkout URL (the merchant’s custom domain when one is active, paysio.com otherwise), and items carries product names and images — enough for an ads or email integration to advertise a link without guessing. Payment links are mode-aware: a test key sees test links, a live key sees live links. Scoped keys need payment_links:read. Creating and editing links stays a dashboard (or CLI) action — there is no write endpoint yet.

List payment links

List payment links, newest first. Filtered to the key's mode (test keys see test links).

GEThttps://paysio.com/api/v1/payment-links

Authorizations

Authorizationstringheaderrequired

Any API key. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Query parameters

limitinteger

1-100, default 10

starting_afterstring

Cursor for pagination

statusstring

Filter by status, e.g. "active"

Example request — cURL

curl -X GET https://paysio.com/api/v1/payment-links \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/payment-links", {
  method: "GET",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "data": [
    {
      "object": "payment_link",
      "id": "1c9f4b1e-7a3d-4e88-b2c1-5f6a7d8e9b0c",
      "name": "Pro Plan",
      "slug": "pro-plan",
      "url": "https://shop.example.com/pay/pro-plan",
      "status": "active",
      "mode": "live",
      "collect_shipping_address": false,
      "payment_methods": null,
      "success_url": null,
      "metadata": {},
      "items": [
        { "product_id": "uuid", "name": "Pro Plan", "quantity": 1, "images": ["https://cdn.paysio.com/products/pro.png"] }
      ],
      "created": 1735689600
    }
  ],
  "has_more": false
}

Example response (400)

{
  "error": "Invalid request parameters",
  "type": "invalid_request_error",
  "code": "parameter_invalid"
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Create a payment link

Create a link for products that already exist in the catalogue. There are no ad-hoc prices on purpose: a link is a shop window onto the catalogue, so create the product first and reference it here. The link inherits the CALLER'S mode, so a test-mode app token can only ever produce a sandbox link. Requires the payment_links:write scope.

POSThttps://paysio.com/api/v1/payment-links

Authorizations

Authorizationstringheaderrequired

Secret key (sk_*) or app access token. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Body

namestringrequired

Internal name for the link

itemsarrayrequired

Line items: [{ product_id, quantity?, adjustable_quantity? }]. 1-50 items, each product must belong to this workspace.

slugstring

Preferred URL slug. Sanitised, and a numeric suffix is added if taken. Defaults to the name.

collect_shipping_addressboolean

Ask the buyer for a shipping address

success_urlstring

Where to send the buyer after payment

payment_methodsarray

Restrict to specific methods. Omit to use the workspace default.

metadataobject

Arbitrary key-value data stored on the link

Example request — cURL

curl -X POST https://paysio.com/api/v1/payment-links \
  -H "Authorization: Bearer sk_test_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "...",
  "items": []
}'

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/payment-links", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "name": "...",
    "items": []
  }),
})
const data = await res.json()

Example response (200)

{
  "object": "payment_link",
  "id": "c1f0a3d2-6b21-4a77-9f3e-2b8d5c7a1e04",
  "name": "Summer sale",
  "slug": "summer-sale",
  "url": "https://shop.acme.com/pay/summer-sale",
  "status": "active",
  "mode": "test",
  "collect_shipping_address": false,
  "payment_methods": null,
  "success_url": null,
  "metadata": {},
  "items": [
    {
      "product_id": "9b1c8e77-4f2a-4c31-9e77-1d0a5b3c2f88",
      "name": "Creatine 300g",
      "quantity": 1,
      "images": ["https://cdn.paysio.com/products/creatine.png"]
    }
  ],
  "created": 1790000000
}

Example response (400)

{
  "error": "Invalid request parameters",
  "type": "invalid_request_error",
  "code": "parameter_invalid"
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}

Retrieve a payment link

Retrieve a single payment link. The object is returned at the top level (no data wrapper). Check mode ('live' or 'test') before driving paid traffic at a link.

GEThttps://paysio.com/api/v1/payment-links/:id

Authorizations

Authorizationstringheaderrequired

Any API key. Prepend your key with Bearer, e.g. Bearer sk_test_your_secret_key.

Example request — cURL

curl -X GET https://paysio.com/api/v1/payment-links/:id \
  -H "Authorization: Bearer sk_test_your_secret_key"

Example request — JavaScript

const res = await fetch("https://paysio.com/api/v1/payment-links/:id", {
  method: "GET",
  headers: {
    "Authorization": "Bearer sk_test_your_secret_key"
  },
})
const data = await res.json()

Example response (200)

{
  "object": "payment_link",
  "id": "1c9f4b1e-7a3d-4e88-b2c1-5f6a7d8e9b0c",
  "name": "Pro Plan",
  "slug": "pro-plan",
  "url": "https://shop.example.com/pay/pro-plan",
  "status": "active",
  "mode": "live",
  "collect_shipping_address": false,
  "payment_methods": null,
  "success_url": null,
  "metadata": {},
  "items": [
    { "product_id": "uuid", "name": "Pro Plan", "quantity": 1, "images": ["https://cdn.paysio.com/products/pro.png"] }
  ],
  "created": 1735689600
}

Example response (401)

{
  "error": "Invalid API key provided",
  "type": "authentication_error",
  "code": "api_key_invalid"
}

Example response (404)

{
  "error": "Resource not found",
  "type": "not_found_error",
  "code": "resource_missing"
}

Example response (429)

{
  "error": "Too many requests",
  "type": "rate_limit_error",
  "code": "rate_limited"
}