Skip to main content

Payment Links

Generate shareable payment links for flexible payment collection scenarios.

Payment links provide a URL where customers can complete their payment. This guide covers creating and managing payment links.

Overview​

A payment link:

  • Associates with a payment order
  • Generates a checkout URL for customers
  • Has configurable lifetime (expiration)
  • Supports language and payment method customization
Amount Format

All amounts use minor currency units (e.g., cents for EUR), as integers:

  • Request: integer (e.g., 2500 for €25.00)
  • Response: integer (e.g., 2500 for €25.00)
Splits require a non-expiring, full-amount link

If the underlying order was created with splits, the payment link must not expire. Set lifetime: 0 — otherwise the request is rejected with validation_split_expiration_not_allowed. The link amount must also equal the order's full amount; a mismatch is rejected with validation_split_amount_mismatch (partial-amount links are only allowed for non-split orders).

Endpoints​

MethodEndpointDescription
POST/checkout-payment-link/integration/v1/payment-linksCreate a payment link
GET/checkout-payment-link/integration/v1/payment-links/{id}Get a payment link
GET/checkout-payment-link/integration/v1/payment-linksList payment links
PUT/checkout-payment-link/integration/v1/payment-links/{id}Update a payment link
PUT/checkout-payment-link/integration/v1/payment-links/{id}/cancelCancel a payment link
info

You can read a link with GET /payment-links/{id} and list links with GET /payment-links. Links can also be updated (PUT /payment-links/{id}) and canceled (PUT /payment-links/{id}/cancel). Webhooks remain available for state changes (see Webhooks).

Request​

curl -X POST https://api.paysera.com/checkout-payment-link/integration/v1/payment-links \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"order_id": "a6f2b8e3-5e5f-47d9-b13f-87ed2db2938a",
"name": "Order #12345",
"lifetime": 3600,
"experience": {
"language": "en",
"payment_flow": "paysera_checkout"
},
"purchase": {
"amount": 2500
},
"payment_details": {
"purpose": "Order #12345 - Leather Wallet",
"country_code": "LT"
},
"payer_information": {
"name": "John Doe",
"email": "john.doe@paysera.net"
},
"metadata": {
"referrer": "https://paysera.net"
}
}'

Request Parameters​

ParameterTypeRequiredDescription
order_idUUIDYesThe payment order ID
namestringYesDisplay name for the payment link (max 255 chars)
lifetimeintegerNoLink validity in seconds (default: 259200 = 3 days, 0 = never expire, max: 86313600). Must be 0 if the order has splits.
experienceobjectYesPayment experience configuration
experience.languagestringYesUI language code (ISO 639-1, e.g., "en", "lt")
experience.payment_flowstringNoPayment flow: "paysera_checkout" (default) or "direct_payment". direct_payment requires payment_details.key and payment_details.country_code, see Pre-selecting Payment Method
purchaseobjectYesPurchase information ({} for a payer-set order without overrides)
purchase.amountintegerYes, unless payer-setAmount in minor units (e.g., 2500 for €25.00). Omit it for a payer-set order
purchase.suggested_amountintegerNoPayer-set order only: overrides the order's suggested amount for this link
purchase.amount_buttonsarray of integersNoPayer-set order only: overrides the order's amount buttons for this link
payment_detailsobjectNoPayment method configuration
payment_details.keystringYes, with direct_paymentPayment method key (e.g., "swedbank"). Required with direct_payment: sets the method the payer is redirected to; omitting it returns 400 validation_payment_method_required. Deprecated with paysera_checkout: still accepted as a hint that lists the method right after Paysera, ahead of the project's display order. The order in which payment methods appear on the payment page is configured per project in the merchant portal (Payment Methods).
payment_details.purposestringNoPayment purpose description (max 255 chars). Used verbatim as the payer-facing payment purpose, truncated to 140 chars — see Payment purpose
payment_details.country_codestringFor direct_paymentISO 3166-1 alpha-2 country code. With direct_payment it selects the country of the payment method's bank. A direct_payment link without it is still accepted (no validation error) and opens the Paysera checkout page instead
payer_informationobjectNoCustomer information
payer_information.namestringNoCustomer name (max 150 chars)
payer_information.emailstringNoCustomer email
metadataobjectNoAdditional key-value metadata

