Skip to main content

Payment Orders

Create and manage payment orders - the core transaction record in Paysera Checkout.

Payment orders represent the core transaction record in Paysera Checkout. This guide covers creating and managing orders via the API.

Overview​

A payment order contains:

  • Transaction amount, currency, and your merchant reference (your order ID)
  • Optional redirect URLs for success/failure/callback
  • Optional metadata and merchant_data key-value pairs
  • Optional splits describing how the funds should be distributed (see Split Payments)
  • Optionally, instead of a fixed amount, limits within which the payer sets the amount
  • Optionally, a tip the payer may add on top of a fixed amount
note

redirect_urls.* fields are optional in the create-order request. Provide them per environment if you need browser redirects after payment.

Amount Format

All amounts in the API use minor currency units (e.g., cents for EUR, pennies for GBP):

  • Request: integer (e.g., 2500 for €25.00)
  • Response: Long/integer format (e.g., 2500 for €25.00)

Endpoints​

For complete request/response schemas and examples, see the Endpoint Reference:

MethodEndpointDescription
POST/merchant-order/integration/v1/ordersCreate an order
GET/merchant-order/integration/v1/orders/{id}Get a single order
GET/merchant-order/integration/v1/ordersList orders
PATCH/merchant-order/integration/v1/orders/{id}Update an order before payment
info

Order state is pushed to your callback_url via webhooks (recommended for real-time updates). You can also read order state directly with GET /orders/{id} and GET /orders — useful for reconciliation and on-demand lookups. See Webhooks.

No idempotency key

Order creation does not support an idempotency key, and purchase.reference is not enforced unique — retrying POST /orders creates a second order (the server-generated order_id is the unique key). Guard retries on your side (e.g. track the order_id you got back, or check before retrying). Refunds, by contrast, take an idempotency-key header — see Refunds.

Order Statuses​

StatusCodeDescription
Pending Paymentpending_paymentOrder created, awaiting payment
PaidpaidOrder fully paid
CanceledcanceledOrder was canceled before anything was paid
ClosedclosedReserved, not currently used

Only a pending_payment order with nothing paid can be canceled: by the merchant in the Paysera Merchant Portal, by Paysera support, when its project is deleted, when it expires unpaid, or when the reusable payment link it was opened from is deactivated (unless a checkout session or payment is in progress, then the order stays pending_payment). GET /orders/{id} returns the cancel reason as cancel_reason, for example canceled_by_merchant, canceled_by_admin, project_deleted, expired_ttl or order_template_deactivated; it is null unless the order is canceled. Treat unknown values as a generic cancel. You receive an order canceled webhook when it happens.

See Payment Statuses Reference for complete status documentation.

Splits​

If the merchant has enabled automatic splits or payer tips through Split Payments on the project (for tips without Split Payments, see Tips), attach a splits array to the order to control how the funds are distributed. The merchant's share, fixed shares, and percentages all come from the project's policy template — your integration only sends the per-order pieces. See the Split Payments concept page for the full picture, including how to register beneficiaries.

Activation required

Automatic splits and payer tips through Split Payments are not enabled by default. The merchant must request activation through Paysera customer support before the splits field can be used. Until the project is configured, requests with splits are rejected (for example with intermediary_account_required).

There are two per-order mechanisms: splits[] (fill variadic slots / add tips, referencing registered beneficiaries by id or declaring them inline) and split_overrides (restate the whole policy for one order — and the only path that accepts a recipient account directly). Discover your policy's slot_ids and roles via GET /checkout-project/integration/v1/project/split-policy.

splits[] entries name their recipient by registered beneficiary id or with an inline declaration:

FieldTypeRequiredDescription
splits[].typestring✓variadic (the per-order recipient for the policy's variadic slot) or tip (an extra tip recipient)
splits[].beneficiary_idstring (UUID)one ofId of the registered beneficiary to pay. Provide either this or beneficiary
splits[].beneficiaryobjectone ofInline declaration { "iban": ..., "name": ... } — registers the recipient on the fly. Provide either this or beneficiary_id
splits[].slot_idstring (UUID)Variadic slot to bind to. Required only when the policy has more than one variadic slot; ignored for tips
Payment-link lifetime

Orders with splits require a non-expiring payment link. Pass lifetime: 0 when creating the payment link.

Example: variadic​

The policy template has a variadic slot — your integration points it at the per-order recipient's beneficiary (the marketplace seller, courier, freelancer, etc.):

"splits": [
{ "type": "variadic", "beneficiary_id": "550e8400-e29b-41d4-a716-446655440000" }
]

Example: tip​

Payer tips through Split Payments are enabled (for tips without Split Payments, see Tips). The customer's bill follows the policy template; one entry routes any tip the payer adds to the recipient's beneficiary:

"splits": [
{ "type": "tip", "beneficiary_id": "550e8400-e29b-41d4-a716-446655440000" }
]

Per-order rule overrides​

When the project has per-order overrides enabled, send a split_overrides block instead to restate the whole policy for a single order — change each slot's rule and recipient without altering the saved policy. Override recipients may be a registered beneficiary_id, a Paysera account paid directly (no registration), or an inline beneficiary declaration. See Per-order rule overrides for the full rules.

"split_overrides": {
"slots": [
{ "slot_id": "MERCHANT_SLOT_ID", "type": "remainder" },
{ "slot_id": "VARIADIC_SLOT_ID", "type": "fixed", "value": 1500,
"recipient": { "account": "LT403500010018497892" } }
]
}

Let the payer set the amount​

For donations, top-ups or "pay what you want" sales, let the payer enter the amount on the Paysera payment page instead of fixing it on the order. Set purchase.payer_sets_amount to true and omit purchase.amount:

{
"purchase": {
"reference": "DONATION-2026-001",
"currency": "EUR",
"payer_sets_amount": true,
"minimum_amount": 500,
"maximum_amount": 50000,
"suggested_amount": 2000,
"amount_buttons": [1000, 2000, 5000]
}
}
FieldTypeRequiredDescription
purchase.payer_sets_amountbooleantrue lets the payer enter the amount (default false). purchase.amount must then be omitted
purchase.minimum_amountintegerLowest amount the payer may enter, in minor units; at least 1. Omitted: the floor of 1 applies
purchase.maximum_amountintegerHighest amount the payer may enter, in minor units; at most 1000000 and above the minimum. Omitted: the platform maximum of 1000000 applies
purchase.suggested_amountintegerAmount prefilled in the payer's amount input; the payer can change it. Must be within the limits
purchase.amount_buttonsarray of integersThree or four amounts the payer can pick with one tap, strictly ascending and within the limits. Shown in the order you send them. [] is the same as omitting it

The limits, the suggested amount and the buttons are accepted only together with payer_sets_amount: true. All values are minor units of the order currency; the floor and the platform maximum are the same numbers in every currency. When you omit a limit, the response, GET /orders/{id} and the webhook return it as null, and the floor or the platform maximum applies.

Prerequisites
  • Switch the capability on. In the merchant dashboard, open the project's Features page and switch on Payer-set amount. Until then, orders with payer_sets_amount: true are rejected with 422 payer_set_amount_not_enabled.
  • No split payments. Payer-set amount is not available on a project with split payments, and an order cannot combine it with splits or split_overrides (422 payer_set_amount_with_split_payments): split shares are computed from an amount the order does not have yet.
  • No tips. A payer-set order cannot offer a tip (422 tips_and_payer_set_amount_conflict).
  • Stored cards. If the order stores the payer's card (tokenization), tokenization.max_amount must be at least maximum_amount, or 1000000 when you omit it (400 invalid_properties on tokenization.max_amount).

How the amount is set. The order is created without an amount: purchase.amount and balance_due are null. When the payer enters an amount and starts a payment, that amount is written to the order and to the payment link. It is not final yet: while no payment has been accepted, a later attempt (say, after the payer abandoned the first one) can overwrite it. The amount becomes final when a payment is accepted — it is then set to that payment's amount, and payment_accepted_at is filled. So a non-null amount alone does not mean the payer committed to it. A payer-set order takes a single payment: the first accepted payment fixes the amount and pays the order, so use one order per payer (for example, one order per donor). Read the final amount from the amount_paid_updated webhook or GET /orders/{id}, never from your own records. A payer-set order's amount and currency cannot be changed with Update an Order (422 payer_set_amount_not_editable).

Create the payment link without purchase.amount; the link takes the flag and the limits from the order. The SDK sets these fields with the payer-set arguments of Purchase — see SDK Payments.

Validation errors are listed under Payer-Set Amount and Tip Errors.

Tips​

To let the payer add a tip on top of a fixed amount — for example a taxi driver, a hairdresser or a courier working alone — set tips_enabled to true on the order. The tip goes to the merchant together with the payment; no split policy or beneficiary is involved.

{
"purchase": {
"reference": "ORDER-12345",
"amount": 4000,
"currency": "EUR"
},
"tips_enabled": true
}

The payer chooses the tip on the Paysera payment page. purchase.amount stays the bill; the tip is added on top of it:

  • amount_paid includes the tip, so it exceeds amount by the tip. A €40.00 order with a €4.00 tip reports amount: 4000, amount_paid: 4400 and tip_amount: 400.
  • tip_amount is on the order (order currency) and on each payment (payment currency) in the amount_paid_updated webhook, and on the order in GET /orders/{id}. It is null when no tip was paid. A tip in another currency than the order, or larger than the settled payment, is not recorded on the order: it counts towards the bill instead, and only the payment carries it.
  • A tip is offered only when the payment link's amount equals the order amount. A link for part of the order — including one for the balance left after a partial payment — gets no tip.
  • A link with experience.payment_flow: direct_payment cannot be created for the order (400 validation_direct_payment_with_tips), whatever its amount. Use the default paysera_checkout flow. This does not apply to an order on which tips_enabled has no effect (see below). A direct link for an order with a tip split is refused with 400 validation_direct_payment_with_tip_rule.
  • balance_due ignores tips: it is amount minus (amount_paid − tip_amount, with a null tip_amount as 0), so a tip never pays off the bill.
  • The payment method's maximum is checked against the bill plus the tip. If only the tip takes the total over it, the payment is refused (tips_exceed_payment_method_limit) and the payer is shown the limit, so they can lower the tip or pick another method.
  • A tipped payment's amount in Payments and in the thin payment webhook includes the tip, and so does the amount you can refund.
  • tips_enabled is not available on a project with split payments, whose tips follow Split Payments, or on an order that stores the payer's card (tokenization); see the prerequisites below. Orders created before these refusals keep working as created: on one with a split configuration or tokenization, tips_enabled has no effect (the order echoes tips_enabled: true, but the payer is never offered a tip); on any other, the payer is offered the tip. An order has a split configuration when it was sent with splits or split_overrides, or created on a project with a split policy. The flag is read from the order, so switching Tips off in Features does not affect orders already created.
Prerequisites
  • Switch tips on. In the merchant dashboard, open the project's Features page and switch on Tips. Until then, orders with tips_enabled: true are rejected with 422 tips_not_enabled.
  • Fixed amount only. tips_enabled cannot be combined with purchase.payer_sets_amount (422 tips_and_payer_set_amount_conflict).
  • No split payments. Tips cannot be switched on for a project with split payments, and an order with tips_enabled: true on such a project is rejected with 422 tips_with_split_payments, also when split payments were switched on after Tips. Payer tips through Split Payments work as before.
  • No stored cards. An order that stores the payer's card (tokenization) cannot offer a tip (422 tips_and_tokenization_conflict).

tips_enabled is separate from tips routed to a beneficiary through Split Payments (splits[].type: "tip"); those still report the tip in tip_amount, so tip_amount can be set while tips_enabled is false.

Code Examples​

Splits not shown below

The samples in this section create an order without splits — the most common entry point. If you need automatic splits or payer tips through Split Payments, take any sample below and add a splits array next to purchase in the request body, using one of the shapes documented in the Splits section above. Don't copy-paste these samples if your project has a policy that requires a variadic entry — the API will return variadic_entry_required.

<?php

function createPaymentOrder(string $accessToken, array $orderData): array
{
$ch = curl_init('https://api.paysera.com/merchant-order/integration/v1/orders');

curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $accessToken,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'redirect_urls' => [
'success_url' => $orderData['success_url'],
'failure_url' => $orderData['failure_url'],
'callback_url' => $orderData['callback_url'],
],
'purchase' => [
'reference' => $orderData['reference'],
'amount' => $orderData['amount'], // Integer, already in minor units
'currency' => $orderData['currency'],
],
]),
]);

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

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

