> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ecomm365.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.

Optional `billing_details` are supplied by the merchant and forwarded for
the payment. The hosted card-entry page does not let shoppers edit these
billing details. The editable cardholder-name field is separate from the
billing profile.

`return_url` is an absolute HTTPS merchant URL with a valid hostname
or IP address, where the customer is sent after completing or abandoning
the hosted payment page. HTTP and other schemes are rejected before
Payment creation. Host validation checks syntax; no domain allowlist
or DNS lookup is applied. Return URL query
parameters are UX hints only; merchants must use
`GET /v1/payments/{id}` as the source of truth.

New hosted-page Payments require one of the
[supported payment currencies](/introduction#amounts-and-currencies).
A well-formed unsupported currency returns `422 currency_not_supported`
without creating a Payment. Existing Payments in other currencies remain
readable.

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** (exponent 2).

    Historical records can have other exponents: `4999` is **JPY 4999**

    (exponent 0, no minor unit). Independently supported Payout currencies

    also follow their ISO exponents. Do not assume two decimal places when

    reading stored records.


    Currencies are three-letter ISO 4217 codes. Requests are accepted

    case-insensitively; Flowlix normalizes them and always returns canonical

    uppercase codes such as `EUR`. New Direct and hosted-page Payments accept

    only `EUR` and `GBP`; Payout eligibility is independent and described by

    its own operation. 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. Existing Payments and Refunds

    in other currencies remain readable.


    A refund is always made in the currency of the original payment, and the

    refund request does not accept a currency. A new Refund is accepted only

    when that Payment's currency is supported for new Payments; an exact retry

    of an already created Refund can still return its original response.
  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.


        Optional `billing_details` are supplied by the merchant and forwarded
        for

        the payment. The hosted card-entry page does not let shoppers edit these

        billing details. The editable cardholder-name field is separate from the

        billing profile.


        `return_url` is an absolute HTTPS merchant URL with a valid hostname

        or IP address, where the customer is sent after completing or abandoning

        the hosted payment page. HTTP and other schemes are rejected before

        Payment creation. Host validation checks syntax; no domain allowlist

        or DNS lookup is applied. Return URL query

        parameters are UX hints only; merchants must use

        `GET /v1/payments/{id}` as the source of truth.


        New hosted-page Payments require one of the

        [supported payment currencies](/introduction#amounts-and-currencies).

        A well-formed unsupported currency returns `422 currency_not_supported`

        without creating a Payment. Existing Payments in other currencies remain

        readable.


        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
                  merchant_customer_id: cust_opaque_42
                  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
        - merchant_customer_id
        - return_url
      properties:
        amount:
          type: integer
          format: int64
          minimum: 1
          description: |
            Payment amount in the currency's minor units, using its ISO 4217
            exponent. For example, `4999` is EUR 49.99 (exponent 2).
          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
          nullable: true
          maxLength: 500
          description: Merchant-provided payment description.
          example: 'Order #5678'
        return_url:
          type: string
          format: uri
          description: >
            Absolute HTTPS merchant URL with a valid hostname or IP address,

            where the customer returns after hosted payment completion or

            abandonment. Parsed URIs with a different scheme or no valid host

            return `400 parameter_invalid` with `param: return_url` before

            Payment creation. Malformed URI text returns `400
            request_body_invalid`.

            Host validation checks syntax, without a domain allowlist or DNS
            lookup.
          example: https://shop.example.com/checkout/complete
    Payment:
      type: object
      additionalProperties: false
      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
        - payment_method
      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'
        payment_method:
          $ref: '#/components/schemas/PaymentMethodSummary'
        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'
        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. This is `0` unless `status`
            is `SUCCEEDED`, because no amount was captured on a payment that has
            not succeeded. For a `SUCCEEDED` payment it is the payment amount
            less anything already refunded or reserved for a refund in flight.
          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. For new Payment eligibility, see the

        [supported payment currencies](/introduction#amounts-and-currencies);

        Payout eligibility is independent.
      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
      x-flowlix-unicode-scalar-validation: true
      description: >-
        Stable merchant-scoped non-PII opaque identity. Reuse it for the same
        logical customer or recognized guest. Do not send an email, phone
        number, login, name, payment ID, order ID, attempt ID, fresh per-payment
        UUID, or any other fresh per-payment value. Case and whitespace are
        significant. The value must contain 1-255 Unicode scalar values, must be
        nonblank, and U+0000 is forbidden.
      example: cust_opaque_42
    BillingDetailsInput:
      type: object
      additionalProperties: false
      description: >
        Optional merchant-supplied payer contact and billing-address details for

        the payment. These details are not editable on the hosted card-entry
        page

        and are separate from the cardholder name.
      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
    PaymentMethodSummary:
      type: object
      nullable: true
      additionalProperties: false
      required:
        - type
      example:
        type: apple_pay
        card:
          brand: visa
          last4: '2207'
          exp_month: 12
          exp_year: 2028
      description: >
        Known submitted direct method or authoritative selected hosted-page

        method. Null means unknown, not card; the field is always present. This
        does not imply

        success. No wallet credentials or authentication payload is returned.


        The `apple_pay` and `google_pay` values are Experimental: wallet support

        and this guidance are still being refined and are not final. See

        [wallet contract
        availability](/guides/direct-api#wallet-contract-availability).
      properties:
        type:
          type: string
          minLength: 1
          maxLength: 64
          description: >-
            Known values are card, apple_pay and google_pay. Clients must
            tolerate future values. Wallet support for the apple_pay and
            google_pay values is Experimental; it is still being refined and is
            not final. The value strings themselves are stable.
          example: apple_pay
        card:
          $ref: '#/components/schemas/Card'
    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/CountryCodeInput'
    Card:
      type: object
      nullable: true
      additionalProperties: false
      description: >
        Masked card details. The entire `card` field may be omitted or `null`,

        including for a successful card payment. When present, the object
        contains

        all required fields: `brand`, `last4`, `exp_month`, and `exp_year`.

        Use `status` to determine the payment outcome independently of card
        details.
      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'
    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.
    CountryCodeInput:
      type: string
      pattern: >-
        ^(?:AD|AE|AF|AG|AI|AL|AM|AO|AQ|AR|AS|AT|AU|AW|AX|AZ|BA|BB|BD|BE|BF|BG|BH|BI|BJ|BL|BM|BN|BO|BQ|BR|BS|BT|BV|BW|BY|BZ|CA|CC|CD|CF|CG|CH|CI|CK|CL|CM|CN|CO|CR|CU|CV|CW|CX|CY|CZ|DE|DJ|DK|DM|DO|DZ|EC|EE|EG|EH|ER|ES|ET|FI|FJ|FK|FM|FO|FR|GA|GB|GD|GE|GF|GG|GH|GI|GL|GM|GN|GP|GQ|GR|GS|GT|GU|GW|GY|HK|HM|HN|HR|HT|HU|ID|IE|IL|IM|IN|IO|IQ|IR|IS|IT|JE|JM|JO|JP|KE|KG|KH|KI|KM|KN|KP|KR|KW|KY|KZ|LA|LB|LC|LI|LK|LR|LS|LT|LU|LV|LY|MA|MC|MD|ME|MF|MG|MH|MK|ML|MM|MN|MO|MP|MQ|MR|MS|MT|MU|MV|MW|MX|MY|MZ|NA|NC|NE|NF|NG|NI|NL|NO|NP|NR|NU|NZ|OM|PA|PE|PF|PG|PH|PK|PL|PM|PN|PR|PS|PT|PW|PY|QA|RE|RO|RS|RU|RW|SA|SB|SC|SD|SE|SG|SH|SI|SJ|SK|SL|SM|SN|SO|SR|SS|ST|SV|SX|SY|SZ|TC|TD|TF|TG|TH|TJ|TK|TL|TM|TN|TO|TR|TT|TV|TW|TZ|UA|UG|UM|US|UY|UZ|VA|VC|VE|VG|VI|VN|VU|WF|WS|YE|YT|ZA|ZM|ZW)$
      description: >-
        Uppercase assigned ISO 3166-1 alpha-2 country code. Reserved,
        user-assigned and withdrawn codes are rejected. This identifies the
        country; it does not establish commercial eligibility.
      example: DE
    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
  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
        payment_method: null
        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
        payment_method: null
        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
        payment_method: null
        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 USD 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 <key>`.
      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 in
        the [supported payment currencies](/introduction#amounts-and-currencies)
        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
        ```

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.