Skip to main content

API Reference

Complete reference of all Paysera Checkout integration endpoints.

Interactive API Reference​

For detailed endpoint documentation with request/response examples, see the Endpoint Reference section under API Integration:

OpenAPI Specification​

Download the complete API specification:

Download OpenAPI Spec (YAML)

Use with Postman, Insomnia, or Swagger Editor for interactive exploration.

Base URL​

https://api.paysera.com

Authentication​

All endpoints require OAuth2 Bearer token authentication:

Authorization: Bearer YOUR_ACCESS_TOKEN

See Authentication for details on obtaining tokens.


Orders API​

Base path: /merchant-order/integration/v1

Create Order​

Creates a new payment order.

POST /merchant-order/integration/v1/orders

Request Body:

FieldTypeRequiredDescription
project_idstring (UUID)NoYour merchant project ID. Defaults to the project from your JWT token.
redirect_urls.success_urlstringNoURL to redirect on successful payment
redirect_urls.failure_urlstringNoURL to redirect on failed payment
redirect_urls.callback_urlstringNoBackend URL to receive webhook notifications
purchase.referencestringYesYour unique order reference in the merchant system
purchase.amountintegerYes*Amount in minor units (e.g., 14999 for €149.99). *Omit it when purchase.payer_sets_amount is true
purchase.currencystringYesISO 4217 currency code
purchase.payer_sets_amountbooleanNotrue lets the payer enter the amount (default false). See Let the payer set the amount
purchase.minimum_amount / purchase.maximum_amountintegerNoPayer-set limits in minor units; only with payer_sets_amount: true
purchase.suggested_amountintegerNoAmount prefilled for the payer; only with payer_sets_amount: true
purchase.amount_buttonsarray<integer>NoThree or four one-tap amounts; only with payer_sets_amount: true
tips_enabledbooleanNoOffer the payer a tip on top of the fixed amount (default false). See Tips
sourcestringNoWhere the order originated (URL or identifier). Defaults to Integration.
metadataobjectNoAdditional key-value pairs (each key/value max 255 chars). An integration partner reports itself with tpi_id; see Report integration partner.
merchant_dataobjectNoMerchant data key-value pairs (each key/value max 255 chars)
splitsarrayNoPer-order split entries — variadic slot fills and/or payer tips, referencing registered beneficiaries by beneficiary_id or declaring them inline. See Split payments.
split_overridesobjectNoPer-order restatement of the whole split policy (requires per-order overrides enabled). See Per-order rule overrides.

Response: 201 Created

FieldTypeDescription
order_idstring (UUID)Unique order identifier
project_idstring (UUID)Project identifier associated with the order
created_atintegerCreation Unix timestamp (UTC)
sourcestringSource indicating where the order originated
merchant_dataobjectMerchant data key-value pairs (if provided in request)
purchase.referencestringYour order reference
purchase.amountinteger | nullAmount in minor units; null on a payer-set order
purchase.currencystringCurrency code
purchase.payer_sets_amountbooleanWhether the payer enters the amount
purchase.minimum_amount / purchase.maximum_amountinteger | nullPayer-set limits as sent; null when not set
purchase.suggested_amountinteger | nullSuggested amount as sent
purchase.amount_buttonsarray<integer>Amount buttons as sent; [] when none
tips_enabledbooleanWhether the order offers a tip

Base path: /checkout-payment-link/integration/v1

Creates a payment link for an existing order.

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

Request Body:

FieldTypeRequiredDescription
order_idstring (UUID)YesThe associated order ID
namestringYesDescriptive name for the payment link (max 255 chars)
purchase.amountintegerYes*Amount in minor currency units (e.g., cents). *Omit it for a payer-set order; the link takes the amount rules from the order
purchase.suggested_amount / purchase.amount_buttonsinteger / array<integer>NoPayer-set orders only: override the order's suggested amount and buttons for this link. See Payer-set amount links
experience.languagestringYesUI language, 2-letter ISO 639-1 code (e.g., en, lt)
experience.payment_flowstringNoPayment flow type. Defaults to paysera_checkout. direct_payment requires payment_details.key and payment_details.country_code; without country_code the link opens the Paysera checkout page instead.
lifetimeintegerNoLink validity in seconds. Default 259200 (3 days). 0 = never expires.
payment_details.keystringYes, with direct_paymentPayment method key (e.g., card-payment). 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; omit it to get the generated default. See Payment purpose
payment_details.country_codestringFor direct_paymentCountry code, ISO 3166-1 alpha-2 (e.g., LT). 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_information.namestringNoPayer name (max 150 chars)
payer_information.emailstringNoPayer email
metadataobjectNoAdditional key-value metadata