return json_decode($response, true);
}

// Usage - amount is in minor units (cents)
$order = createPaymentOrder($accessToken, [
'success_url' => 'https://your-site.paysera.net/success',
'failure_url' => 'https://your-site.paysera.net/failure',
'callback_url' => 'https://your-site.paysera.net/webhook',
'reference' => 'ORDER-12345',
'amount' => 2500, // €25.00 in cents
'currency' => 'EUR',
]);

echo "Order ID: " . $order['order_id'];
// Note: To get a payment URL, create a payment link using this order_id

Reading and Updating Orders​

You can read an order directly and update it before payment. Webhooks remain the recommended push channel for real-time status changes (see Webhooks).

Get an Order​

GET /merchant-order/integration/v1/orders/{id}

Retrieves a single order by its identifier. The order must belong to your project.

curl https://api.paysera.com/merchant-order/integration/v1/orders/{id} \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Path Parameters​

ParameterTypeRequiredDescription
idUUIDYesOrder identifier

Response​

{
"id": "a6f2b8e3-5e5f-47d9-b13f-87ed2db2938a",
"project_id": "your-project-id",
"amount": 2500,
"currency": "EUR",
"status": "paid",
"reference": "ORDER-12345",
"amount_paid": 2500,
"balance_due": 0,
"callback_url": "https://example.com/webhook",
"success_url": "https://example.com/success",
"fail_url": "https://example.com/failure",
"source": "Integration",
"created_at": 1736433000,
"updated_at": 1736433600,
"payment_accepted_at": 1736433540,
"payer_sets_amount": false,
"minimum_amount": null,
"maximum_amount": null,
"suggested_amount": null,
"amount_buttons": [],
"tips_enabled": false,
"tip_amount": null,
"order_template": null,
"payer_text": null
}

