openapi: 3.0.1 info: title: Paysera Checkout Integration API description: API reference for Paysera Checkout integration endpoints. Use these endpoints to create payment orders, generate payment links, and query available payment methods. version: 1.0.0 contact: name: Paysera Technical Support email: tech_support@paysera.com servers: - url: https://api.paysera.com description: Production security: - BearerAuth: [] tags: - name: Integration Project Management description: Integration Project Management x-displayName: Integration Project Management - name: Integration payment links description: Integration API endpoints for managing payment links x-displayName: Integration payment links - name: Integration Order Management description: API endpoints for managing orders x-displayName: Integration Order Management paths: /checkout-project/integration/v1/methods: get: tags: - Integration Project Management summary: Get Available Payment Methods description: Retrieve all available payment methods for a project. The response includes details about each payment method, such as its key, title, description, type, flow, and the countries where it is available. Optional filtering by transaction amount and currency - when both parameters are provided, only payment methods whose limits encompass the specified amount will be returned. operationId: getPaymentMethods parameters: - name: amount in: query description: Transaction amount for filtering payment methods by limits. Filtering is only applied when both amount and currency are provided. If omitted, all payment methods are returned without limit filtering. required: false schema: type: integer example: 1000 example: 5000 - name: currency in: query description: Transaction currency code (ISO 4217) for filtering payment methods by limits. Filtering is only applied when both amount and currency are provided. If omitted, all payment methods are returned without limit filtering. required: false schema: type: string maxLength: 3 minLength: 3 example: EUR example: EUR - name: payer_country in: query description: Payer country code (ISO 3166-1 alpha-2). When provided, a method that has payer countries is listed only when this country is enabled for it and the amount fits this country's limits (its override, else the global limits), and available_countries holds only this country. If omitted, each method lists every country whose limits accept the amount. required: false schema: type: string maxLength: 2 minLength: 2 example: LT example: LT responses: '200': description: Available payment methods successfully retrieved content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_GetAvailablePaymentMethodsResponse' example: 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 logo_url: https://api.paysera.com/checkout-engine/public/v1/assets/payment-method/swedbank/logo logo_wide_url: https://api.paysera.com/checkout-engine/public/v1/assets/payment-method/swedbank/logo/wide display_order: null display_order_group: null min_amount: amount: 1 currency: EUR max_amount: amount: 1500000 currency: EUR - key: revolut title: Revolut description: Pay via Revolut type: pis flow: redirect available_countries: [AT, BE, BG, CY, CZ, DE] available_currencies: EUR: main: true logo_url: https://api.paysera.com/checkout-engine/public/v1/assets/payment-method/revolut/logo logo_wide_url: https://api.paysera.com/checkout-engine/public/v1/assets/payment-method/revolut/logo/wide display_order: 5 display_order_group: null min_amount: null max_amount: null '401': description: Unauthorized - Authentication required content: application/json: schema: properties: error: type: string example: unauthorized error_description: type: string example: Authentication required type: object example: error: unauthorized error_description: Authentication required '404': description: Resource not found content: application/json: schema: properties: error: type: string example: not_found error_description: type: string example: Project not found or no payment methods available type: object example: error: not_found error_description: Project not found or no payment methods available /checkout-project/integration/v1/split-beneficiaries: post: tags: - Integration Project Management summary: Register a split beneficiary description: | Register a recipient that order splits can reference by id. The recipient is identified by IBAN; whether it is a Paysera account or an external bank account is resolved server-side and returned as `destination_type`. An external IBAN is only accepted when external beneficiaries are enabled for the project, and the IBAN must not resolve to the project owner's own account. The returned `id` is the `beneficiary_id` used in order `splits[]`. operationId: createSplitBeneficiary requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_CreateSplitBeneficiaryRequest' responses: '201': description: Beneficiary registered content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_SplitBeneficiaryResponse' example: id: 550e8400-e29b-41d4-a716-446655440000 destination_type: paysera_account account_number: EVP5210018145214 name: Marketplace Seller 42 created_at: 1716200000 '400': description: | Invalid input — `invalid_properties` (field validation; details in `error_properties`) or `invalid_request` (malformed JSON, or an external IBAN that is not an EEA SEPA IBAN: "Only EEA SEPA IBANs are accepted"). The EEA check runs only on a project that accepts external IBANs; on any other project a non-EEA IBAN gets `422` instead. content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse' example: error: invalid_properties error_description: Validation failed error_properties: iban: - This value is not a valid IBAN. '401': description: Unauthorized - Authentication required content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse' example: error: unauthorized error_description: Authentication required '409': description: A beneficiary with this account already exists for the project content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse' example: error: conflict error_description: A beneficiary with this account already exists '422': description: | The request is well-formed but cannot be fulfilled — returned as `unprocessable_entity` with the reason in `error_description` (for example: split beneficiaries not enabled for the project, the IBAN belongs to the project owner, the IBAN is an external account but external beneficiaries are not enabled for the project, external beneficiaries are not allowed because payer tips are enabled, or the Paysera account behind the IBAN is inactive or closed). These checks run before the EEA check, so on a project that does not accept external IBANs a non-EEA IBAN gets `422`, not `400`. content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse' example: error: unprocessable_entity error_description: Split beneficiaries are not enabled for this project get: tags: - Integration Project Management summary: List split beneficiaries description: | List the project's registered split beneficiaries (cursor-paginated). The merchant's own self-row is included with a `null` id and cannot be referenced in order splits. operationId: getSplitBeneficiaries parameters: - name: after in: query required: false description: Cursor for the next page. Mutually exclusive with `before`. schema: type: string - name: before in: query required: false description: Cursor for the previous page. Mutually exclusive with `after`. schema: type: string - name: order_direction in: query required: false description: Sort direction by creation time. schema: type: string enum: - asc - desc default: desc - name: include_total in: query required: false description: Include the total count in `_metadata.total`. schema: type: boolean default: false - name: size in: query required: false description: Page size. schema: type: integer minimum: 1 maximum: 1000 responses: '200': description: Beneficiaries retrieved content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_SplitBeneficiaryListResponse' example: items: - id: 550e8400-e29b-41d4-a716-446655440000 destination_type: paysera_account account_number: EVP5210018145214 bic: null name: Marketplace Seller 42 created_at: 1716200000 consent_status: null _metadata: has_next: false has_previous: false cursors: after: null before: null total: 1 '400': description: Invalid query parameters (`invalid_properties`) content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse' example: error: invalid_properties error_description: Validation failed '401': description: Unauthorized - Authentication required content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse' example: error: unauthorized error_description: Authentication required /checkout-project/integration/v1/split-beneficiaries/by-phone: post: tags: - Integration Project Management summary: Register a split beneficiary by phone description: | Register a tip recipient by the phone number of their Paysera account. The person must already have a Paysera individual account registered to that phone number. Available only on projects with payer tips enabled. For Lithuanian merchants the returned `account_number` is `null`: the recipient's payout account is assigned later, when they give tax-agent consent. For other merchants the recipient's Paysera account is assigned immediately. operationId: createSplitBeneficiaryByPhone requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_CreateSplitBeneficiaryByPhoneRequest' responses: '201': description: Beneficiary registered content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_SplitBeneficiaryByPhoneResponse' example: id: 550e8400-e29b-41d4-a716-446655440000 name: John D. account_number: null created_at: 1716200000 '400': description: | Invalid input — `invalid_properties` (missing, malformed, too short or too long phone number) or `invalid_request` (malformed JSON). content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse' example: error: invalid_properties error_description: Validation failed error_properties: phone: - This value is not a valid phone number. '401': description: Unauthorized - Authentication required content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse' example: error: unauthorized error_description: Authentication required '409': description: | A beneficiary for this person already exists for the project (duplicates are detected by the Paysera user the phone number resolves to). content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse' example: error: conflict error_description: A split beneficiary already exists for this project (Tip recipients) '422': description: | `unprocessable_entity` — payer tips are not enabled for the project, or no Paysera individual account was found for this phone number. content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse' example: error: unprocessable_entity error_description: No Paysera individual was found for this phone number /checkout-project/integration/v1/split-beneficiaries/{beneficiaryId}: delete: tags: - Integration Project Management summary: Delete a split beneficiary description: | Remove a registered beneficiary. Fails if the beneficiary is still referenced by the project's split policy. operationId: deleteSplitBeneficiary parameters: - name: beneficiaryId in: path required: true description: Id of the beneficiary to delete. schema: type: string format: uuid responses: '204': description: Beneficiary deleted (no content) '400': description: The `beneficiaryId` path parameter is not a valid UUID (`invalid_properties`). content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse' example: error: invalid_properties error_description: Validation failed '401': description: Unauthorized - Authentication required content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse' example: error: unauthorized error_description: Authentication required '404': description: Beneficiary not found for this project content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse' example: error: not_found error_description: Split beneficiary not found '409': description: | The beneficiary is still referenced by the split policy. `error_properties.referenced_by_slot_positions` lists the policy slot positions that reference it. content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse' example: error: conflict error_description: Beneficiary is referenced by the split policy error_properties: referenced_by_slot_positions: - '1' '422': description: | `unprocessable_entity` — split beneficiaries not enabled, or attempting to delete the merchant's own self-row. content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse' example: error: unprocessable_entity error_description: The merchant's own beneficiary cannot be deleted /checkout-project/integration/v1/project/split-policy: get: tags: - Integration Project Management summary: Get the project split policy description: | Read the project's split-policy template — each slot's `slot_id`, role, and configured rule. Use the `slot_id`s to bind variadic order entries and to build per-order overrides. operationId: getSplitPolicy responses: '200': description: Split policy retrieved content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_ProjectSplitPolicyResponse' example: project_id: b7c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e configured: true slots: - slot_id: 11111111-1111-1111-1111-111111111111 position: 0 role: merchant rule_type: percentage value: 1000 beneficiary_id: null beneficiary_account_number: null beneficiary_name: null beneficiary_missing: false - slot_id: 22222222-2222-2222-2222-222222222222 position: 1 role: variadic rule_type: remainder value: null beneficiary_id: null beneficiary_account_number: null beneficiary_name: null beneficiary_missing: false '401': description: Unauthorized - Authentication required content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse' example: error: unauthorized error_description: Authentication required '404': description: The project has no split-policy template content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse' example: error: not_found error_description: Split policy not found /checkout-project/integration/v1/project/integrator-id: post: tags: - Integration Project Management summary: Report the integration partner description: | Tell Paysera which integration partner the calling project belongs to, so projects brought by a platform can be identified, supported and counted. The project is taken from the `project_id` claim of the token, so the call carries no project in its path. Only an active registered identifier is accepted. The last partner to report wins, so a merchant that moves from one platform to another is re-attributed by the new one. An attribution set by Paysera support is a lock and is never overwritten here. operationId: setIntegratorId requestBody: required: true content: application/json: schema: type: object required: - tpi_id properties: tpi_id: type: string description: Integration partner identifier issued to the partner on registration example: hostinger example: tpi_id: hostinger responses: '200': description: Integration partner set on the project content: application/json: schema: type: object properties: project_id: type: string format: uuid description: Project the integration partner was set on tpi_id: type: string nullable: true description: Integration partner now attributed to the project set_at: type: integer format: int64 nullable: true description: Unix timestamp of the moment the current value was set example: project_id: b7c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e tpi_id: hostinger set_at: 1756900000 '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse' example: error: invalid_request error_description: Integration partner id is required '401': description: Unauthorized - Authentication required content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse' example: error: unauthorized error_description: Authentication required '404': description: No active partner is registered under this identifier content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse' example: error: not_found error_description: Integration partner with TPI ID "hostinger" not found '409': description: Attribution is set by Paysera support and cannot be changed here content: application/json: schema: $ref: '#/components/schemas/Checkout_Merchant_Project_API_ErrorResponse' example: error: conflict error_description: The integration partner of this project is set by Paysera support and cannot be changed here /checkout-payment-link/integration/v1/payment-links: post: tags: - Integration payment links summary: Create a new payment link via integration description: "\n Creates a new payment link with the provided details\ \ through the integration API.\n A unique payment link will be\ \ generated and returned in the response.\n " operationId: createPaymentLink parameters: - name: Accept-Language in: header description: Preferred language for the response required: false schema: type: string enum: - en - lt requestBody: content: application/json: schema: $ref: '#/components/schemas/Checkout_Payment_Link_API_CreatePaymentLinkIntegrationRequest' required: true responses: '201': description: Payment link created successfully content: application/json: schema: $ref: '#/components/schemas/Checkout_Payment_Link_API_CreatePaymentLinkIntegrationResponse' example: 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 payment_details: key: null purpose: Order #12345 - Leather Wallet country_code: LT purchase: amount: 2500 payer_sets_amount: false minimum_amount: null maximum_amount: null suggested_amount: null amount_buttons: [] payer_information: name: John Doe email: john@example.com expired_at: 1736436870 created_at: 1736433270 '400': description: | Invalid input. When the underlying order has splits, the link must not expire — passing a non-zero `lifetime` is rejected with `validation_split_expiration_not_allowed`. For a split order the link amount must also equal the order's full amount; a mismatch is rejected with `validation_split_amount_mismatch`. When the order lets the payer set the amount: `payer_set_amount_with_amount` (omit `purchase.amount`), `validation_direct_payment_with_payer_set_amount` (`payment_flow: direct_payment` is not available), `suggested_amount_out_of_limits`, `amount_buttons_count`, `amount_buttons_not_ascending` and `amount_buttons_out_of_limits`. On a fixed-amount order, `suggested_amount_without_payer_set` and `amount_buttons_without_payer_set`; a missing `purchase.amount` is an `invalid_properties` error on `purchase.amount`. `payment_flow: direct_payment` is not available for an order that offers tips: `validation_direct_payment_with_tips` when the order has `tips_enabled: true` (unless it was created with a split configuration or `tokenization` before those combinations were refused, where the flag has no effect), `validation_direct_payment_with_tip_rule` when it has a `tip` split. Use the default `paysera_checkout` flow for those orders. A `direct_payment` link without a non-empty `payment_details.key` is rejected with `validation_payment_method_required`. A missing `payment_details.country_code` is not an error: the link opens the Paysera checkout page instead. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Checkout_Payment_Link_API_ValidationErrorResponse' - $ref: '#/components/schemas/Checkout_Payment_Link_API_SimpleErrorResponse' example: error: invalid_properties error_description: One or more fields failed validation error_properties: purchase.amount: - This value should be greater than 0 '401': description: Unauthorized - Invalid or missing API credentials content: application/json: schema: $ref: '#/components/schemas/Checkout_Payment_Link_API_SimpleErrorResponse' example: error: unauthorized error_description: Authentication is required to access this resource '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/Checkout_Payment_Link_API_SimpleErrorResponse' example: error: not_found error_description: Payment link not found '409': description: | A payment link with this name already exists for the order (`validation_duplicate_name`). content: application/json: schema: $ref: '#/components/schemas/Checkout_Payment_Link_API_SimpleErrorResponse' example: error: validation_duplicate_name error_description: A payment link with this name already exists /merchant-order/integration/v1/orders: post: tags: - Integration Order Management summary: Create a new order description: "\n Creates a new order with the provided details.\n\ \ The order will be initialized in 'collecting-funds' status.\n\ \ A unique order ID will be generated and returned in the response.\n\ \ " operationId: createOrder parameters: - name: Accept-Language in: header description: 'Preferred language for the response. Supported values: ''en'' (English) and ''lt'' (Lithuanian)' required: false schema: type: string enum: - en - lt default: en requestBody: content: application/json: schema: $ref: '#/components/schemas/Merchant_Order_API_IntegrationCreateOrderRequest' required: true responses: '201': description: Order created successfully content: application/json: schema: $ref: '#/components/schemas/Merchant_Order_API_IntegrationCreateOrderResponse' example: 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 '400': description: | Invalid input. For orders with `splits`, request-validation problems return `400` — e.g. `intermediary_account_required` (the project is not configured for splits) or `invalid_properties` (an entry's `type` is not `variadic` or `tip`). Policy and beneficiary conflicts return `422`. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Merchant_Order_API_ValidationErrorResponse' - $ref: '#/components/schemas/Merchant_Order_API_SimpleErrorResponse' example: error: invalid_properties error_description: One or more fields failed validation error_properties: purchase.amount: - This value should be a positive whole number '401': description: Unauthorized - Invalid or missing API credentials content: application/json: schema: $ref: '#/components/schemas/Merchant_Order_API_SimpleErrorResponse' example: error: unauthorized error_description: Authentication is required to access this resource '422': description: | Split validation error. The `error` field identifies the specific problem. Common split-related codes: * `policy_not_configured` — the policy template has unfilled slots * `policy_invalid` — the project's split policy is invalid * `variadic_entry_required` — the policy expects a variadic entry * `variadic_entry_not_allowed` — the policy has no variadic slot but one was sent * `variadic_entry_requires_policy` — a variadic entry was sent but the project has no split policy * `split_variadic_count_mismatch` — the number of variadic entries doesn't match the policy * `tip_entries_without_tips_enabled` — tip entries sent but payer tips through Split Payments are not enabled on the project * `split_variadic_slot_id_required` / `_unknown` / `_duplicate` — variadic `slot_id` binding problems * `variadic_beneficiary_required` / `tip_beneficiary_required` — an entry names no recipient * `split_entry_identifier_invalid` — an entry sets both `beneficiary_id` and `beneficiary` * `tip_beneficiary_consent_not_given` — the tip recipient has a payout account but no tax-agent consent, e.g. withdrew it (LT) * `inline_beneficiary_not_allowed_for_tip` — an inline `beneficiary` on a `tip` entry, on a project under the tax-agent consent regime * `inline_beneficiary_rejected` — the inline beneficiary was refused registration; `error_properties.rule` carries the stable reason key * `split_beneficiary_not_found` — a `beneficiary_id` is not registered for the project, or is an LT tip recipient who has not given tax-agent consent yet * `split_beneficiary_account_not_found` — a resolved EVP account does not exist * `split_amount_too_low` — order amount is below the minimum the policy needs to settle * `splits_invalid` — the resulting split configuration is invalid Per-order override (`split_overrides`) codes: * `overrides_not_enabled` — per-order overrides are not enabled on the project * `split_overrides_require_policy` — overrides sent but the project has no policy * `split_overrides_incomplete` / `split_override_unknown_slot` / `split_override_duplicate_slot` — slot restatement problems * `split_override_duplicate_recipient` — the same recipient appears more than once (variable split recipients only) * `split_override_recipient_required` / `_not_allowed` / `_invalid` / `_ambiguous` — per-slot recipient problems (`_ambiguous`: more than one of `beneficiary_id` / `account` / `beneficiary` set) * `split_override_account_not_resolvable` — `account` is not a Paysera account; use an inline `beneficiary` or a registered `beneficiary_id` instead * `split_override_value_invalid` — value invalid for the slot's rule type * `split_override_variadic_entry_not_allowed` — a `variadic` entry was sent in `splits` alongside overrides * `split_remainder_required` / `split_too_many_remainders` / `split_percentage_sum_exceeded` — aggregate rule violations Payer-set amount codes (`purchase.payer_sets_amount` and its fields): * `payer_set_amount_not_enabled` — payer-set amount is not switched on for the project under Features * `payer_set_amount_with_split_payments` — the project has split payments, or the order sends `splits` / `split_overrides` * `payer_set_amount_with_amount` — `purchase.amount` sent together with `payer_sets_amount` * `payer_set_amount_limits_without_flag` — `minimum_amount` / `maximum_amount` sent without `payer_sets_amount` * `minimum_amount_below_floor` — `minimum_amount` below 1 * `maximum_amount_above_platform_maximum` — `maximum_amount` above 1000000 * `minimum_amount_not_below_maximum` — the minimum is not lower than the maximum * `suggested_amount_without_payer_set` / `amount_buttons_without_payer_set` — sent without `payer_sets_amount` * `suggested_amount_out_of_limits` — `suggested_amount` outside the limits * `amount_buttons_count` — not three or four `amount_buttons` * `amount_buttons_not_ascending` — `amount_buttons` not unique and strictly ascending * `amount_buttons_out_of_limits` — a button outside the limits Tip codes (`tips_enabled`): * `tips_and_payer_set_amount_conflict` — `tips_enabled` together with `payer_sets_amount` * `tips_not_enabled` — tips are not switched on for the project under Features * `tips_with_split_payments` — `tips_enabled` on a project with split payments * `tips_and_tokenization_conflict` — `tips_enabled` together with `tokenization` content: application/json: schema: $ref: '#/components/schemas/Merchant_Order_API_SimpleErrorResponse' example: error: variadic_entry_required error_description: The configured split policy requires exactly one variadic entry. /merchant-order/integration/v1/orders/{id}: get: tags: - Integration Order Management summary: Get an order by id description: | Retrieves a single order by its identifier. The order is scoped to the project associated with the token — attempts to access an order from another project return a 403 response. operationId: getOrderById parameters: - name: id in: path description: Order identifier required: true schema: type: string format: uuid responses: '200': description: Order retrieved successfully content: application/json: schema: $ref: '#/components/schemas/Merchant_Order_API_IntegrationGetOrderByIdResponse' example: id: a6f2b8e3-5e5f-47d9-b13f-87ed2db2938a project_id: b7c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e amount: 2500 currency: EUR status: canceled reference: ORDER-12345 callback_url: https://example.com/webhook success_url: https://example.com/success fail_url: https://example.com/failure cancel_url: https://example.com/cancel source: https://example.com created_at: 1736433000 updated_at: 1736433600 amount_paid: 0 balance_due: 2500 merchant_data: key1: value1 split_config_id: null checkout_flow: null cancel_reason: canceled_by_merchant payer_sets_amount: false minimum_amount: null maximum_amount: null suggested_amount: null amount_buttons: [] payment_accepted_at: null tips_enabled: false tip_amount: null order_template: null payer_text: null '400': description: Invalid input content: application/json: schema: oneOf: - $ref: '#/components/schemas/Merchant_Order_API_ValidationErrorResponse' - $ref: '#/components/schemas/Merchant_Order_API_SimpleErrorResponse' '401': description: Unauthorized - Invalid or missing API credentials content: application/json: schema: $ref: '#/components/schemas/Merchant_Order_API_SimpleErrorResponse' example: error: unauthorized error_description: Authentication is required to access this resource '403': description: Forbidden - Order belongs to a different project content: application/json: schema: $ref: '#/components/schemas/Merchant_Order_API_SimpleErrorResponse' '404': description: Order not found content: application/json: schema: $ref: '#/components/schemas/Merchant_Order_API_SimpleErrorResponse' components: schemas: Checkout_Merchant_Project_API_GetAvailablePaymentMethodsResponse: required: - items properties: items: description: List of available payment methods type: array items: $ref: '#/components/schemas/Checkout_Merchant_Project_API_GetAvailablePaymentMethodResponse' type: object Checkout_Merchant_Project_API_GetAvailablePaymentMethodResponse: required: - title - type - flow - available_countries - available_currencies properties: key: description: Unique identifier for the payment method type: string example: swedbank nullable: true title: description: Display name of the payment method type: string example: Credit/Debit Card description: description: Detailed description of the payment method type: string example: Pay via credit or debit card. nullable: true type: description: Type of payment method. The catalogue currently returns only pis, card and bnpl, but clients should accept the full set. type: string enum: - pis - card - wallet - banklink - bnpl example: card flow: description: Flow type. Every method currently uses redirect. type: string enum: - redirect - decoupled - direct example: redirect available_countries: description: List of country codes where this payment method is available. An empty array means the method has no payer-country restriction. type: array items: type: string example: - EE - LT - LV available_currencies: description: Available currencies configuration for this payment method, keyed by ISO 4217 currency code type: object example: EUR: main: true additionalProperties: type: object properties: main: description: Marks the primary currency for this payment method type: boolean example: true logo_url: description: URL of the icon variant of the payment method logo, a 48 px disc type: string nullable: true example: https://api.paysera.com/checkout-engine/public/v1/assets/payment-method/swedbank/logo logo_wide_url: description: URL of the wide variant of the payment method logo, the wordmark for wide slots type: string nullable: true example: https://api.paysera.com/checkout-engine/public/v1/assets/payment-method/swedbank/logo/wide display_order: description: Position in the default ordering. Null means unranked - unranked methods follow the ranked ones, sorted by name. type: integer nullable: true example: 5 display_order_group: description: Display group the method belongs to. Methods sharing a group are meant to be rendered as one block. type: integer nullable: true example: 2 min_amount: description: Lowest amount the method accepts, in the transaction limit currency - for the payer_country when given, else the lowest minimum of the listed countries (the global minimum for a method without payer countries). Null when there is no minimum. allOf: - $ref: '#/components/schemas/Checkout_Merchant_Project_API_PaymentMethodLimitAmount' nullable: true max_amount: description: Highest amount the method accepts, in the transaction limit currency - for the payer_country when given, else the highest maximum of the listed countries (the global maximum for a method without payer countries). Null when there is no maximum. allOf: - $ref: '#/components/schemas/Checkout_Merchant_Project_API_PaymentMethodLimitAmount' nullable: true type: object Checkout_Merchant_Project_API_PaymentMethodLimitAmount: required: - amount - currency type: object properties: amount: type: integer format: int64 description: Amount in minor units example: 500000 currency: type: string description: Currency code (ISO 4217) the method limits are held in example: EUR Checkout_Payment_Link_API_ValidationErrorResponse: required: - error - error_description - error_properties type: object properties: error_properties: type: object additionalProperties: type: array items: type: string error_description: type: string error: type: string Checkout_Payment_Link_API_SimpleErrorResponse: required: - error - error_description type: object properties: error: type: string error_description: type: string Checkout_Payment_Link_API_CreatePaymentLinkIntegrationRequest: required: - experience - name - order_id - purchase type: object properties: name: maxLength: 255 minLength: 0 type: string description: Descriptive name for the payment link example: April Invoice Payment lifetime: maximum: 86313600 minimum: 0 type: integer description: | The lifetime of the link in seconds. If omitted, the default value 259200 (3 days) is used. If value is 0, the link never expires. **Must be `0` if the underlying order has splits** — otherwise the request is rejected with `validation_split_expiration_not_allowed`. format: int64 example: 3600 experience: $ref: '#/components/schemas/Checkout_Payment_Link_API_ExperienceDto' payment_details: $ref: '#/components/schemas/Checkout_Payment_Link_API_PaymentDetailsDto' purchase: $ref: '#/components/schemas/Checkout_Payment_Link_API_PurchaseDto' payer_information: $ref: '#/components/schemas/Checkout_Payment_Link_API_PayerInformationDto' order_id: type: string description: An reference ID for the associated order. format: uuid example: a6f2b8e3-5e5f-47d9-b13f-87ed2db2938a metadata: type: object additionalProperties: type: string description: Additional metadata key-value pairs example: '{"referrer":"https://paysera.net"}' description: Additional metadata key-value pairs example: referrer: https://paysera.net description: Request for integration payment link creation Checkout_Payment_Link_API_ExperienceDto: required: - language type: object properties: language: minLength: 1 pattern: ^[a-z]{2}$ type: string description: The language of the payment link, selected from the project's description languages example: en payment_flow: type: string description: | Payment flow type - can be null for default flow. `direct_payment` requires `payment_details.key` and `payment_details.country_code`. A `direct_payment` link without `country_code` opens the Paysera checkout page instead, where the payer selects the country and payment method. nullable: true enum: - paysera_checkout - direct_payment example: paysera_checkout default: paysera_checkout description: Payment experience configuration Checkout_Payment_Link_API_PayerInformationDto: type: object properties: name: maxLength: 150 minLength: 0 type: string description: Payer name example: John Doe email: type: string description: Payer email. Required if the payment link is personalized example: customer@example.com description: Payer information Checkout_Payment_Link_API_PaymentDetailsDto: type: object properties: key: type: string description: >- Payment method key. 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). example: card-payment purpose: maxLength: 255 minLength: 0 type: string description: >- Payment purpose description. Used verbatim as the payer-facing payment purpose, truncated to 140 characters; omit it to get the generated default narrative. example: 'Order #12345 - Leather Wallet' country_code: pattern: ^[A-Z]{2}$ type: string description: | Country code in ISO 3166-1 alpha-2 format. Required for the `direct_payment` flow, where it selects the country of the payment method's bank (for example Swedbank LT, LV or EE). A `direct_payment` link without it is still accepted (no validation error) and opens the Paysera checkout page instead. example: LT description: Payment details Checkout_Payment_Link_API_PurchaseDto: type: object properties: amount: minimum: 1 type: number nullable: true description: The amount to be paid in minor currency units (e.g. cents). Required unless the order lets the payer set the amount; must be omitted then (rejected with `payer_set_amount_with_amount`). example: 1000 suggested_amount: type: integer format: int64 nullable: true minimum: 1 maximum: 1000000 description: Amount suggested to the payer in minor currency units, overriding the order's suggested amount. Only when the order lets the payer set the amount (`suggested_amount_without_payer_set`), and within the order's limits (`suggested_amount_out_of_limits`). When omitted, the order's suggested amount is used. example: 2500 amount_buttons: type: array nullable: true maxItems: 4 uniqueItems: true description: Preset amounts offered to the payer in minor currency units, overriding the order's amount buttons. Only when the order lets the payer set the amount (`amount_buttons_without_payer_set`); three or four values (`amount_buttons_count`), strictly ascending (`amount_buttons_not_ascending`), each within the order's limits (`amount_buttons_out_of_limits`). When omitted or empty, the order's amount buttons are used. items: type: integer format: int64 minimum: 1 maximum: 1000000 example: - 1000 - 2500 - 5000 description: Purchase information. Required; send `{}` for an order where the payer sets the amount and you do not override anything Checkout_Payment_Link_API_CreatePaymentLinkIntegrationResponse: required: - created_at - experience - link_id - order_id - payer_information - payment_URL - payment_details - purchase type: object properties: link_id: type: string description: Unique payment link ID format: uuid order_id: type: string description: Unique order ID format: uuid example: a6f2b8e3-5e5f-47d9-b13f-87ed2db2938a payment_URL: type: string description: Payment URL example: www.example.com/sasdadw experience: $ref: '#/components/schemas/Checkout_Payment_Link_API_ExperienceResponseDto' payment_details: $ref: '#/components/schemas/Checkout_Payment_Link_API_PaymentDetailsResponseDto' purchase: $ref: '#/components/schemas/Checkout_Payment_Link_API_PurchaseResponseDto' payer_information: $ref: '#/components/schemas/Checkout_Payment_Link_API_PayerInformationResponseDto' expired_at: type: integer description: Payment link expiration timestamp in UTC timezone format: int64 example: 1745925943 created_at: type: integer description: Payment link creation timestamp in UTC timezone format: int64 example: 1745925543 description: Response after integration payment link creation Checkout_Payment_Link_API_ExperienceResponseDto: required: - language - payment_flow type: object properties: language: type: string description: The language of the payment link, selected from the project's description languages example: en payment_flow: type: string description: Payment flow type enum: - paysera_checkout - direct_payment example: paysera_checkout description: Payment experience configuration response Checkout_Payment_Link_API_PayerInformationResponseDto: type: object properties: name: type: string description: Payer name example: John Doe email: type: string description: Payer email example: customer@example.com description: Payer information response Checkout_Payment_Link_API_PaymentDetailsResponseDto: type: object properties: key: type: string description: Payment method key example: card-payment purpose: type: string description: >- The purpose supplied on the request, echoed back; null when it was omitted. example: 'Order #12345 - Leather Wallet' country_code: type: string description: Country code in ISO 3166-1 alpha-2 format example: LT description: Payment details response Checkout_Payment_Link_API_PurchaseResponseDto: required: - amount type: object properties: amount: type: integer description: The amount to be paid in minor currency units (e.g. cents). Null while the payer sets the amount format: int64 nullable: true example: 4999 payer_sets_amount: type: boolean description: Whether the payer enters the amount. Read-only, taken from the order example: false minimum_amount: type: integer description: Lowest amount the payer may enter, in minor currency units, as set on the order. Null when the order did not set one (the floor of 1 applies) or the amount is fixed format: int64 nullable: true example: 500 maximum_amount: type: integer description: Highest amount the payer may enter, in minor currency units, as set on the order. Null when the order did not set one (the platform maximum of 1000000 applies) or the amount is fixed format: int64 nullable: true example: 50000 suggested_amount: type: integer description: Amount suggested to the payer, in minor currency units. Null when not set format: int64 nullable: true example: 2500 amount_buttons: type: array description: Preset amounts offered to the payer, in minor currency units. Empty when none items: type: integer format: int64 example: [] description: Purchase information response Merchant_Order_API_ValidationErrorResponse: required: - error - error_description - error_properties type: object properties: error_properties: type: object additionalProperties: type: array items: type: string error_description: type: string error: type: string Merchant_Order_API_SimpleErrorResponse: required: - error - error_description type: object properties: error: type: string error_description: type: string Merchant_Order_API_IntegrationCreateOrderRequest: required: - purchase type: object properties: project_id: type: string description: Project identifier. If not provided, will be extracted from JWT token. format: uuid example: c35593b8-6b65-4cae-9d8e-39af32578ba7 redirect_urls: $ref: '#/components/schemas/Merchant_Order_API_RedirectUrls' metadata: type: object additionalProperties: type: string description: "\n Additional data attached to the order in key-value\ \ format.\n Each key and value must be at most 255 characters\ \ long.\n \"Keys and values exceeding 255 characters will\ \ be automatically trimmed.\n " example: '{"platform":"shopify","platform_version":"2.11.0","plugin_name":"paysera-checkout","plugin_version":"1.4.3","referrer":"https://merchantsite.com/somepage","tpi_id":"hostinger"}' description: "\n Additional data attached to the order in key-value\ \ format.\n Each key and value must be at most 255 characters\ \ long.\n \"Keys and values exceeding 255 characters will be\ \ automatically trimmed.\n " example: platform: shopify platform_version: 2.11.0 plugin_name: paysera-checkout plugin_version: 1.4.3 referrer: https://merchantsite.com/somepage tpi_id: hostinger merchant_data: type: object additionalProperties: type: string description: "\n Merchant data attached to the order in key-value\ \ format.\n Each key and value must be at most 255 characters\ \ long.\n " example: '{"key1":"value1","key2":"value2","key3":"value3"}' description: "\n Merchant data attached to the order in key-value\ \ format.\n Each key and value must be at most 255 characters\ \ long.\n " example: key1: value1 key2: value2 key3: value3 source: maxLength: 255 minLength: 0 type: string description: "\n Source indicating where this order originated\ \ from.\n \"Can be a website URL or other identifier.\n \ \ \"If not specified or empty, defaults to 'Integration'\n \ \ " example: https://myshop.paysera.net default: Integration purchase: $ref: '#/components/schemas/Merchant_Order_API_Purchase' splits: type: array nullable: true description: | Per-order entries for the project's split policy. Send one `variadic` entry per variadic slot in the policy template, and one `tip` entry per tip recipient when payer tips are enabled. Each entry names its recipient either by `beneficiary_id` (a beneficiary registered for the project) or with an inline `beneficiary` declaration that registers the recipient on the fly — the merchant share, percentages, and fixed shares come from the policy template, so do not send them. Orders with splits require a non-expiring payment link (`lifetime: 0`). items: $ref: '#/components/schemas/Merchant_Order_API_SplitRequest' split_overrides: allOf: - $ref: '#/components/schemas/Merchant_Order_API_SplitOverridesRequest' description: | Per-order override of the project's split-policy rules. Restates every policy slot for this order only — changing each slot's rule and/or recipient without altering the saved policy. Requires the project to have per-order overrides enabled. This is the only path that accepts a recipient account directly (without registering a beneficiary). Tips still travel in `splits` as `tip` entries. tips_enabled: type: boolean default: false description: | Offer the payer a tip on top of the fixed amount, outside Split Payments. Accepted only when tips are switched on for the project under Features in the merchant dashboard (otherwise `tips_not_enabled`), not together with `purchase.payer_sets_amount` (`tips_and_payer_set_amount_conflict`), not on a project with split payments (`tips_with_split_payments`), and not together with `tokenization` (`tips_and_tokenization_conflict`). example: false description: Request for order creation Merchant_Order_API_SplitRequest: required: - type type: object description: | Single split entry. `type` selects the role; the recipient is named by exactly one of `beneficiary_id` (a beneficiary registered for the project) or an inline `beneficiary` declaration. The rule (fixed amount or percentage) is configured on the project's split-policy template — your integration does not send it. properties: type: type: string description: | Role of this entry: * `variadic` — the per-order recipient that fills the policy template's variadic slot (e.g., the marketplace seller for this specific order). * `tip` — a recipient of an extra tip the payer chooses to add on top of the order total. enum: - variadic - tip example: variadic beneficiary_id: type: string format: uuid nullable: true description: | Id of the registered split beneficiary to pay. Register beneficiaries via the integration split-beneficiaries API; the merchant's self-beneficiary cannot be referenced here. Provide either this or `beneficiary`, not both. example: 550e8400-e29b-41d4-a716-446655440000 beneficiary: allOf: - $ref: '#/components/schemas/Merchant_Order_API_InlineSplitBeneficiaryRequest' description: | Inline beneficiary declaration — registers the recipient for the project as part of order creation. Provide either this or `beneficiary_id`, not both. Not accepted for `tip` entries on projects under the tax-agent consent regime. slot_id: type: string format: uuid nullable: true description: | Policy slot this variadic entry binds to. Required only when the policy has more than one variadic slot; with a single variadic slot it binds automatically. Ignored for `tip` entries. example: c1a2b3d4-e5f6-7890-abcd-ef1234567890 Merchant_Order_API_SplitOverridesRequest: required: - slots type: object description: | Per-order restatement of the project's split policy. Must restate every policy slot exactly once. When the project has variable split recipients enabled, a `variadic` slot may instead be listed zero or more times — once per recipient — while `merchant` and `beneficiary` slots are still listed exactly once. Exactly one slot must be `remainder`, and the `percentage` slots must sum to less than 100%. properties: slots: type: array minItems: 1 maxItems: 50 description: | One entry per policy slot. Every slot of the policy must be listed exactly once; with variable split recipients enabled, a `variadic` slot may be repeated (one entry per recipient) or left out. At most 50 entries. items: $ref: '#/components/schemas/Merchant_Order_API_SplitOverrideSlotRequest' Merchant_Order_API_SplitOverrideSlotRequest: required: - slot_id - type type: object description: Restated rule for a single policy slot. properties: slot_id: type: string format: uuid description: | Identifies which policy slot is being restated (from the split-policy response). The recipient is taken from that policy slot unless `recipient` is supplied. example: c1a2b3d4-e5f6-7890-abcd-ef1234567890 type: type: string description: | Rule type for this slot: * `fixed` — `value` in minor units / cents. * `percentage` — `value` in basis points (1 bp = 0.01%; 10000 = 100%). * `remainder` — omit `value`; the slot absorbs the residual. enum: - fixed - percentage - remainder example: percentage value: type: integer format: int64 nullable: true description: | Rule value. Required for `fixed` (cents, > 0) and `percentage` (basis points, 1–10000); omit for `remainder`. example: 1500 recipient: allOf: - $ref: '#/components/schemas/Merchant_Order_API_SplitOverrideRecipientRequest' description: | Recipient for this slot. Required for a `variadic` slot, optional for a fixed `beneficiary` slot (replaces the policy recipient), and must be omitted for the `merchant` slot. Merchant_Order_API_SplitOverrideRecipientRequest: type: object description: | Recipient of an override slot. Provide exactly one of `beneficiary_id`, `account`, or `beneficiary`. properties: beneficiary_id: type: string format: uuid nullable: true description: Id of a split beneficiary already registered for the project. example: 550e8400-e29b-41d4-a716-446655440000 account: type: string nullable: true description: | A Paysera account paid directly, without prior registration — given as an EVP account number or as the IBAN of a Paysera account (resolved server-side). A non-Paysera IBAN is not accepted here, as `account` carries no beneficiary name — declare it via `beneficiary` or register it as a beneficiary first. example: LT403500010018497892 beneficiary: allOf: - $ref: '#/components/schemas/Merchant_Order_API_InlineSplitBeneficiaryRequest' description: | Inline beneficiary declaration — registers the recipient for the project as part of order creation. Merchant_Order_API_InlineSplitBeneficiaryRequest: required: - iban - name type: object description: | Beneficiary declared inline on an order. Registered for the project as the order is created (the returned beneficiary can be reused on later orders). If the IBAN is already registered for the project, the existing beneficiary is reused and keeps its stored name. Whether the IBAN is a Paysera account or an external bank account is resolved server-side, under the same project rules as the split-beneficiaries API (external IBANs require external beneficiaries to be enabled for the project; only EEA SEPA IBANs are accepted). Registration happens after the request's shape checks pass, so an order rejected by a later configuration check may still leave the beneficiary registered. properties: iban: type: string description: Recipient's IBAN (Paysera or external). example: LT403500010018497892 name: type: string description: Display name for the beneficiary. minLength: 1 maxLength: 255 example: Marketplace Seller 42 Merchant_Order_API_Purchase: required: - currency - reference type: object properties: reference: type: string description: Unique identifier for the order in the merchant system example: ORDER-879-XYZ amount: type: integer format: int64 nullable: true description: Order amount in minor currency units (cents). Must be a positive whole number. For example, €149.99 is 14999. Required unless `payer_sets_amount` is true, and must then be omitted (`payer_set_amount_with_amount`). example: 14999 currency: type: string description: Currency code in ISO 4217 format example: EUR payer_sets_amount: type: boolean default: false description: Let the payer enter the amount on the payment page, within `minimum_amount` and `maximum_amount`. Accepted only when payer-set amount is switched on for the project under Features in the merchant dashboard and the project has no split payments; `amount` must then be omitted. example: true minimum_amount: type: integer format: int64 nullable: true minimum: 1 description: Lowest amount the payer may enter, in minor currency units. Only with `payer_sets_amount`; at least 1. When omitted, the floor of 1 applies and the created order's `minimum_amount` is null. example: 500 maximum_amount: type: integer format: int64 nullable: true minimum: 1 maximum: 1000000 description: Highest amount the payer may enter, in minor currency units. Only with `payer_sets_amount`; at most 1000000 and above `minimum_amount`. When omitted, the platform maximum of 1000000 applies and the created order's `maximum_amount` is null. example: 50000 suggested_amount: type: integer format: int64 nullable: true minimum: 1 maximum: 1000000 description: Amount prefilled in the payer's amount input, in minor currency units; the payer can change it. Only with `payer_sets_amount`, and within `minimum_amount` and `maximum_amount` (or the floor and platform maximum when they are omitted). example: 2000 amount_buttons: type: array nullable: true maxItems: 4 uniqueItems: true description: Three or four amounts the payer can pick, in minor currency units, strictly ascending; shown in the order sent. Only with `payer_sets_amount`, and each within `minimum_amount` and `maximum_amount` (or the floor and platform maximum when they are omitted). An empty list is the same as omitting it. items: type: integer format: int64 minimum: 1 maximum: 1000000 example: - 500 - 1000 - 2000 description: Payment purchase information (request) Merchant_Order_API_PurchaseResponse: required: - amount - currency - reference type: object properties: reference: type: string description: Unique identifier for the order in the merchant system example: ORDER-879-XYZ amount: type: integer format: int64 nullable: true description: Order amount in minor currency units (cents). Returned as an integer (Long). For example, €149.99 is returned as 14999. Null when the payer sets the amount. example: 14999 currency: type: string description: Currency code in ISO 4217 format example: EUR payer_sets_amount: type: boolean description: Whether the payer enters the amount example: false minimum_amount: type: integer format: int64 nullable: true description: Lowest amount the payer may enter, in minor currency units, as the merchant set it. Null when not set; on a payer-set order the floor of 1 then applies example: 500 maximum_amount: type: integer format: int64 nullable: true description: Highest amount the payer may enter, in minor currency units, as the merchant set it. Null when not set; on a payer-set order the platform maximum of 1000000 then applies example: 50000 suggested_amount: type: integer format: int64 nullable: true description: Amount prefilled in the payer's amount input, in minor currency units. Null when not set example: 2000 amount_buttons: type: array description: Amounts the payer can pick, in minor currency units, in the order the merchant sent them. Empty when not set items: type: integer format: int64 example: [] description: Payment purchase information (response — amount is an integer) Merchant_Order_API_RedirectUrls: type: object properties: success_url: maxLength: 2048 minLength: 0 type: string description: URL for redirection after successful payment completion example: https://best-merchant.paysera.net/success failure_url: maxLength: 2048 minLength: 0 type: string description: URL for redirection when payment fails example: https://best-merchant.paysera.net/fail callback_url: maxLength: 2048 minLength: 0 type: string description: Backend URL to receive payment updates example: https://best-merchant.paysera.net/webhook cancel_url: maxLength: 2048 minLength: 0 type: string description: URL for redirection when the payer cancels the payment example: https://best-merchant.paysera.net/cancel description: Redirect URLs for the order Merchant_Order_API_IntegrationCreateOrderResponse: required: - created_at - order_id - project_id - purchase - source type: object properties: project_id: type: string description: Project identifier associated with the order format: uuid example: c35593b8-6b65-4cae-9d8e-39af32578ba7 order_id: type: string description: Unique order identifier format: uuid created_at: type: integer description: Creation date-time in UTC timezone format: int64 example: 1736433270 merchant_data: type: object additionalProperties: type: string description: "\n Additional data attached to the order in key-value\ \ format.\n " example: '{"key1":"value1","key2":"value2","key3":"value3"}' description: "\n Additional data attached to the order in key-value\ \ format.\n " example: key1: value1 key2: value2 key3: value3 source: type: string description: Source indicating where this order originated from example: https://myshop.paysera.net purchase: $ref: '#/components/schemas/Merchant_Order_API_PurchaseResponse' tips_enabled: type: boolean description: Whether the payer is offered a tip on top of the fixed amount, outside Split Payments example: false description: Response after order creation Merchant_Order_API_IntegrationGetOrderByIdResponse: required: - id - project_id - amount - currency - status - reference - source - created_at - updated_at - amount_paid - balance_due type: object properties: id: type: string description: Unique order identifier format: uuid project_id: type: string description: ID of the project associated with the order example: a6f2b8e3-5e5f-47d9-b13f-87ed2db2938a amount: type: integer description: Total amount of the order in minor currency units (e.g. cents). Null while the payer has not entered the amount of a payer-set order format: int64 nullable: true example: 1000 currency: pattern: ^[A-Z]{3}$ type: string description: Currency code in ISO 4217 format example: EUR status: type: string description: Status of the order enum: - pending_payment - paid - canceled - closed reference: type: string description: Unique reference for order tracking (for example, order ID in the merchant system) example: ORDER_123 callback_url: type: string description: URL for payment system callbacks success_url: type: string description: URL to redirect the user after successful payment fail_url: type: string description: URL to redirect the user when payment fails cancel_url: type: string description: URL to redirect the user to when the payment is canceled (back to shop) source: type: string description: Source indicating where this order originated from example: https://myshop.paysera.net created_at: type: integer description: Creation date-time in UTC timezone format: int64 updated_at: type: integer description: Last update date-time in UTC timezone format: int64 amount_paid: type: integer description: Amount already paid in minor currency units (e.g. cents) format: int64 example: 1000 balance_due: type: integer description: Balance due in minor currency units (e.g. cents). Null while the order has no amount yet format: int64 nullable: true example: 0 merchant_data: type: object additionalProperties: type: string description: Additional data attached to the order in key-value format split_config_id: type: string description: Fund-distributor split-config identifier. Null when the order was not created with splits. format: uuid nullable: true example: 550e8400-e29b-41d4-a716-446655440000 checkout_flow: type: string description: Checkout flow the order is paid through, as supplied on creation. Null when the order did not set one and the project's own setting applies. nullable: true example: cards_and_wallets_only cancel_reason: type: string description: | Why the order was canceled. Null until the order is canceled. Known values: `canceled_by_merchant`, `canceled_by_admin`, `project_deleted` (the order's project was deleted), `expired_ttl` (the order was not paid within its time limit) and `order_template_deactivated` (the reusable payment link the order was opened from was deactivated). Treat any other value as a generic cancellation. nullable: true example: canceled_by_merchant payer_sets_amount: type: boolean description: Whether the payer enters the amount example: false minimum_amount: type: integer description: Lowest amount the payer may enter, in minor currency units, as the merchant set it. Null when not set format: int64 nullable: true example: 500 maximum_amount: type: integer description: Highest amount the payer may enter, in minor currency units, as the merchant set it. Null when not set format: int64 nullable: true example: 50000 suggested_amount: type: integer description: Amount prefilled in the payer's amount input, in minor currency units. Null when not set format: int64 nullable: true example: 2000 amount_buttons: type: array description: Amounts the payer can pick, in minor currency units, in the order the merchant sent them. Empty when not set items: type: integer format: int64 example: - 500 - 1000 - 2000 payment_accepted_at: type: integer description: When a payment of this order was first accepted (authorized or later); null until then. format: int64 nullable: true example: 1737968400 tips_enabled: type: boolean description: Whether the payer is offered a tip on top of the fixed amount, outside Split Payments example: false tip_amount: type: integer description: Tip total the payer added, in minor currency units; included in `amount_paid` on top of `amount`. Set for tips with and without Split Payments, so it may be set while `tips_enabled` is false. Null when no tip was paid format: int64 nullable: true example: 150 order_template: type: object description: Reusable payment link the order was opened from. Null for an order created any other way nullable: true required: - id - name properties: id: type: string description: Order template identifier. This is not a payment link id format: uuid example: 0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f6a01 name: type: string description: Name of the reusable payment link, for display only example: Coffee donations payer_text: type: string description: Text shown to the payer, copied from the reusable payment link the order was opened from. Null for an order created any other way nullable: true example: Thank you for supporting us description: Order details Checkout_Merchant_Project_API_ErrorResponse: type: object description: | Error envelope. `error` is a stable machine code; `error_description` is a human-readable message; `error_properties` (when present) maps a field to its validation messages. properties: error: type: string example: unprocessable_entity error_description: type: string example: Split beneficiaries are not enabled for this project error_properties: type: object nullable: true additionalProperties: type: array items: type: string Checkout_Merchant_Project_API_CreateSplitBeneficiaryRequest: type: object required: - iban - name properties: iban: type: string description: | Recipient's IBAN. Whether it is a Paysera account or an external bank account is resolved server-side and returned as `destination_type`. An external IBAN is only accepted when external beneficiaries are enabled for the project, and the IBAN must not resolve to the project owner's own account. example: LT403500010018497892 name: type: string description: Display name for the beneficiary. minLength: 1 maxLength: 255 example: Marketplace Seller 42 Checkout_Merchant_Project_API_SplitBeneficiaryResponse: type: object description: A registered split beneficiary. The `id` is the `beneficiary_id` used in order `splits[]`. properties: id: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 destination_type: type: string enum: - paysera_account - external_iban description: Resolved from the submitted IBAN. example: paysera_account account_number: type: string description: The resolved Paysera (EVP) account number, or the masked IBAN for an external destination. example: EVP5210018145214 name: type: string example: Marketplace Seller 42 created_at: type: integer format: int64 description: Creation time as a Unix timestamp (seconds). example: 1716200000 Checkout_Merchant_Project_API_CreateSplitBeneficiaryByPhoneRequest: type: object required: - phone properties: phone: type: string description: Phone number of the recipient's Paysera individual account, in international format. minLength: 8 maxLength: 32 example: '+37060000000' Checkout_Merchant_Project_API_SplitBeneficiaryByPhoneResponse: type: object description: A tip recipient registered by phone. The `id` is the `beneficiary_id` used in order `splits[]`. properties: id: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 name: type: string nullable: true description: The recipient's name as known to Paysera. example: John D. account_number: type: string nullable: true description: | The recipient's Paysera (EVP) account. `null` for Lithuanian merchants until the recipient gives tax-agent consent, after which their payout account is assigned. example: null created_at: type: integer format: int64 description: Creation time as a Unix timestamp (seconds). example: 1716200000 Checkout_Merchant_Project_API_SplitBeneficiaryListResponse: type: object properties: items: type: array items: $ref: '#/components/schemas/Checkout_Merchant_Project_API_SplitBeneficiaryListItem' _metadata: $ref: '#/components/schemas/Checkout_Merchant_Project_API_ListMetadata' Checkout_Merchant_Project_API_SplitBeneficiaryListItem: type: object required: - id - destination_type - account_number - bic - name - created_at - consent_status properties: id: type: string format: uuid nullable: true description: Beneficiary id. `null` for the merchant's own self-row (cannot be referenced in splits). example: 550e8400-e29b-41d4-a716-446655440000 destination_type: type: string enum: - paysera_account - external_iban example: paysera_account account_number: type: string nullable: true description: | The beneficiary's Paysera (EVP) account, or the masked IBAN for an external destination; `null` for a self-row with no bank account and for tip recipients whose account is not assigned yet. example: EVP5210018145214 bic: type: string nullable: true description: BIC / SWIFT of the beneficiary bank, when provided for an external destination. `null` for paysera-account beneficiaries and the merchant self-row. example: null name: type: string example: Marketplace Seller 42 created_at: type: integer format: int64 example: 1716200000 consent_status: type: string enum: - given - not_given - not_required - null nullable: true description: | Tax-agent consent status. Populated only on Lithuanian payer-tips projects; `null` on non-LT or tips-disabled projects, and also `null` within an eligible project for the merchant self-row, plain account beneficiaries, and tip recipients with no consent record. `not_required` means the recipient declared a non-Lithuanian residence. A tip recipient who has not consented yet is `not_given`, with `account_number: null`. Checkout_Merchant_Project_API_ListMetadata: type: object properties: has_next: type: boolean has_previous: type: boolean cursors: type: object properties: after: type: string nullable: true before: type: string nullable: true total: type: integer nullable: true description: Total item count. Always present; `null` unless `include_total=true` was requested. Checkout_Merchant_Project_API_ProjectSplitPolicyResponse: type: object properties: project_id: type: string format: uuid example: b7c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e configured: type: boolean description: Whether every slot's merchant-owned fields are set. An order with splits fails if `false`. slots: type: array items: $ref: '#/components/schemas/Checkout_Merchant_Project_API_SplitPolicySlot' Checkout_Merchant_Project_API_SplitPolicySlot: type: object description: One share of the policy. Bind variadic order entries and per-order overrides by `slot_id`. properties: slot_id: type: string format: uuid example: 22222222-2222-2222-2222-222222222222 position: type: integer description: 0-based position of the slot in the policy. example: 1 role: type: string enum: - merchant - beneficiary - variadic example: variadic rule_type: type: string enum: - fixed - percentage - remainder nullable: true description: Rule kind, or `null` if not yet configured. value: type: integer nullable: true description: Cents for `fixed`; basis points for `percentage` (10000 = 100%); `null` for `remainder` or unconfigured. beneficiary_id: type: string format: uuid nullable: true description: Fixed recipient configured on the slot, if any. beneficiary_account_number: type: string nullable: true description: The fixed recipient's EVP account, if any. beneficiary_name: type: string nullable: true description: The fixed recipient's display name, if any. beneficiary_missing: type: boolean description: '`true` if a beneficiary slot references a recipient that has been deleted.' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: JWT token for authentication