Skip to main content

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​

FieldTypeRequiredDescription
project_idstring (UUID)Your merchant project ID (defaults to the project from your JWT token)
redirect_urls.success_urlstringURL to redirect customer after successful payment
redirect_urls.failure_urlstringURL to redirect customer after failed payment
redirect_urls.callback_urlstringWebhook URL for payment notifications (omit and you receive no webhooks)
redirect_urls.cancel_urlstringURL to redirect customer when the payment is canceled
purchase.referencestring✓Your unique order reference (e.g., order ID in your system)
purchase.amountinteger✓ (unless payer_sets_amount)Amount in minor units (e.g., 2500 for €25.00). Omit it when purchase.payer_sets_amount is true
purchase.currencystring✓ISO 4217 currency code (e.g., EUR)
purchase.payer_sets_amountbooleantrue 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_amountintegerLowest amount the payer may enter, in minor units. Only with payer_sets_amount; at least 1. Omitted: the floor of 1 applies
purchase.maximum_amountintegerHighest 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_amountintegerAmount 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_buttonsarray of integersThree 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_enabledbooleantrue 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
splitsarrayPer-order entries for the project's split policy. Required when the policy has a variadic slot. See Split Payments.
splits[].typestring✓ (when splits present)variadic (the per-order recipient for the policy's variadic slot) or tip (an extra tip recipient)
splits[].beneficiary_idstringone ofId of the registered beneficiary to pay (UUID). 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_idstringVariadic slot to bind to. Required only when the policy has more than one variadic slot; ignored for tips
split_overridesobjectPer-order restatement of the whole split policy. Accepts a recipient account directly (no registration). Requires per-order overrides enabled. See Per-order rule overrides.
metadataobjectKey-value metadata. Include referrer (your site URL) for origin verification. An integration partner may report itself with tpi_id — see Report integration partner
Amount Format

All amounts use minor currency units (e.g., cents for EUR). The amount 2500 represents €25.00.

Response​

FieldTypeDescription
project_idstring (UUID)Project identifier associated with the order
order_idstring (UUID)Unique order identifier
created_atintegerCreation timestamp in UTC timezone
merchant_dataobjectKey-value merchant data attached to the order
sourcestringSource indicating where this order originated from
purchase.referencestringUnique identifier for the order in the merchant system
purchase.amountinteger | nullOrder amount in minor currency units (cents), returned as an integer. null when the payer sets the amount
purchase.currencystringCurrency code in ISO 4217 format
purchase.payer_sets_amountbooleanWhether the payer enters the amount
purchase.minimum_amountinteger | nullMinimum as you sent it; null when omitted
purchase.maximum_amountinteger | nullMaximum as you sent it; null when omitted
purchase.suggested_amountinteger | nullSuggested amount; null when not set
purchase.amount_buttonsarray of integersAmount buttons in the order sent; [] when not set
tips_enabledbooleanWhether 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

Base URL
https://api.paysera.com

RESPONSE

Order created successfully
{
"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
}