Response​

{
"link_id": "c8d9e0f1-2a3b-4c5d-6e7f-8a9b0c1d2e3f",
"order_id": "a6f2b8e3-5e5f-47d9-b13f-87ed2db2938a",
"payment_URL": "https://api.paysera.com/checkout-payment-link/payment-collection/v1/payment-links/abc123def456GhiJkl_mNOpQrStUvWxYz0123456",
"experience": {
"language": "en",
"payment_flow": "paysera_checkout"
},
"purchase": {
"amount": 2500
},
"payment_details": {
"key": null,
"purpose": "Order #12345 - Leather Wallet",
"country_code": "LT"
},
"payer_information": {
"name": "John Doe",
"email": "john.doe@paysera.net"
},
"expired_at": 1736436870,
"created_at": 1736433270
}

Response Fields​

FieldTypeDescription
link_idUUIDUnique payment link identifier
order_idUUIDAssociated order identifier
payment_URLstringPayment URL for customer redirect
experienceobjectPayment experience configuration
experience.languagestringUI language code
experience.payment_flowstringPayment flow type
purchaseobjectPurchase information
purchase.amountLongAmount in minor units; null while the payer sets the amount
purchase.payer_sets_amountbooleanWhether the payer enters the amount (taken from the order)
purchase.minimum_amountLongThe order's minimum; null when the order set none
purchase.maximum_amountLongThe order's maximum; null when the order set none
purchase.suggested_amountLongSuggested amount for this link; null when not set
purchase.amount_buttonsarrayAmount buttons for this link; [] when none
payment_detailsobjectPayment details (if provided)
payment_details.keystringPayment method key
payment_details.purposestringThe purpose you sent, echoed back — null if you omitted it. See Payment purpose
payment_details.country_codestringCountry code
payer_informationobjectPayer information (if provided)
payer_information.namestringPayer name
payer_information.emailstringPayer email
expired_atLongExpiration Unix timestamp (seconds), null if never expires
created_atLongCreation Unix timestamp (seconds)

When the order was created with purchase.payer_sets_amount: true, create its link without purchase.amount (send "purchase": {} when you override nothing) — sending one is rejected with 400 payer_set_amount_with_amount. There is no payer-set flag or limit on the link: it takes them from the order, and the response echoes them under purchase.

