Create Order
POST https://api.paysera.com/merchant-order/integration/v1/orders
Creates a new payment order in the system. The order represents the core transaction record and must be created before generating a payment link.
Authorization​
This endpoint requires OAuth2 Bearer token authentication.
Authorization Header Format:
Authorization: Bearer YOUR_ACCESS_TOKEN
For more details, see the Authentication section.
Request Body​
| Field | Type | Required | Description |
|---|---|---|---|
project_id | string (UUID) | Your merchant project ID (defaults to the project from your JWT token) | |
redirect_urls.success_url | string | URL to redirect customer after successful payment | |
redirect_urls.failure_url | string | URL to redirect customer after failed payment | |
redirect_urls.callback_url | string | Webhook URL for payment notifications (omit and you receive no webhooks) | |
redirect_urls.cancel_url | string | URL to redirect customer when the payment is canceled | |
purchase.reference | string | ✓ | Your unique order reference (e.g., order ID in your system) |
purchase.amount | integer | ✓ (unless payer_sets_amount) | Amount in minor units (e.g., 2500 for €25.00). Omit it when purchase.payer_sets_amount is true |
purchase.currency | string | ✓ | ISO 4217 currency code (e.g., EUR) |
purchase.payer_sets_amount | boolean | true lets the payer enter the amount on the payment page (default false). Requires payer-set amount switched on under Features in the merchant dashboard; not available with split payments. See Let the payer set the amount | |
purchase.minimum_amount | integer | Lowest amount the payer may enter, in minor units. Only with payer_sets_amount; at least 1. Omitted: the floor of 1 applies | |
purchase.maximum_amount | integer | Highest amount the payer may enter, in minor units. Only with payer_sets_amount; at most 1000000 and above minimum_amount. Omitted: the platform maximum of 1000000 applies | |
purchase.suggested_amount | integer | Amount prefilled in the payer's amount input, in minor units; the payer can change it. Only with payer_sets_amount, within the limits | |
purchase.amount_buttons | array of integers | Three or four amounts the payer can pick, in minor units, strictly ascending and within the limits; shown in the order sent. Only with payer_sets_amount. [] is the same as omitting it | |
tips_enabled | boolean | true offers the payer a tip on top of the fixed amount, without Split Payments (default false). Requires tips switched on under Features in the merchant dashboard; not with purchase.payer_sets_amount or tokenization, and not on a project with split payments. See Tips | |
splits | array | Per-order entries for the project's split policy. Required when the policy has a variadic slot. See Split Payments. | |
splits[].type | string | ✓ (when splits present) | variadic (the per-order recipient for the policy's variadic slot) or tip (an extra tip recipient) |
splits[].beneficiary_id | string | one of | Id of the registered beneficiary to pay (UUID). Provide either this or beneficiary |
splits[].beneficiary | object | one of | Inline declaration { "iban": ..., "name": ... } — registers the recipient on the fly. Provide either this or beneficiary_id |
splits[].slot_id | string | Variadic slot to bind to. Required only when the policy has more than one variadic slot; ignored for tips | |
split_overrides | object | Per-order restatement of the whole split policy. Accepts a recipient account directly (no registration). Requires per-order overrides enabled. See Per-order rule overrides. | |
metadata | object | Key-value metadata. Include referrer (your site URL) for origin verification. An integration partner may report itself with tpi_id — see Report integration partner |
All amounts use minor currency units (e.g., cents for EUR). The amount 2500 represents €25.00.
Response​
| Field | Type | Description |
|---|---|---|
project_id | string (UUID) | Project identifier associated with the order |
order_id | string (UUID) | Unique order identifier |
created_at | integer | Creation timestamp in UTC timezone |
merchant_data | object | Key-value merchant data attached to the order |
source | string | Source indicating where this order originated from |
purchase.reference | string | Unique identifier for the order in the merchant system |
purchase.amount | integer | null | Order amount in minor currency units (cents), returned as an integer. null when the payer sets the amount |
purchase.currency | string | Currency code in ISO 4217 format |
purchase.payer_sets_amount | boolean | Whether the payer enters the amount |
purchase.minimum_amount | integer | null | Minimum as you sent it; null when omitted |
purchase.maximum_amount | integer | null | Maximum as you sent it; null when omitted |
purchase.suggested_amount | integer | null | Suggested amount; null when not set |
purchase.amount_buttons | array of integers | Amount buttons in the order sent; [] when not set |
tips_enabled | boolean | Whether the payer is offered a tip |
Example​
Request​
POST https://api.paysera.com/merchant-order/integration/v1/orders
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
{
"project_id": "b7c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
"redirect_urls": {
"success_url": "https://example.com/checkout/success",
"failure_url": "https://example.com/checkout/failure",
"callback_url": "https://example.com/webhooks/paysera"
},
"purchase": {
"reference": "ORDER-12345",
"amount": 2500,
"currency": "EUR"
},
"metadata": {
"referrer": "https://example.com",
"platform": "my-ecommerce",
"platform_version": "2.0.0",
"tpi_id": "hostinger"
}
}
Splits Example​
When the merchant project has a configured split policy with a variadic slot, attach the recipient per order — by beneficiary_id (registered up front) or with an inline beneficiary declaration (see Split Payments); the remaining shares come from the policy template:
{
"purchase": {
"reference": "ORDER-12345",
"amount": 100000,
"currency": "EUR"
},
"splits": [
{ "type": "variadic", "beneficiary_id": "550e8400-e29b-41d4-a716-446655440000" }
]
}
For payer tips routed to a split recipient, use "type": "tip" (one entry per recipient). See Split Payments for the full reference. Orders with splits require a non-expiring payment link — set lifetime: 0 when creating the link.
Payer-Set Amount Example​
The payer enters any amount from €5.00 to €500.00, with €20.00 prefilled and three quick picks. 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]
}
}
Tips Example​
A fixed-amount order where the payer may add a tip on the payment page:
{
"purchase": {
"reference": "ORDER-12345",
"amount": 4000,
"currency": "EUR"
},
"tips_enabled": true
}
Response​
{
"project_id": "b7c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
"order_id": "a6f2b8e3-5e5f-47d9-b13f-87ed2db2938a",
"created_at": 1736433270,
"merchant_data": {
"key1": "value1",
"key2": "value2"
},
"source": "https://example.com",
"purchase": {
"reference": "ORDER-12345",
"amount": 2500,
"currency": "EUR",
"payer_sets_amount": false,
"minimum_amount": null,
"maximum_amount": null,
"suggested_amount": null,
"amount_buttons": []
},
"tips_enabled": false
}
For the payer-set example above, the response returns "amount": null, "payer_sets_amount": true and the limits, suggested amount and buttons as sent.
Next Steps​
After creating an order, create a payment link to generate a URL where customers can complete the payment.
AUTHORIZATION: HTTP
REQUEST
RESPONSE
{
"project_id": "b7c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
"order_id": "a6f2b8e3-5e5f-47d9-b13f-87ed2db2938a",
"created_at": 1736433270,
"merchant_data": {
"key1": "value1",
"key2": "value2"
},
"source": "https://example.com",
"purchase": {
"reference": "ORDER-12345",
"amount": 2500,
"currency": "EUR",
"payer_sets_amount": false,
"minimum_amount": null,
"maximum_amount": null,
"suggested_amount": null,
"amount_buttons": []
},
"tips_enabled": false
}