Payment Links & QR Codes

Payment links let you create reusable or one-time payment pages without writing any checkout UI. QR codes are generated from payment links and can be printed, embedded in emails, or shown on POS screens.

---

Create a payment link

POST /api/v1/links

curl -X POST https://4pay.online/api/v1/links \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444" \
  -d '{
    "amount": {
      "default": 1000,
      "currency": "RUB"
    },
    "amount_type": "fixed",
    "pay_config": {
      "methods": ["card"]
    }
  }'

Parameters

Field	Type	Required	Description
amount	object	✓	Amount object
amount.default	integer	✓	Amount in the smallest currency unit (e.g. kopecks for RUB)
amount.currency	string	✓	ISO 4217 currency code (e.g. "RUB", "USD")
amount_type	string	✓	"fixed" — payer sees fixed amount; "dynamic" — payer enters amount
pay_config	object	✓	Payment configuration
pay_config.methods	array	—	Enabled payment methods, e.g. ["card", "sbp"]
products	array	—	Array of product UUIDs to attach to the link. Products must belong to the same partner. On update, replaces the current list entirely
image	string	—	Image URL obtained via POST /api/v1/images

Response

{
  "data": {
    "id": "abc12345-0000-0000-0000-000000000000",
    "created": "2026-03-01T10:00:00+00:00",
    "partner_id": 42,
    "amount": {
      "default": 1000,
      "currency": "RUB"
    },
    "amount_type": "fixed",
    "pay_config": {
      "methods": ["card"]
    },
    "image": null,
    "products": []
  }
}

---

Attach products to a payment link

Products and payment links have a many-to-many relationship. One link can contain multiple products, and one product can be attached to multiple links.

Step-by-step

1. Create products via POST /api/v1/products and save their id values
2. Create a link with the products field containing an array of product UUIDs:

curl -X POST https://4pay.online/api/v1/links \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444" \
  -d '{
    "amount": { "default": 198000, "currency": "RUB" },
    "amount_type": "fixed",
    "pay_config": { "methods": ["card"] },
    "products": [
      "550e8400-e29b-41d4-a716-446655440000",
      "660f9500-f39c-52e5-b827-557766551111"
    ]
  }'

3. The response returns products as an array of full product objects (with price, header, image, etc.)

Update product binding

To change the attached products, pass a new UUID array in PATCH /api/v1/links/:id:

curl -X PATCH https://4pay.online/api/v1/links/abc12345-... \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444" \
  -d '{ "products": ["550e8400-e29b-41d4-a716-446655440000"] }'

The products array fully replaces the current binding. To detach all products, send "products": [].

Scenario	Result
UUID not found	Product is silently ignored
Empty array []	Link with no products
products field omitted	Binding unchanged (on update)

---

Get a payment link

GET /api/v1/links/:id

curl https://4pay.online/api/v1/links/abc12345-... \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444"

---

List payment links

GET /api/v1/links

curl https://4pay.online/api/v1/links \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444"

---

Update a payment link

PATCH /api/v1/links/:id

curl -X PATCH https://4pay.online/api/v1/links/abc12345-... \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444" \
  -d '{
    "amount": {
      "default": 2000,
      "currency": "RUB"
    }
  }'

---

Delete a payment link

DELETE /api/v1/links/:id

curl -X DELETE https://4pay.online/api/v1/links/abc12345-... \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444"

---

Webhook for link payments

A link payment produces the same webhook as any other payment — there is no separate link event type:

{
  "event_id": "4d9d0e6c-1d0a-4a2e-9a2f-0c9a1b0e8f21",
  "timestamp": 1772668800,
  "type": "transaction.charged",
  "data": {
    "type": "payment",
    "txid": "generated-txid",
    "id": "550e8400-...",
    "status": "charged",
    "amount": "1000",
    "amount_dest": "950",
    "amount_with_fee": "1050",
    "error_description": ""
  }
}

To find out which link was paid, read the transaction back with GET /api/v1/transactions/{id} — it carries link_id.

---

QR Code Products

For retail or POS use cases, you can create products with QR codes that trigger a fixed-price payment flow:

POST /api/v1/products

curl -X POST https://4pay.online/api/v1/products \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444" \
  -d '{
    "header": "Coffee",
    "text": "Espresso 200ml",
    "price": 350,
    "currency": "RUB",
    "qty": "1"
  }'

Product parameters

Field	Type	Required	Description
header	string	✓	Product name shown on the payment page
text	string	✓	Short product description
price	integer	—	Price in the smallest currency unit
currency	string	—	ISO 4217 currency code (default: "RUB")
qty	string	—	Quantity (default: "1")
image	string	—	Image URL obtained via POST /api/v1/images

Each product generates a dedicated QR code that can be printed and used indefinitely.

---

Upload an image

Images for products and payment links are uploaded separately and then referenced by URL.

POST /api/v1/images
Content-Type: multipart/form-data

curl -X POST https://4pay.online/api/v1/images \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444" \
  -F "image=@photo.jpg"

Response

{
  "data": {
    "url": "https://s3.example.com/images/uploads/42/1709472000000photo.jpg"
  }
}

Use the returned url in the image field when creating or updating products and links.