A payer-set order takes a single payment: the first accepted payment fixes the amount and pays the order, after which its other links can no longer be paid. Create one order per payer, never one order behind a shared or public link. You may override the order's suggested amount and amount buttons for one link, for example to suggest a lower amount in an SMS reminder than in the first email to the same donor. Overrides follow the order's rules (buttons: three or four, strictly ascending; all values within the order's limits). Omitted or [] buttons keep the order's.

{
"order_id": "a6f2b8e3-5e5f-47d9-b13f-87ed2db2938a",
"name": "Donation",
"experience": { "language": "en" },
"purchase": {
"suggested_amount": 2500,
"amount_buttons": [1000, 2500, 5000]
}
}
  • payment_flow: direct_payment is not available for a payer-set order (400 validation_direct_payment_with_payer_set_amount).
  • Until the payer starts a payment, the link's purchase.amount is null. The amount the payer enters is then written to the link and to the order; a later attempt can overwrite it until a payment is accepted.
  • On a fixed-amount order, suggested_amount and amount_buttons are rejected (suggested_amount_without_payer_set, amount_buttons_without_payer_set).

On an order with tips_enabled, the payer is offered a tip only when the link's amount equals the order amount — not on a link for part of the order, including one for the balance left after a partial payment.

payment_flow: direct_payment is not available for an order that offers tips, whatever the link's amount: create those links with the default paysera_checkout flow.

  • An order with tips_enabled: true is rejected with 400 validation_direct_payment_with_tips, unless it was created with a split configuration or a stored card (tokenization) before those combinations were refused, where tips_enabled has no effect.
  • An order with a tip split is rejected with 400 validation_direct_payment_with_tip_rule.

Payment purpose​

The payment purpose is the narrative the payer sees on the payment page and on their bank statement. The resolved narrative — yours or the generated default — is returned as purpose on the payment object and in payment webhooks. The payment link object echoes back only what you sent in payment_details.purpose, so that field stays null when you omit it, even though the payer still sees the generated default.

The purpose is set at creation only. The management endpoints use a different, flat representation of the link and do not carry it at all: neither Get a Payment Link nor List Payment Links returns it, and Update a Payment Link cannot change it. To change the purpose, cancel the link and create a new one.

If you send payment_details.purpose, it is used verbatim as the payer-facing purpose, truncated to 140 characters (banks do not accept longer narratives, even though the field itself accepts up to 255). Write it in the language your payer should read — it is never translated.

If you omit it, Paysera generates a default narrative from the order and project:

Payment for order #<purchase.reference> at <business name> (<project website>)

The generated text is translated into experience.language; languages without a translation fall back to English. The (<project website>) suffix is omitted when the project has no website configured.

Merchant statement is separate

The text on your own settlement statement is always the generated English narrative with your legal or registered name, regardless of payment_details.purpose and experience.language, so your reconciliation text stays stable.

StatusCodeDescription
ActiveactiveLink is valid and can be used for payment
CompletedcompletedPayment completed successfully via this link
ExpiredexpiredLink has expired (can still complete if payment in-flight)
CanceledcanceledLink was invalidated
No Failed Status

Payment links do not have a failed status. If a payment attempt fails, the link remains active (unless expired or canceled), allowing the customer to retry.

See Payment Statuses Reference for complete status documentation.

Code Examples​

<?php

function createPaymentLink(string $accessToken, string $orderId, array $linkData): array
{
$ch = curl_init('https://api.paysera.com/checkout-payment-link/integration/v1/payment-links');

$payload = [
'order_id' => $orderId,
'name' => $linkData['name'],
'lifetime' => $linkData['lifetime'] ?? 3600,
'experience' => [
'language' => $linkData['language'] ?? 'en',
'payment_flow' => 'paysera_checkout',
],
'purchase' => [
'amount' => $linkData['amount'], // In minor units (cents)
],
];

// Add optional payer information
if (!empty($linkData['payer_email'])) {
$payload['payer_information'] = [
'name' => $linkData['payer_name'] ?? null,
'email' => $linkData['payer_email'],
];
}

// Optional payer country (filters the methods shown)
if (!empty($linkData['country_code'])) {
$payload['payment_details'] = [
'country_code' => $linkData['country_code'],
];
}

curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $accessToken,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode !== 201) {
throw new Exception('Failed to create payment link: ' . $response);
}

return json_decode($response, true);
}

// Usage - amount is in minor units (cents)
$link = createPaymentLink($accessToken, $orderId, [
'name' => 'Order #12345',
'amount' => 2500, // €25.00 in cents
'language' => 'en',
'lifetime' => 3600,
'payer_email' => 'customer@paysera.net',
]);

echo "Payment URL: " . $link['payment_URL'];

Pre-selecting Payment Method​

This section applies to the direct_payment flow only. To skip the payment method selection screen, set payment_flow to direct_payment and pass the method in payment_details.key and the payer's country in payment_details.country_code. Both are required: one method key can cover banks in several countries (for example Swedbank in LT, LV and EE), and the country selects which one opens. Let the payer choose the bank's country on your side, for example with a country selector next to the bank logos: a billing address does not tell which country's bank the payer uses.

curl -X POST https://api.paysera.com/checkout-payment-link/integration/v1/payment-links \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"order_id": "order-uuid",
"name": "Direct bank payment",
"lifetime": 3600,
"experience": {
"language": "en",
"payment_flow": "direct_payment"
},
"purchase": {
"amount": 2500
},
"payment_details": {
"key": "swedbank",
"country_code": "LT"
}
}'

A direct_payment link without country_code opens the Paysera checkout page instead, where the payer selects the country and payment method. This applies to every payment method, cards and wallets included.

Method hint on the hosted flow is deprecated

With the default paysera_checkout flow, payment_details.key is deprecated: the payment page still lists that method right after Paysera, ahead of the project's display order, and may open with it selected, but it does not skip the selection screen. Don't rely on it: set the order in which payment methods appear per project in the merchant portal (Payment Methods). To send the payer straight to a method, use direct_payment.