On a payer-set order, amount and balance_due are null until the payer starts a payment, and amount is final only once payment_accepted_at is set. payment_accepted_at is when a payment of the order was first accepted (authorized or later), null until then. tip_amount is included in amount_paid but not in balance_due (see Tips). order_template names the reusable payment link the order was opened from, and payer_text is the text the payer saw; both are null for an order created any other way. order_template.id is the order template id, not a payment link id.

Polling vs webhooks

Webhooks remain the recommended way to react to order changes in real time. Use this endpoint for reconciliation or on-demand lookups.

List Orders​

GET /merchant-order/integration/v1/orders

Returns a cursor-paginated list of orders for your project. Filters can be combined freely.

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

Filter Parameters​

ParameterTypeDescription
statusstringFilter by one or more order statuses (repeat the parameter: status=paid&status=canceled)
amount, amount_gte, amount_lteintegerExact / range filter on amount (minor units)
amount_paid, amount_paid_gte, amount_paid_lteintegerExact / range filter on amount paid
currencystringFilter by one or more ISO 4217 currencies (repeatable)
created_at_gte, created_at_lteintegerCreated-at range (Unix seconds)
qstringPrefix search over reference — matches references that start with the value (max 255 chars)
payer_sets_amountbooleantrue: only orders where the payer sets the amount; false: only fixed-amount orders; omitted: all
order_template_ordersstringOrders opened from a reusable payment link: shown (default) includes them, hidden excludes them, only returns nothing else

Repeatable filters use the plain repeated form (status=paid&status=canceled). The bracket form status[]=paid is not recognized — like any unknown parameter it is silently ignored, so the list comes back unfiltered.

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), status, amount, amount_paid, currency and reference. Any other value returns 400 invalid_properties.

Response​

{
"items": [
{
"id": "a6f2b8e3-5e5f-47d9-b13f-87ed2db2938a",
"project_id": "your-project-id",
"amount": 2500,
"amount_paid": 2500,
"currency": "EUR",
"status": "paid",
"reference": "ORDER-12345",
"callback_url": "https://example.com/webhook",
"success_url": "https://example.com/success",
"fail_url": "https://example.com/failure",
"cancel_url": null,
"created_at": 1736433000,
"payment_accepted_at": 1736433540,
"payer_sets_amount": false,
"minimum_amount": null,
"maximum_amount": null,
"suggested_amount": null,
"amount_buttons": [],
"tips_enabled": false,
"tip_amount": null,
"order_template": null,
"payer_text": null
}
],
"_metadata": {
"has_next": true,
"has_previous": false,
"cursors": {
"after": "MDE5ZmRiMmUtOWE5NC03ZDVmLThmY2ItNGRhMTQ1MzFkZGQ0",
"before": "MDE5ZmRjMjgtNWQ5YS03NjQ5LWExOWItZDhjNDAzODQ2NTRi"
},
"total": null
}
}

List items carry fewer fields than Get an Order — source, updated_at, balance_due, merchant_data and split_config_id are returned only by the single-order endpoint.

Update an Order​

PATCH /merchant-order/integration/v1/orders/{id}

Partially updates an order before payment. At least one field must be provided. Changing amount or currency cancels any active payment link for the order.

warning

Returns 422 if the order is already paid or canceled.

On a payer-set order, amount and currency cannot be changed: the patch is rejected with 422 payer_set_amount_not_editable.

On an order with splits, changing amount or currency first re-validates the order's split configuration against the new amount. If the new amount is below what the split rules need, the patch is rejected with 422 split_amount_too_low and nothing changes — the amount stays as it was and active payment links are not cancelled.

Request​

curl -X PATCH https://api.paysera.com/merchant-order/integration/v1/orders/{id} \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "reference": "ORDER-12345-REV2", "amount": 3000, "currency": "EUR" }'

Request Parameters​

ParameterTypeRequiredDescription
referencestringNoMerchant reference (max 255 chars)
amountintegerNoNew amount in minor units (e.g. 3000 for €30.00)
currencystringNoNew currency (ISO 4217)

All fields optional; at least one required.

Response​

{ "order_id": "a6f2b8e3-5e5f-47d9-b13f-87ed2db2938a" }

Error Responses​

Validation Error​

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

Invalid Project​

{
"error": "not_found",
"error_description": "Project not found or access denied"
}

Authentication Failure​

{
"error": "unauthorized",
"error_description": "Authentication is required to access this resource"
}