Response: 201 Created

FieldTypeDescription
link_idstring (UUID)Unique payment link ID
order_idstring (UUID)Associated order ID
payment_URLstringPayment URL to redirect the customer to
experience.languagestringSelected language
experience.payment_flowstringPayment flow type
payment_details.keystringPayment method key (if specified)
payment_details.purposestringThe purpose you sent, echoed back — null if you omitted it. See Payment purpose
payment_details.country_codestringCountry code (if specified)
payer_information.namestringPayer name (if specified)
payer_information.emailstringPayer email (if specified)
purchase.amountinteger | nullAmount in minor units; null on a payer-set link until the payer enters one
purchase.payer_sets_amountbooleanWhether the payer enters the amount
purchase.minimum_amount / purchase.maximum_amount / purchase.suggested_amountinteger | nullPayer-set limits and suggested amount the link applies
purchase.amount_buttonsarray<integer>Amount buttons the link shows; [] when none
created_atintegerCreation Unix timestamp (UTC)
expired_atintegerExpiration Unix timestamp (UTC)
note

The response field payment_URL uses mixed case as documented.


Payment Methods API​

Base path: /checkout-project/integration/v1

Get Available Payment Methods​

Retrieves available payment methods for your project.

GET /checkout-project/integration/v1/methods

Query Parameters:

ParameterTypeRequiredDescription
amountintegerNoFilter by transaction amount (minor units)
currencystringNoFilter by currency (ISO 4217)
payer_countrystringNoPayer country (ISO 3166-1 alpha-2). A method that has payer countries is listed only when this country is enabled for it and the amount fits this country's limits; available_countries then holds only this country.
note

Filtering by limits only applies when both amount and currency are provided. payer_country is separate and optional: without it, each method lists every country whose limits accept the amount. Each method returns its limits as min_amount / max_amount.

Response: 200 OK

{
"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 }
},
"display_order": null,
"display_order_group": null,
"min_amount": { "amount": 1, "currency": "EUR" },
"max_amount": { "amount": 1500000, "currency": "EUR" }
}
]
}
FieldTypeDescription
items[].keystring | nullUnique identifier for the payment method
items[].titlestringDisplay name of the payment method
items[].descriptionstring | nullDetailed description of the payment method
items[].typestringMethod type: pis, card, wallet, banklink or bnpl. Today's catalogue uses only pis, card and bnpl.
items[].flowstringFlow: redirect, decoupled or direct. Every method currently uses redirect.
items[].available_countriesarray<string>ISO 3166-1 alpha-2 country codes. An empty array means no payer-country restriction.
items[].available_currenciesobjectMap of currency code → { main: boolean }
items[].logo_urlstring | nullURL of the icon variant of the logo, a 48 px disc
items[].logo_wide_urlstring | nullURL of the wide variant, the wordmark for wide slots
items[].display_orderinteger | nullPosition in the default ordering; null means unranked
items[].display_order_groupinteger | nullDisplay group the method belongs to
items[].min_amount / items[].max_amountobject | nullThe method's limits as { amount, currency } in minor units, for payer_country when given; null when there is no limit. See Get payment methods

Common Response Codes​

CodeDescription
200Success
201Created
400Bad Request - Invalid parameters
401Unauthorized - Invalid or expired token
403Forbidden - Insufficient permissions
404Not Found - Resource doesn't exist
409Conflict - Resource already exists
422Unprocessable Entity - Validation error
429Too Many Requests - Rate limit exceeded
500Internal Server Error

Error Response Format​

Simple error response:

{
"error": "error_code",
"error_description": "Human-readable description"
}

Validation error response (per-field details):

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