Getting Available Payment Methods​

To get the method keys to use in payment_details.key with the direct_payment flow:

curl -X GET "https://api.paysera.com/checkout-project/integration/v1/methods?amount=2500&currency=EUR" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Filtering by amount and currency is optional and only applied when both are provided. With the optional payer_country, a method that has payer countries is listed only when that country is enabled for it and the amount fits that country's limits, and available_countries holds only that country. Each method's min_amount and max_amount give the limits that apply.

Response includes available methods with their keys:

{
"items": [
{
"key": "swedbank",
"title": "Swedbank",
"description": "Pay via Swedbank online banking.",
"type": "pis",
"flow": "redirect",
"available_countries": ["EE", "LT", "LV"],
"available_currencies": {
"EUR": { "main": true }
}
},
{
"key": "seb",
"title": "SEB",
"type": "pis",
"flow": "redirect",
"available_countries": ["EE", "LT", "LV"],
"available_currencies": {
"EUR": { "main": true }
}
}
]
}

See Payment Methods Reference for the full field list.

Error Responses​

Invalid Order​

{
"error": "not_found",
"error_description": "Order not found"
}

Validation Error​

{
"error": "invalid_properties",
"error_description": "Validation failed",
"error_properties": {
"purchase.amount": ["Amount should be greater than 0"],
"experience.language": ["Language is required"]
}
}

Creating a link whose name is already used by another link on the same order returns 409 Conflict:

{
"error": "validation_duplicate_name",
"error_description": "A payment link with this name already exists"
}

Authentication Failure​

{
"error": "unauthorized",
"error_description": "Authentication is required to access this resource"
}
GET /checkout-payment-link/integration/v1/payment-links/{id}

Retrieves a single payment link. Expired links are recognised on read and reflected in status.

curl https://api.paysera.com/checkout-payment-link/integration/v1/payment-links/{id} \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response​

{
"id": "c8d9e0f1-2a3b-4c5d-6e7f-8a9b0c1d2e3f",
"order_id": "a6f2b8e3-5e5f-47d9-b13f-87ed2db2938a",
"project_id": "your-project-id",
"name": "Order #12345",
"amount": 2500,
"currency": "EUR",
"language": "en",
"country_code": "LT",
"link": { "url": "https://api.paysera.com/…/payment-links/abc123", "hash": "abc123" },
"preferred_payment_method_key": "swedbank",
"status": "active",
"is_personalized": true,
"expired_at": 1736436870,
"created_at": 1736433270,
"updated_at": 1736433270,
"payer_sets_amount": false,
"minimum_amount": null,
"maximum_amount": null,
"suggested_amount": null,
"amount_buttons": []
}

On a payer-set link, amount is null until the payer starts a payment, payer_sets_amount is true and minimum_amount / maximum_amount are the order's limits (null when the order set none). suggested_amount and amount_buttons are the link's own values, inherited from the order unless the link overrides them. List items carry the same fields.

GET /checkout-payment-link/integration/v1/payment-links

Returns a cursor-paginated list of payment links for your project.

curl "https://api.paysera.com/checkout-payment-link/integration/v1/payment-links?status=active&size=50" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Filter Parameters​

ParameterTypeDescription
order_idUUIDFilter by associated order
statusstringComma-separated statuses, e.g. active,expired

Pagination Parameters​

The order, payment link, payment and refund list endpoints share the same cursor-based pagination. Cursors are opaque strings — read them from _metadata.cursors and send them back unchanged; never build or parse them yourself.

ParameterTypeDefaultDescription
sizeinteger10Items per page (1–1000). Out-of-range values return 400 invalid_properties.
afterstring—Cursor for the next page. Take it from _metadata.cursors.after.
beforestring—Cursor for the previous page. Take it from _metadata.cursors.before. Mutually exclusive with after.
order_directionstringdescSort direction: asc or desc.
order_bystringcreation timeField to sort by. Allowed values differ per endpoint — see the endpoint's parameter table.
include_total_countbooleanfalseSet to true to populate _metadata.total. Off by default because counting is more expensive.

Every list response has the same envelope:

{
"items": [],
"_metadata": {
"has_next": true,
"has_previous": false,
"cursors": {
"after": "MDE5ZmRiMmUtOWE5NC03ZDVmLThmY2ItNGRhMTQ1MzFkZGQ0",
"before": "MDE5ZmRjMjgtNWQ5YS03NjQ5LWExOWItZDhjNDAzODQ2NTRi"
},
"total": null
}
}

total is null unless you pass include_total_count=true.

To walk the whole collection, keep sending after until has_next is false:

# first page
curl "https://api.paysera.com/merchant-order/integration/v1/orders?size=50" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# next page — reuse _metadata.cursors.after from the previous response
curl "https://api.paysera.com/merchant-order/integration/v1/orders?size=50&after=MDE5ZmRiMmUtOWE5NC03ZDVmLThmY2ItNGRhMTQ1MzFkZGQ0" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Unknown query parameters are ignored

The API does not reject parameters it doesn't know. Sending limit or cursor (names used by some other APIs) does not return an error — the values are silently dropped and you keep receiving the first page with the default size of 10. If pagination seems stuck, check the parameter names first.

order_by accepts created_at (default), updated_at, status, amount, currency and name.

Response​

{
"items": [
{
"id": "c8d9e0f1-2a3b-4c5d-6e7f-8a9b0c1d2e3f",
"link": { "url": "https://api.paysera.com/…/payment-links/abc123", "hash": "abc123" },
"project_id": "your-project-id",
"order_id": "a6f2b8e3-5e5f-47d9-b13f-87ed2db2938a",
"name": "Order #12345",
"amount": 2500,
"currency": "EUR",
"language": "en",
"country_code": "LT",
"receiver": { "name": null, "email": null },
"payer": { "name": "Jonas Jonaitis", "email": "jonas@example.com" },
"expired_at": 1736436870,
"preferred_payment_method_key": "swedbank",
"status": "active",
"is_personalized": true,
"created_at": 1736433270,
"updated_at": 1736433270,
"is_test": false,
"payer_sets_amount": false,
"minimum_amount": null,
"maximum_amount": null,
"suggested_amount": null,
"amount_buttons": []
}
],
"_metadata": {
"has_next": true,
"has_previous": false,
"cursors": {
"after": "MDE5ZmRiMmUtYTY2Ny03MjFiLTkyZjMtNTUxODk4ZDg5OWM2",
"before": "MDE5ZmRjMjgtNjYwMy03NzJhLWI3NjQtNzM3NGViM2Q4MTUx"
},
"total": null
}
}
PUT /checkout-payment-link/integration/v1/payment-links/{id}

Updates a payment link. This is a full replacement — send all required fields; changes take effect immediately. The full updated payment-link object is returned. A payer-set link cannot be updated: the request is rejected with 400 payer_set_amount_not_editable.

Different field names from create

The update request uses a flat structure and names the lifetime field link_lifetime — unlike the create request, which nests purchase.amount / experience.language and names the field lifetime. This difference is intentional; use the field names shown below when updating. As with create, set link_lifetime: 0 if the order has splits.

Request Parameters​

ParameterTypeRequiredDescription
namestringYesDisplay name (max 255 chars)
amountintegerYesAmount in minor units (≥ 1)
currencystringYesISO 4217 currency
languagestringYesUI language (ISO 639-1)
payerobjectYes{ name, email }
receiverobjectNo{ name, email }
link_lifetimeintegerNoSeconds; default 259200 (3 days), 0 = never expires (max 86313600). Must be 0 if the order has splits.
preferred_payment_method_keystringYes, with direct_paymentPayment method key. Required on a direct_payment link: it sets the method the payer is redirected to; omitting it returns 400 validation_payment_method_required, and a different key moves the redirect to that method. Deprecated on a paysera_checkout link: still accepted as a hint that lists the method right after Paysera, ahead of the project's display order. The order in which payment methods appear on the payment page is configured per project in the merchant portal (Payment Methods).
PUT /checkout-payment-link/integration/v1/payment-links/{id}/cancel

Cancels a payment link. The request body is empty; a 200 OK is returned.

Idempotent

Re-cancelling an already-canceled link succeeds. A 409 is returned only if the link has an active payment session in progress.