> ## Documentation Index > Fetch the complete documentation index at: https://docs.flowlix.eu/llms.txt > Use this file to discover all available pages before exploring further. # Create a hosted payment page payment > Creates a hosted payment page payment attempt. Redirect the customer to `next_action.redirect_url` to complete the `next_action.reason` customer action. The required-action URL is opaque and may later change from the hosted page to a 3D Secure browser action. Use the latest `next_action.redirect_url` from `GET /v1/payments/{id}`, and avoid redirect loops when the URL is unchanged. `billing_details` is optional and, when supplied, is used to prefill the hosted page. If the customer edits the billing details on the hosted page, the customer-entered values become authoritative for the payment. `return_url` is the merchant URL where the customer is sent after completing or abandoning the hosted payment page. Return URL query parameters are UX hints only; merchants must use `GET /v1/payments/{id}` as the source of truth. Use the `Idempotency-Key` header to safely retry requests. ## OpenAPI ````yaml /api-reference/payments-api.yaml post /v1/payments/hpp openapi: 3.0.4 info: title: Flowlix Payments API version: 1.0.0 description: > The Flowlix Payments API is a RESTful API for creating and retrieving Payments, creating Refunds, and submitting and retrieving Payouts. It follows industry-standard conventions: JSON request/response bodies, Bearer token authentication, standard HTTP verbs, idempotency support, and cursor-based pagination. ## Base URL API requests are made to `https://api.flowlix.eu`. Endpoints are versioned under `/v1`, e.g. `https://api.flowlix.eu/v1/payments`. ## Amounts and currencies All monetary amounts are expressed in **minor units** (the smallest currency unit). How many minor units make up one major unit is defined by the currency's ISO 4217 exponent, so the same integer means a different value in different currencies: `4999` is **EUR 49.99** and **GBP 49.99** (exponent 2), but **JPY 4999** (exponent 0, no minor unit). Do not assume two decimal places. Currencies are three-letter ISO 4217 codes. Requests are accepted case-insensitively; Flowlix normalizes them and always returns canonical uppercase codes such as `EUR`. The currencies accepted for a Payment or Payout are validated separately per request rather than listed in this contract, so enabling another currency is not a breaking change. A code that is not three letters is rejected with `400 parameter_invalid` (`param=currency`), and a well-formed code that Flowlix does not accept for the requested operation is rejected with `422 currency_not_supported`. Neither response creates a Payment or Payout. A refund is always made in the currency of the original payment, and the refund request does not accept a currency. contact: name: Flowlix Developer Support email: developers@flowlix.eu url: https://flowlix.dev/support license: name: Proprietary url: https://flowlix.dev/terms servers: - url: https://api.flowlix.eu description: Flowlix Merchant API. security: - BearerAuth: [] tags: - name: Health description: Check aggregate Flowlix API availability. - name: Payments description: Create, retrieve, and list payments. - name: Payouts description: Submit, list, and retrieve Host-to-Host card payouts. - name: Refunds description: >- Create refunds and track their status through the parent payment's `refunds` array. paths: /v1/payments/hpp: post: tags: - Payments summary: Create a hosted payment page payment description: | Creates a hosted payment page payment attempt. Redirect the customer to `next_action.redirect_url` to complete the `next_action.reason` customer action. The required-action URL is opaque and may later change from the hosted page to a 3D Secure browser action. Use the latest `next_action.redirect_url` from `GET /v1/payments/{id}`, and avoid redirect loops when the URL is unchanged. `billing_details` is optional and, when supplied, is used to prefill the hosted page. If the customer edits the billing details on the hosted page, the customer-entered values become authoritative for the payment. `return_url` is the merchant URL where the customer is sent after completing or abandoning the hosted payment page. Return URL query parameters are UX hints only; merchants must use `GET /v1/payments/{id}` as the source of truth. Use the `Idempotency-Key` header to safely retry requests. operationId: createHppPayment parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateHPPaymentRequest' examples: basic: summary: Hosted payment page payment value: amount: 2500 currency: EUR merchant_reference: 2345678901 customer_ip_address: 203.0.113.7 billing_details: email: jenny@example.com first_name: Jenny last_name: Rosen phone: '+491701234567' address: line1: Kurfuerstendamm 21 city: Berlin postal_code: '10719' country: DE return_url: https://shop.example.com/checkout/complete responses: '201': description: | Hosted payment page payment accepted and a Payment object was created. `REQUIRES_ACTION` includes the hosted redirect; `PENDING` records an outcome that is not safe to resubmit; and `FAILED` records a terminal Payment result. A newly created HPP Payment does not return `PROCESSING` before the first customer redirect. Use `GET /v1/payments/{id}` as the source of truth for the final outcome. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Payment' examples: pending: $ref: '#/components/examples/HppPaymentPending' requires_action: $ref: '#/components/examples/HppPaymentRequiresAction' failed: $ref: '#/components/examples/HppPaymentFailed' '400': $ref: '#/components/responses/CreateBadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/PaymentForbidden' '409': $ref: '#/components/responses/HppConflict' '422': $ref: '#/components/responses/PaymentUnprocessableEntity' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailable' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: true description: > A unique key to ensure one effective operation is processed only once. If the same key and an equivalent operation-specific effective request identity have already completed successfully, the original response is returned. A different identity returns `409 idempotency_key_reused`. Non-2xx responses are not cached, so callers may retry after errors. No fixed retention period is promised by this contract. For one-shot requests, such as creating a payment from a checkout button, a random UUIDv4 is fine. For requests tied to a specific business operation, such as refunding an order, a deterministic key is preferred so retries collapse correctly across processes. schema: type: string maxLength: 255 example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 schemas: CreateHPPaymentRequest: type: object additionalProperties: false required: - amount - currency - customer_ip_address - return_url properties: amount: type: integer format: int64 minimum: 1 description: | Payment amount in the currency's minor units. How many minor units make one major unit is set by the currency's ISO 4217 exponent, so the same integer means a different value in different currencies: `4999` is EUR 49.99 (exponent 2) but JPY 4999 (exponent 0). Do not assume two decimal places. example: 2500 currency: $ref: '#/components/schemas/CurrencyInput' merchant_reference: $ref: '#/components/schemas/MerchantReference' customer_ip_address: $ref: '#/components/schemas/CustomerIpAddress' merchant_customer_id: $ref: '#/components/schemas/MerchantCustomerId' billing_details: $ref: '#/components/schemas/BillingDetailsInput' description: type: string maxLength: 500 description: Merchant-provided payment description. example: 'Order #5678' return_url: type: string format: uri description: >- Merchant URL where the customer returns after hosted payment completion or abandonment. example: https://shop.example.com/checkout/complete Payment: type: object description: | A Payment represents one attempt to collect funds from the customer. Merchants can use `merchant_reference` to associate multiple payment attempts with the same order or checkout in their own systems. required: - id - amount - currency - status - created_at - livemode - amount_refunded - amount_refundable - integration_type properties: id: $ref: '#/components/schemas/PaymentId' amount: type: integer format: int64 minimum: 1 description: >- Payment amount in the currency's minor units, per its ISO 4217 exponent: `4999` is EUR 49.99 but JPY 4999. example: 4999 currency: $ref: '#/components/schemas/CurrencyCode' status: $ref: '#/components/schemas/PaymentStatus' integration_type: $ref: '#/components/schemas/IntegrationType' merchant_reference: type: integer allOf: - $ref: '#/components/schemas/MerchantReference' nullable: true description: Merchant-side reconciliation reference, if provided. description: type: string nullable: true description: Merchant-provided payment description. example: 'Order #1234' card: type: object allOf: - $ref: '#/components/schemas/Card' nullable: true description: Masked card details, or `null` before card details are available. billing_details: type: object allOf: - $ref: '#/components/schemas/BillingDetails' nullable: true description: Billing details captured for the payment, if available. failure_code: type: string allOf: - $ref: '#/components/schemas/OperationFailureCode' nullable: true description: >- Machine-readable reason code when the payment reaches a terminal failed status. example: insufficient_funds failure_message: type: string nullable: true description: >- Human-readable explanation when the payment reaches a terminal failed status. example: The card has insufficient funds. amount_refunded: type: integer format: int64 minimum: 0 description: >- Total amount successfully refunded so far, in the payment currency's minor units, per its ISO 4217 exponent. example: 0 amount_refundable: type: integer format: int64 minimum: 0 description: >- Remaining amount that can be refunded, in the payment currency's minor units, per its ISO 4217 exponent. example: 4999 refunds: type: array description: Refunds created for this payment, oldest first. items: $ref: '#/components/schemas/Refund' default: [] status_transitions: $ref: '#/components/schemas/StatusTransitions' created_at: type: integer format: int64 description: Unix timestamp when the payment was created. example: 1719792000 livemode: type: boolean description: Always `false` for a Payment created in Sandbox. example: false next_action: type: object allOf: - $ref: '#/components/schemas/PaymentNextAction' nullable: true description: Customer action required to continue the payment. CurrencyInput: type: string minLength: 3 maxLength: 16 pattern: ^\s*[A-Za-z]{3}\s*$ description: > Three-letter ISO 4217 currency code supplied when creating a payment or payout. Accepted case-insensitively and with surrounding whitespace, then normalized to a canonical uppercase code before the operation is created. A value that is not three letters is rejected with `400 parameter_invalid` (`param=currency`); a well-formed code that Flowlix does not accept for that operation is rejected with `422 currency_not_supported`. Neither creates a payment or payout. The available set is validated per request instead of being enumerated here, so enabling another currency is not a breaking contract change. example: EUR MerchantReference: type: integer format: int64 minimum: 1000000000 maximum: 9999999999 description: | Optional merchant-side reconciliation reference. The value must contain exactly 10 decimal digits and does not provide idempotency by itself. example: 1234567890 CustomerIpAddress: type: string minLength: 3 maxLength: 45 pattern: >- ^(((25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])|[0-9A-Fa-f:]*:[0-9A-Fa-f:.]*)$ description: > Shopper IPv4 or IPv6 address observed by the merchant during checkout. Send one literal address, not a hostname, port, or comma-separated proxy chain. Flowlix validates the complete IPv4 or IPv6 literal before registering the payment; the pattern is only an initial schema-level character and length guard. example: 203.0.113.7 MerchantCustomerId: type: string minLength: 1 maxLength: 255 description: Optional stable identifier for the shopper within the merchant account. example: customer_42 BillingDetailsInput: type: object additionalProperties: false description: >- Optional payer contact and billing-address details used to prefill hosted payment pages. properties: email: type: string format: email minLength: 1 maxLength: 255 description: Billing email address. example: jenny@example.com first_name: type: string nullable: true maxLength: 255 description: Payer first name. example: Jenny last_name: type: string nullable: true maxLength: 255 description: Payer last name. example: Rosen phone: type: string nullable: true pattern: ^\+[1-9]\d{1,14}$ maxLength: 16 description: Billing phone number in E.164 format, for example `+491701234567`. example: '+491701234567' address: allOf: - $ref: '#/components/schemas/BillingAddressInput' PaymentId: type: string pattern: ^pay_[A-Za-z0-9]{24}$ description: >- Unique opaque identifier for a payment (`pay_` prefix + random alphanumeric suffix). example: pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E CurrencyCode: type: string minLength: 3 maxLength: 3 pattern: ^[A-Z]{3}$ description: > Canonical uppercase three-letter ISO 4217 currency code. Responses always return the original currency the payment was created in; a provider response never replaces it. example: EUR PaymentStatus: type: string enum: - PENDING - REQUIRES_ACTION - PROCESSING - SUCCEEDED - FAILED - EXPIRED description: > Current status of a payment attempt. - `PENDING` -- The payment was accepted by Flowlix and is awaiting provider submission or the next lifecycle decision. - `REQUIRES_ACTION` -- Customer action is required, such as completing 3D Secure authentication or a hosted payment page. - `PROCESSING` -- The payment is being processed by downstream payment systems. - `SUCCEEDED` -- The payment completed successfully. - `FAILED` -- The payment was declined or failed permanently. - `EXPIRED` -- The customer did not complete a required action before its expiry time. example: SUCCEEDED IntegrationType: type: string enum: - DIRECT - HOSTED_PAYMENT_PAGE description: | How the payment was collected. This is separate from the payment method instrument, such as `card`. example: DIRECT Card: type: object description: >- Masked card details. If card details are not available, the entire `card` field is `null`. required: - brand - last4 - exp_month - exp_year properties: brand: $ref: '#/components/schemas/CardBrand' last4: type: string pattern: ^[0-9]{4}$ description: Last four digits of the card number. example: '2207' exp_month: type: integer format: int32 minimum: 1 maximum: 12 description: Card expiration month. example: 12 exp_year: type: integer format: int32 description: Card expiration year. example: 2027 cardholder_name: type: string nullable: true description: >- Cardholder name, if available. For Direct API payments, this is the submitted `holder_name`. example: Jenny Rosen country: type: string nullable: true description: Two-letter ISO country code of the issuing bank, if available. allOf: - $ref: '#/components/schemas/CountryCode' BillingDetails: type: object description: Billing details associated with the payer. properties: email: type: string nullable: true format: email description: Billing email address. example: jenny@example.com first_name: type: string nullable: true description: Payer first name. example: Jenny last_name: type: string nullable: true description: Payer last name. example: Rosen phone: type: string nullable: true pattern: ^\+[1-9]\d{1,14}$ description: Billing phone number in E.164 format, for example `+491701234567`. example: '+491701234567' address: type: object allOf: - $ref: '#/components/schemas/BillingAddress' nullable: true OperationFailureCode: type: string description: >- Stable public failure vocabulary used by Payment `failure_code`, Refund `failure.code`, and Payout `failure_code`. The meaning is shared, but handling differs: shopper or new-card actions for a Payment must not be applied to a Refund or Payout. enum: - not_found - processor_error - processor_unavailable - generic_decline - do_not_honor - issuer_declined - insufficient_funds - invalid_number - invalid_expiry - expired_card - invalid_amount - invalid_currency - not_permitted - cardholder_limit - card_velocity_exceeded - lost_card - stolen_card - suspect_fraud - fraud_filter - three_d_secure_failed - three_d_secure_timeout - three_d_secure_not_supported - three_d_secure_error example: insufficient_funds Refund: type: object description: A refund against a payment. required: - id - payment_id - amount - currency - reason - refund_type - status - created_at - updated_at - livemode properties: id: $ref: '#/components/schemas/RefundId' payment_id: $ref: '#/components/schemas/PaymentId' amount: type: integer format: int64 minimum: 1 description: >- Refund amount in the currency's minor units, per its ISO 4217 exponent: `4999` is EUR 49.99 but JPY 4999. example: 1500 currency: $ref: '#/components/schemas/CurrencyCode' merchant_reference: type: integer allOf: - $ref: '#/components/schemas/MerchantReference' nullable: true description: Merchant-side reconciliation reference for this refund, if provided. reason: type: string maxLength: 50 description: Merchant-provided refund reason stored with the refund. example: Full refund verification refund_type: $ref: '#/components/schemas/RefundType' status: $ref: '#/components/schemas/RefundStatus' failure: $ref: '#/components/schemas/RefundFailure' created_at: type: integer format: int64 description: Unix timestamp when the refund was created. example: 1719795600 updated_at: type: integer format: int64 description: Unix timestamp when the refund was last updated. example: 1719795660 completed_at: type: integer nullable: true format: int64 description: Unix timestamp when the refund reached a terminal status. example: 1719799200 livemode: type: boolean description: Always `false` for a Refund created in Sandbox. example: false StatusTransitions: type: object description: Timestamps for important payment status transitions. properties: requires_action_at: type: integer nullable: true format: int64 description: Unix timestamp when the payment first required customer action. example: null processing_at: type: integer nullable: true format: int64 description: Unix timestamp when downstream processing started. example: 1719792002 succeeded_at: type: integer nullable: true format: int64 description: Unix timestamp when the payment succeeded. example: 1719792042 failed_at: type: integer nullable: true format: int64 description: Unix timestamp when the payment failed. example: null expired_at: type: integer nullable: true format: int64 description: Unix timestamp when the payment expired. example: null PaymentNextAction: type: object required: - type - reason - redirect_url properties: type: type: string enum: - redirect description: The action type. Currently only `redirect` is supported. example: redirect reason: type: string enum: - hosted_payment_page - three_d_secure description: Why the customer redirect is required. example: three_d_secure redirect_url: type: string format: uri description: | Opaque provider URL for the current customer browser action. The URL can point to a hosted payment page, 3D Secure fingerprint collection, or a later authentication/challenge step. Redirect the customer to the latest URL returned for the payment, follow a new URL if it changes while the payment is still `REQUIRES_ACTION`, and avoid repeatedly redirecting the same browser to the same URL. example: https://authentication.example/redirect-token ApiError: type: object description: Error response wrapper. properties: error: $ref: '#/components/schemas/ApiErrorBody' BillingAddressInput: type: object additionalProperties: false required: - line1 - city - postal_code - country properties: line1: type: string minLength: 1 maxLength: 500 description: First line of the billing street address. example: Kurfuerstendamm 21 line2: type: string nullable: true maxLength: 500 description: Second line of the billing street address, if present. example: Apartment 4B city: type: string minLength: 1 maxLength: 255 description: Billing city. example: Berlin state: type: string nullable: true maxLength: 255 description: Billing state, region, or province, if applicable. example: Berlin postal_code: type: string minLength: 1 maxLength: 20 description: Billing postal code. example: '10719' country: $ref: '#/components/schemas/CountryCode' CardBrand: type: string description: | Canonical lower-case card-network brand, for example `visa`, `mastercard`, or `amex`. The schema remains extensible; each operation validates its supported brands separately. example: visa CountryCode: type: string pattern: ^[A-Z]{2}$ description: Canonical ISO 3166-1 alpha-2 country code. example: DE BillingAddress: type: object description: Billing address associated with the payer. properties: line1: type: string nullable: true description: First line of the billing street address. example: Kurfuerstendamm 21 line2: type: string nullable: true description: Second line of the billing street address, if present. example: Apartment 4B city: type: string nullable: true description: Billing city. example: Berlin state: type: string nullable: true description: Billing state, region, or province, if applicable. example: Berlin postal_code: type: string nullable: true description: Billing postal code. example: '10719' country: type: string nullable: true pattern: ^[A-Z]{2}$ description: Billing country as an ISO 3166-1 alpha-2 code. example: DE RefundId: type: string pattern: ^ref_[A-Za-z0-9]{24}$ description: >- Unique opaque identifier for a refund (`ref_` prefix + random alphanumeric suffix). example: ref_L9xQ4wE2rT8yU6iO3pA7sD1f RefundType: type: string enum: - FULL - PARTIAL description: | Whether the refund covers the full original payment amount or only part of it. example: FULL RefundStatus: type: string enum: - PENDING - PROCESSING - SUCCEEDED - FAILED description: | Current refund lifecycle status. Refunds normally move from `PENDING` to `PROCESSING`, then to `SUCCEEDED` or `FAILED`. example: PENDING RefundFailure: type: object nullable: true description: Refund failure details when the refund reaches `FAILED`. required: - code - message properties: code: type: string description: Machine-readable Flowlix error code. example: fraud_filter message: type: string description: Human-readable Flowlix error explanation. example: The payment was declined by fraud controls. ApiErrorBody: type: object description: Detailed error information. required: - message properties: code: type: string nullable: true description: Short machine-readable error code. message: type: string description: >- Human-readable context that may include object-specific values and may change. Branch on `code`, not this text. param: type: string nullable: true description: Request parameter that caused the error, if applicable. doc_url: type: string nullable: true format: uri description: URL to documentation for this error. request_id: type: string nullable: true description: Request ID matching the `Request-Id` response header. headers: RequestId: description: >- A unique identifier for this API request. Include it when contacting support. schema: type: string maxLength: 255 example: req_abc123def456 RetryAfter: description: Number of seconds to wait before retrying. schema: type: integer example: 5 examples: HppPaymentPending: summary: Hosted Payment Page outcome is pending review value: id: pay_v2Pr7Su3Aw9Cy1De4Fg8Hi0K amount: 2500 currency: EUR status: PENDING integration_type: HOSTED_PAYMENT_PAGE merchant_reference: 2345678901 description: 'Order #5678' amount_refunded: 0 amount_refundable: 0 refunds: [] created_at: 1719792000 livemode: false HppPaymentRequiresAction: summary: Hosted Payment Page is ready for browser redirect value: id: pay_s9Mo4Pr0Xt6Zv8Ab1Cd5Ef7G amount: 2500 currency: EUR status: REQUIRES_ACTION integration_type: HOSTED_PAYMENT_PAGE merchant_reference: 2345678901 description: 'Order #5678' amount_refunded: 0 amount_refundable: 0 refunds: [] status_transitions: requires_action_at: 1719792002 created_at: 1719792000 livemode: false next_action: type: redirect reason: hosted_payment_page redirect_url: https://hosted-payment.example/redirect-token HppPaymentFailed: summary: Hosted Payment Page creation ended in a terminal failure value: id: pay_w3Qs8Tv4Bx0Dz2Ef5Gh9Ij1L amount: 2500 currency: EUR status: FAILED integration_type: HOSTED_PAYMENT_PAGE merchant_reference: 2345678901 description: 'Order #5678' failure_code: generic_decline failure_message: The payment was declined. amount_refunded: 0 amount_refundable: 0 refunds: [] status_transitions: failed_at: 1719792002 created_at: 1719792000 livemode: false ErrorRequestBodyInvalid: summary: Request body cannot be read value: error: code: request_body_invalid message: Request body is invalid. doc_url: https://docs.flowlix.eu/guides/errors request_id: req_body400a ErrorParameterMissing: summary: Required header is missing value: error: code: parameter_missing message: Idempotency-Key header is required. param: Idempotency-Key doc_url: https://docs.flowlix.eu/guides/errors request_id: req_param400b ErrorParameterInvalid: summary: Request parameter has an invalid value value: error: code: parameter_invalid message: Request validation failed. param: amount doc_url: https://docs.flowlix.eu/guides/errors request_id: req_param400a ErrorInvalidApiKey: summary: Missing or invalid API key value: error: code: invalid_api_key message: The API key is invalid. doc_url: https://docs.flowlix.eu/guides/errors request_id: req_auth401a ErrorPaymentAcceptanceUnavailable: summary: Merchant cannot accept new Payments value: error: code: payment_acceptance_unavailable message: Payment acceptance is unavailable. doc_url: https://docs.flowlix.eu/api-reference/errors request_id: req_payment403a ErrorHppIdempotencyKeyInUse: summary: Original Hosted Payment Page request is still processing value: error: code: idempotency_key_in_use message: >- The original hosted page payment request for pay_s9Mo4Pr0Xt6Zv8Ab1Cd5Ef7G is still processing for this idempotency key. param: Idempotency-Key doc_url: https://docs.flowlix.eu/api-reference/errors request_id: req_hpp409a ErrorHppIdempotencyKeyReused: summary: Hosted Payment Page key was reused for a different effective identity value: error: code: idempotency_key_reused message: >- Idempotency key was already used for hosted page payment pay_s9Mo4Pr0Xt6Zv8Ab1Cd5Ef7G with different request parameters. param: Idempotency-Key doc_url: https://docs.flowlix.eu/api-reference/errors request_id: req_hpp409b ErrorPaymentCurrencyNotSupported: summary: Currency is not accepted for Payments value: error: code: currency_not_supported message: Currency XTS is not supported for payments. param: currency doc_url: https://docs.flowlix.eu/api-reference/errors request_id: req_currency422p ErrorMerchantNotProvisioned: summary: Merchant is not provisioned for this operation value: error: code: merchant_not_provisioned message: The merchant is not provisioned on the payment gateway. doc_url: https://docs.flowlix.eu/api-reference/errors request_id: req_merchant422a ErrorInternal: summary: Unexpected Flowlix error value: error: code: internal_error message: An internal error occurred. doc_url: https://docs.flowlix.eu/guides/errors request_id: req_internal500a ErrorServiceUnavailable: summary: Flowlix is temporarily unavailable value: error: code: service_unavailable message: Upstream payment processor is temporarily unavailable. Please retry. doc_url: https://docs.flowlix.eu/guides/errors request_id: req_service503a responses: CreateBadRequest: description: | The create request could not be read or failed request validation. Correct the JSON, required headers, or parameter named by `error.param`. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: malformed_body: $ref: '#/components/examples/ErrorRequestBodyInvalid' missing_idempotency_key: $ref: '#/components/examples/ErrorParameterMissing' invalid_parameter: $ref: '#/components/examples/ErrorParameterInvalid' Unauthorized: description: > The API key is missing, invalid, expired, or revoked. Send the secret key for the intended merchant and mode in `Authorization: Bearer `. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: invalid_api_key: $ref: '#/components/examples/ErrorInvalidApiKey' PaymentForbidden: description: | The API key is valid, but the merchant cannot create this Payment. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: payment_acceptance_unavailable: $ref: '#/components/examples/ErrorPaymentAcceptanceUnavailable' HppConflict: description: | The `Idempotency-Key` is still being processed or was reused for a different Hosted Payment Page effective request identity. Retry the original operation with the same key and equivalent identity, or use a new key for a genuinely new Payment. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: idempotency_key_in_use: $ref: '#/components/examples/ErrorHppIdempotencyKeyInUse' idempotency_key_reused: $ref: '#/components/examples/ErrorHppIdempotencyKeyReused' PaymentUnprocessableEntity: description: | The Payment request passed basic validation, but its currency is not accepted or the merchant is not provisioned for the operation. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: currency_not_supported: $ref: '#/components/examples/ErrorPaymentCurrencyNotSupported' merchant_not_provisioned: $ref: '#/components/examples/ErrorMerchantNotProvisioned' InternalError: description: | Flowlix encountered an unexpected server error before the operation completed. Retry safely with the original idempotency key for a POST and include `Request-Id` when contacting support. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: internal_error: $ref: '#/components/examples/ErrorInternal' ServiceUnavailable: description: | Flowlix is temporarily unable to process the request. Wait for `Retry-After` when present, then retry with exponential backoff. Reuse the same idempotency key when retrying a POST request. headers: Request-Id: $ref: '#/components/headers/RequestId' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: service_unavailable: $ref: '#/components/examples/ErrorServiceUnavailable' securitySchemes: BearerAuth: type: http scheme: bearer description: | Use the secret API key for the intended merchant and mode as the Bearer token. Sandbox keys start with `api_test_sk_`. Send the key only from your server environment. ``` Authorization: Bearer api_test_sk_abc123def456 ``` ````