> ## 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 Direct API payment

> Creates a payment using exactly one merchant-facing payment method.
Submit ordinary card details under `payment_method_data.card`, or submit
a prepared decrypted Apple Pay or Google Pay credential under its wallet
object. Google Pay PAN_ONLY also requires `browser_information`. The
shopper IP belongs in `customer_ip_address`; optional payer identity or
billing data may be supplied when the merchant has it.

Apple Pay and Google Pay are Experimental: their support and this
guidance are still being refined and are not final, and the wallet
fields and validation described here can change. Ordinary `card`
requests are not affected. See
[wallet contract availability](/guides/direct-api#wallet-contract-availability).

The card number illustrates payload shape only. It does not guarantee a
successful, declined, or 3D Secure outcome. In Sandbox the outcome comes
from the amount, not from the card: see
[Sandbox testing](/guides/testing#choose-the-outcome-with-the-amount).

Every new Direct Payment goes through server-side authentication. The
response contains the payment attempt status after bounded eligible
provider retries. Exhausted preparation before execution can return
`FAILED` with `processor_unavailable` or `processor_error`, not an issuer
decline. Uncertain execution is reconciled against the existing order;
technical read failures alone leave the payment nonterminal. If the
status is `REQUIRES_ACTION`, a browser action is required: redirect the customer to
`next_action.redirect_url` for the `next_action.reason` customer action,
then use `GET /v1/payments/{id}` as the source of truth for the final
result. Required-action redirect URLs are opaque and may change
while the payment is still `REQUIRES_ACTION`; redirect the customer again
only when the latest `next_action.redirect_url` differs from the one that
browser already visited.

`return_url` is required. Use an HTTPS URL; reaching it never proves
payment success.

New Direct 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 without
creating duplicate charges.




## OpenAPI

````yaml /api-reference/payments-api.yaml post /v1/payments
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:
    post:
      tags:
        - Payments
      summary: Create a Direct API payment
      description: >
        Creates a payment using exactly one merchant-facing payment method.

        Submit ordinary card details under `payment_method_data.card`, or submit

        a prepared decrypted Apple Pay or Google Pay credential under its wallet

        object. Google Pay PAN_ONLY also requires `browser_information`. The

        shopper IP belongs in `customer_ip_address`; optional payer identity or

        billing data may be supplied when the merchant has it.


        Apple Pay and Google Pay are Experimental: their support and this

        guidance are still being refined and are not final, and the wallet

        fields and validation described here can change. Ordinary `card`

        requests are not affected. See

        [wallet contract
        availability](/guides/direct-api#wallet-contract-availability).


        The card number illustrates payload shape only. It does not guarantee a

        successful, declined, or 3D Secure outcome. In Sandbox the outcome comes

        from the amount, not from the card: see

        [Sandbox testing](/guides/testing#choose-the-outcome-with-the-amount).


        Every new Direct Payment goes through server-side authentication. The

        response contains the payment attempt status after bounded eligible

        provider retries. Exhausted preparation before execution can return

        `FAILED` with `processor_unavailable` or `processor_error`, not an
        issuer

        decline. Uncertain execution is reconciled against the existing order;

        technical read failures alone leave the payment nonterminal. If the

        status is `REQUIRES_ACTION`, a browser action is required: redirect the
        customer to

        `next_action.redirect_url` for the `next_action.reason` customer action,

        then use `GET /v1/payments/{id}` as the source of truth for the final

        result. Required-action redirect URLs are opaque and may change

        while the payment is still `REQUIRES_ACTION`; redirect the customer
        again

        only when the latest `next_action.redirect_url` differs from the one
        that

        browser already visited.


        `return_url` is required. Use an HTTPS URL; reaching it never proves

        payment success.


        New Direct 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 without

        creating duplicate charges.
      operationId: createDirectPayment
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDirectPaymentRequest'
            examples:
              basic:
                summary: Direct Payment payload shape
                value:
                  amount: 4999
                  currency: EUR
                  merchant_reference: 1234567890
                  payment_method_data:
                    type: card
                    card:
                      number: '4635440000002207'
                      exp_month: 12
                      exp_year: 2027
                      cvc: '314'
                      holder_name: Jenny Rosen
                  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
                  description: 'Order #1234'
                  return_url: https://merchant.example/payments/return
              apple_pay:
                summary: Decrypted Apple Pay
                description: >-
                  Synthetic payload for illustrating the contract, not a usable
                  wallet credential.
                value:
                  amount: 1000
                  currency: EUR
                  customer_ip_address: 192.0.2.10
                  merchant_customer_id: cust_opaque_42
                  return_url: https://merchant.example/payments/return
                  payment_method_data:
                    type: apple_pay
                    apple_pay:
                      format: decrypted
                      data:
                        card:
                          number: '4635440000002207'
                          exp_month: 12
                          exp_year: 2028
                          holder_name: Test Payer
                        cryptogram: c3ludGhldGljLWNyZWRlbnRpYWw=
                        eci: '05'
              google_pay_pan_only:
                summary: Decrypted Google Pay PAN_ONLY
                description: >-
                  Synthetic payload. Supply actual browser values and payer IP
                  for a real payment.
                value:
                  amount: 1000
                  currency: EUR
                  customer_ip_address: 192.0.2.10
                  merchant_customer_id: cust_opaque_42
                  return_url: https://merchant.example/payments/return
                  payment_method_data:
                    type: google_pay
                    google_pay:
                      format: decrypted
                      data:
                        auth_method: PAN_ONLY
                        card:
                          number: '4635440000002207'
                          exp_month: 12
                          exp_year: 2028
                          holder_name: Test Payer
                  browser_information:
                    accept_header: >-
                      text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
                    javascript_enabled: true
                    screen_width: 1920
                    screen_height: 1080
                    color_depth: 24
                    user_agent: >-
                      Mozilla/5.0 (Windows NT 10.0; Win64; x64)
                      AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0
                      Safari/537.36
                    language: en-US
                    time_zone_offset: -120
                    java_enabled: false
              google_pay_cryptogram:
                summary: Decrypted Google Pay CRYPTOGRAM_3DS
                description: >-
                  Synthetic payload for illustrating the contract, not a usable
                  wallet credential.
                value:
                  amount: 1000
                  currency: EUR
                  customer_ip_address: 192.0.2.10
                  merchant_customer_id: cust_opaque_42
                  return_url: https://merchant.example/payments/return
                  payment_method_data:
                    type: google_pay
                    google_pay:
                      format: decrypted
                      data:
                        auth_method: CRYPTOGRAM_3DS
                        card:
                          number: '4635440000002207'
                          exp_month: 12
                          exp_year: 2028
                          holder_name: Test Payer
                        cryptogram: c3ludGhldGljLWNyZWRlbnRpYWw=
                        eci: '05'
      responses:
        '201':
          description: >
            Payment accepted and a Payment object was created. Check `status`

            before treating the payment as complete; `REQUIRES_ACTION` includes

            `next_action.reason` and `next_action.redirect_url`, while

            `PENDING` or `PROCESSING` should be followed with `GET
            /v1/payments/{id}`.

            Reconciliation can already have confirmed a terminal result.

            `FAILED` is a terminal Payment result, not an HTTP request error.
          headers:
            Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
              examples:
                processing:
                  $ref: '#/components/examples/DirectPaymentProcessing'
                requires_action:
                  $ref: '#/components/examples/DirectPaymentRequiresAction'
                failed:
                  $ref: '#/components/examples/DirectPaymentFailed'
        '400':
          $ref: '#/components/responses/CreateBadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/PaymentForbidden'
        '404':
          $ref: '#/components/responses/DirectPaymentNotFound'
        '409':
          $ref: '#/components/responses/DirectConflict'
        '422':
          $ref: '#/components/responses/PaymentUnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '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:
    CreateDirectPaymentRequest:
      type: object
      additionalProperties: false
      not:
        required:
          - payment_method_data
        properties:
          payment_method_data:
            type: object
            required:
              - google_pay
            properties:
              google_pay:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - auth_method
                    properties:
                      auth_method:
                        type: string
                        pattern: ^PAN_ONLY$
        not:
          type: object
          required:
            - browser_information
          properties:
            browser_information:
              $ref: '#/components/schemas/BrowserInformationInput'
      required:
        - amount
        - currency
        - payment_method_data
        - 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: 4999
        currency:
          $ref: '#/components/schemas/CurrencyInput'
        merchant_reference:
          $ref: '#/components/schemas/MerchantReference'
        payment_method_data:
          $ref: '#/components/schemas/PaymentMethodDataInput'
        browser_information:
          $ref: '#/components/schemas/BrowserInformationInput'
        customer_ip_address:
          $ref: '#/components/schemas/CustomerIpAddress'
        merchant_customer_id:
          $ref: '#/components/schemas/MerchantCustomerId'
        billing_details:
          $ref: '#/components/schemas/DirectPaymentBillingDetailsInput'
        description:
          type: string
          nullable: true
          maxLength: 500
          description: Merchant-provided payment description.
          example: 'Order #1234'
        return_url:
          type: string
          format: uri
          description: >-
            Send the HTTPS URL where the customer returns after 3D Secure
            authentication.
          example: https://shop.example.com/3ds-return
    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.
    BrowserInformationInput:
      type: object
      additionalProperties: false
      description: |
        Actual payer-browser information, not the caller server's environment.
        Required for the Experimental Google Pay PAN_ONLY method and optional
        for other direct methods.
        When supplied, it is sent as transient provider authentication and risk
        context; it does not prove that a challenge occurred or that a Payment
        succeeded. The existing customer_ip_address supplies the payer browser
        IP, so no second browser-IP field is accepted.
        When supplied, all nine fields are required; do not fabricate missing
        browser values.
      required:
        - accept_header
        - javascript_enabled
        - screen_width
        - screen_height
        - color_depth
        - user_agent
        - language
        - time_zone_offset
        - java_enabled
      properties:
        accept_header:
          type: string
          minLength: 1
          maxLength: 2048
          description: >-
            Payer browser's HTTP `Accept` header, used as provider browser
            context.
          example: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
        javascript_enabled:
          type: boolean
          description: >-
            Whether JavaScript was enabled in the payer browser when the browser
            values were collected.
          example: true
        screen_width:
          type: integer
          minimum: 1
          maximum: 32768
          description: >-
            Payer browser screen width in CSS pixels, used as provider browser
            context.
          example: 1920
        screen_height:
          type: integer
          minimum: 1
          maximum: 32768
          description: >-
            Payer browser screen height in CSS pixels, used as provider browser
            context.
          example: 1080
        color_depth:
          type: integer
          minimum: 1
          maximum: 64
          description: >-
            Payer browser display color depth in bits, used as provider browser
            context.
          example: 24
        user_agent:
          type: string
          minLength: 1
          maxLength: 2048
          description: Payer browser user-agent value, used as provider browser context.
          example: >-
            Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML,
            like Gecko) Chrome/128.0.0.0 Safari/537.36
        language:
          type: string
          minLength: 1
          maxLength: 35
          description: Payer browser preferred language, used as provider browser context.
          example: en-US
        time_zone_offset:
          type: integer
          minimum: -840
          maximum: 840
          description: >-
            Payer browser timezone offset, expressed as UTC minus local time in
            minutes, as returned by JavaScript Date.getTimezoneOffset().
          example: -120
        java_enabled:
          type: boolean
          description: >-
            Whether the payer browser reported Java support when the browser
            values were collected.
          example: false
    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
    PaymentMethodDataInput:
      description: >
        Select exactly one payment method. Card, decrypted Apple Pay, and

        decrypted Google Pay are supported by this direct-payment contract.

        The selected method determines which credential fields are accepted;

        credentials are never inferred from another method's fields.


        The `apple_pay` and `google_pay` methods are Experimental: their support

        and this guidance are still being refined and are not final, and their

        fields and validation can change. The `card` method is not affected. See

        [wallet contract
        availability](/guides/direct-api#wallet-contract-availability).
      oneOf:
        - $ref: '#/components/schemas/CardPaymentMethodDataInput'
        - $ref: '#/components/schemas/ApplePayPaymentMethodDataInput'
        - $ref: '#/components/schemas/GooglePayPaymentMethodDataInput'
      discriminator:
        propertyName: type
        mapping:
          card: '#/components/schemas/CardPaymentMethodDataInput'
          apple_pay: '#/components/schemas/ApplePayPaymentMethodDataInput'
          google_pay: '#/components/schemas/GooglePayPaymentMethodDataInput'
    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
    DirectPaymentBillingDetailsInput:
      type: object
      additionalProperties: false
      description: Optional payer contact and billing-address details for a direct payment.
      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'
    CardPaymentMethodDataInput:
      type: object
      additionalProperties: false
      required:
        - type
        - card
      properties:
        type:
          type: string
          pattern: ^card$
          description: >-
            Merchant-facing payment method. Selects ordinary card validation and
            execution; it is not inferred from the card number or network.
          example: card
        card:
          $ref: '#/components/schemas/CardInput'
    ApplePayPaymentMethodDataInput:
      type: object
      additionalProperties: false
      description: >
        Experimental. Apple Pay direct payment method. Its support and this

        guidance are still being refined and are not final, and the fields and

        validation below can change. See

        [wallet contract
        availability](/guides/direct-api#wallet-contract-availability).
      required:
        - type
        - apple_pay
      properties:
        type:
          type: string
          pattern: ^apple_pay$
          description: >-
            Experimental merchant-facing payment method. Selects Apple Pay
            validation and provider execution; it is not inferred from the card
            number or network. Apple Pay support is still being refined and is
            not final.
          example: apple_pay
        apple_pay:
          $ref: '#/components/schemas/ApplePayInput'
    GooglePayPaymentMethodDataInput:
      type: object
      additionalProperties: false
      description: >
        Experimental. Google Pay direct payment method. Its support and this

        guidance are still being refined and are not final, and the fields and

        validation below can change. See

        [wallet contract
        availability](/guides/direct-api#wallet-contract-availability).
      required:
        - type
        - google_pay
      properties:
        type:
          type: string
          pattern: ^google_pay$
          description: >-
            Experimental merchant-facing payment method. Selects Google Pay
            validation and provider execution; it is not inferred from the card
            number or network. Google Pay support is still being refined and is
            not final.
          example: google_pay
        google_pay:
          $ref: '#/components/schemas/GooglePayInput'
    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.
    CardInput:
      type: object
      additionalProperties: false
      required:
        - number
        - exp_month
        - exp_year
        - cvc
        - holder_name
      properties:
        number:
          type: string
          pattern: ^[0-9]{13,19}$
          description: Card number as digits only.
          example: '4635440000002207'
        exp_month:
          type: integer
          minimum: 1
          maximum: 12
          description: Card expiration month.
          example: 12
        exp_year:
          type: integer
          maximum: 2099
          description: >-
            Card expiration year. Cards expiring in the past are rejected by
            downstream payment systems.
          example: 2027
        cvc:
          type: string
          pattern: ^[0-9]{3,4}$
          description: Card security code.
          example: '314'
        holder_name:
          type: string
          minLength: 1
          maxLength: 255
          description: Cardholder name as printed on the card.
          example: Jenny Rosen
    ApplePayInput:
      description: |
        Experimental Apple Pay wallet input; its support and this guidance are
        still being refined and are not final. `format: decrypted` contains
        prepared typed fields from an enabled upstream wallet integration.
        `format: encrypted` is a separate opaque representation and is rejected
        by this release; do not infer the format from field presence.
      oneOf:
        - $ref: '#/components/schemas/DecryptedApplePayInput'
        - $ref: '#/components/schemas/EncryptedWalletInput'
      discriminator:
        propertyName: format
        mapping:
          decrypted: '#/components/schemas/DecryptedApplePayInput'
          encrypted: '#/components/schemas/EncryptedWalletInput'
    GooglePayInput:
      description: |
        Experimental Google Pay wallet input; its support and this guidance are
        still being refined and are not final. `format: decrypted` contains
        prepared typed fields from an enabled upstream wallet integration.
        `format: encrypted` is a separate opaque representation and is rejected
        by this release; do not infer the format from field presence.
      oneOf:
        - $ref: '#/components/schemas/DecryptedGooglePayInput'
        - $ref: '#/components/schemas/EncryptedWalletInput'
      discriminator:
        propertyName: format
        mapping:
          decrypted: '#/components/schemas/DecryptedGooglePayInput'
          encrypted: '#/components/schemas/EncryptedWalletInput'
    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
    DecryptedApplePayInput:
      type: object
      additionalProperties: false
      required:
        - format
        - data
      properties:
        format:
          type: string
          pattern: ^decrypted$
          description: >-
            The wallet credential has already been prepared into the typed
            `data` fields by the enabled upstream integration. This value
            selects the decrypted contract and is not inferred from the fields.
          example: decrypted
        data:
          $ref: '#/components/schemas/DecryptedApplePayData'
    EncryptedWalletInput:
      type: object
      additionalProperties: false
      description: |
        Encrypted wallet submissions are reserved for a later provider contract
        and are rejected before payment registration. Token serialization is not
        accepted by this version of the direct-payment API.
      required:
        - format
        - data
      properties:
        format:
          type: string
          pattern: ^encrypted$
          description: >-
            The wallet credential is represented as one opaque encrypted
            payload. This format is documented for forward compatibility but is
            rejected by the current direct-payment contract.
          example: encrypted
        data:
          $ref: '#/components/schemas/EncryptedWalletData'
    DecryptedGooglePayInput:
      type: object
      additionalProperties: false
      required:
        - format
        - data
      properties:
        format:
          type: string
          pattern: ^decrypted$
          description: >-
            The wallet credential has already been prepared into the typed
            `data` fields by the enabled upstream integration. This value
            selects the decrypted contract and is not inferred from the fields.
          example: decrypted
        data:
          $ref: '#/components/schemas/DecryptedGooglePayData'
    DecryptedApplePayData:
      type: object
      additionalProperties: false
      description: |
        Apple Pay 3DSecure credential shape supported by this contract. Fill
        `card` and `cryptogram` from the same prepared, verified wallet
        credential, and pass `eci` when that credential supplies it. EMV and
        China UnionPay input are not supported.
      required:
        - card
        - cryptogram
      properties:
        card:
          $ref: '#/components/schemas/WalletCardInput'
        cryptogram:
          $ref: '#/components/schemas/WalletCryptogram'
        eci:
          $ref: '#/components/schemas/WalletEci'
    EncryptedWalletData:
      type: object
      additionalProperties: false
      required:
        - token
      properties:
        token:
          type: string
          minLength: 1
          maxLength: 65536
          description: >-
            Opaque encrypted wallet payload. This representation is reserved and
            rejected by the current direct-payment contract; never log or store
            it.
          example: synthetic-wallet-token
    DecryptedGooglePayData:
      description: |
        Explicit authentication method from the prepared Google Pay credential.
        `auth_method` is required and case-sensitive. `PAN_ONLY` requires the
        request browser information and forbids cryptogram and ECI; it enters
        the provider's PAN/3DS branch. `CRYPTOGRAM_3DS` requires a cryptogram
        and accepts ECI when supplied. The value is never inferred from the
        presence or absence of a cryptogram and does not predict whether a
        customer challenge will occur.
      oneOf:
        - $ref: '#/components/schemas/GooglePayPanOnlyData'
        - $ref: '#/components/schemas/GooglePayCryptogramData'
      discriminator:
        propertyName: auth_method
        mapping:
          PAN_ONLY: '#/components/schemas/GooglePayPanOnlyData'
          CRYPTOGRAM_3DS: '#/components/schemas/GooglePayCryptogramData'
    WalletCardInput:
      type: object
      additionalProperties: false
      required:
        - number
        - exp_month
        - exp_year
      properties:
        number:
          type: string
          pattern: ^[0-9]{13,19}$
          description: >-
            Required PAN or device PAN from the same prepared wallet credential
            as the expiry. It identifies the wallet card for provider
            authorization; it is sensitive and must never be exposed in logs or
            payment resources.
          example: '4635440000002207'
        exp_month:
          type: integer
          minimum: 1
          maximum: 12
          description: >-
            Required numeric expiration month from the same prepared wallet
            credential. Do not replace it with a card-form value from another
            source.
          example: 12
        exp_year:
          type: integer
          maximum: 2099
          description: >-
            Required four-digit expiration year from the same prepared wallet
            credential. Do not replace it with a card-form value from another
            source.
          example: 2028
        holder_name:
          type: string
          minLength: 1
          maxLength: 255
          description: >-
            Optional cardholder name when the prepared wallet credential
            supplies it. It is informational and does not replace the wallet
            authentication fields.
          example: Test Payer
    WalletCryptogram:
      type: string
      minLength: 28
      maxLength: 28
      pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
      description: >-
        Exactly 28 standard Base64 characters from the prepared wallet
        credential. Required for Apple 3DSecure and Google CRYPTOGRAM_3DS,
        passed to the provider unchanged, and never generated from card fields
        or substituted with CVC. Its presence is authentication context, not a
        successful payment result.
      example: c3ludGhldGljLWNyZWRlbnRpYWw=
    WalletEci:
      type: string
      minLength: 2
      maxLength: 2
      pattern: ^[0-9]{2}$
      description: |
        Optional Electronic Commerce Indicator for Apple 3DSecure and Google
        CRYPTOGRAM_3DS. Omit the field when the prepared wallet credential does
        not supply it. When supplied, pass exactly two decimal digits unchanged
        to preserve the network authentication context; it may affect
        authorization processing but is not a success signal. Never infer,
        pad, trim or convert it to a number.
      example: '05'
    GooglePayPanOnlyData:
      type: object
      additionalProperties: false
      description: >-
        PAN_ONLY is a prepared Google Pay credential without a wallet
        cryptogram. It requires `browser_information` on the direct request so
        the provider can perform its PAN/3DS browser checks; the issuer may
        complete frictionlessly or require a customer challenge. Cryptogram and
        ECI are forbidden for this branch.
      required:
        - auth_method
        - card
      properties:
        auth_method:
          type: string
          pattern: ^PAN_ONLY$
          description: >-
            Preserve the authentication-method value from the prepared Google
            Pay credential. It selects the PAN_ONLY provider branch and is not a
            3DS outcome.
          example: PAN_ONLY
        card:
          $ref: '#/components/schemas/WalletCardInput'
    GooglePayCryptogramData:
      type: object
      additionalProperties: false
      description: >-
        CRYPTOGRAM_3DS is a prepared Google Pay device-token credential. The
        cryptogram is required and ECI is forwarded when supplied; the name does
        not guarantee a browser challenge.
      required:
        - auth_method
        - card
        - cryptogram
      properties:
        auth_method:
          type: string
          pattern: ^CRYPTOGRAM_3DS$
          description: >-
            Preserve the authentication-method value from the prepared Google
            Pay credential. It selects the CRYPTOGRAM_3DS provider branch and is
            not a 3DS outcome.
          example: CRYPTOGRAM_3DS
        card:
          $ref: '#/components/schemas/WalletCardInput'
        cryptogram:
          $ref: '#/components/schemas/WalletCryptogram'
        eci:
          $ref: '#/components/schemas/WalletEci'
  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:
    DirectPaymentProcessing:
      summary: Direct Payment is processing without a browser action
      value:
        id: pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E
        amount: 4999
        currency: EUR
        status: PROCESSING
        integration_type: DIRECT
        merchant_reference: 1234567890
        description: 'Order #1234'
        payment_method:
          type: card
          card:
            brand: visa
            last4: '2207'
            exp_month: 12
            exp_year: 2027
            cardholder_name: Jenny Rosen
        amount_refunded: 0
        amount_refundable: 0
        refunds: []
        status_transitions:
          processing_at: 1719792002
        created_at: 1719792000
        livemode: false
    DirectPaymentRequiresAction:
      summary: Direct Payment requires a 3D Secure browser action
      value:
        id: pay_r8Ln3Oq9Ws5Yu7Za0Bc4De6F
        amount: 4999
        currency: EUR
        status: REQUIRES_ACTION
        integration_type: DIRECT
        merchant_reference: 1234567890
        description: 'Order #1234'
        payment_method:
          type: card
          card:
            brand: visa
            last4: '2207'
            exp_month: 12
            exp_year: 2027
            cardholder_name: Jenny Rosen
        amount_refunded: 0
        amount_refundable: 0
        refunds: []
        status_transitions:
          requires_action_at: 1719792002
        created_at: 1719792000
        livemode: false
        next_action:
          type: redirect
          reason: three_d_secure
          redirect_url: https://authentication.example/redirect-token
    DirectPaymentFailed:
      summary: Direct Payment ended in a terminal decline
      value:
        id: pay_u1Oq6Rt2Zv8Bx0Cd3Ef7Gh9J
        amount: 4999
        currency: EUR
        status: FAILED
        integration_type: DIRECT
        merchant_reference: 1234567890
        description: 'Order #1234'
        payment_method:
          type: card
          card:
            brand: visa
            last4: '2207'
            exp_month: 12
            exp_year: 2027
            cardholder_name: Jenny Rosen
        failure_code: insufficient_funds
        failure_message: The card has insufficient funds.
        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
    ErrorDirectPaymentNotFound:
      summary: Direct Payment state is unavailable during creation
      value:
        error:
          code: object_not_found
          message: >-
            The Payment could not be found while the request was being
            completed.
          doc_url: https://docs.flowlix.eu/api-reference/errors
          request_id: req_direct404a
    ErrorDirectIdempotencyKeyInUse:
      summary: Original Direct Payment request is still processing
      value:
        error:
          code: idempotency_key_in_use
          message: >-
            The original direct payment request for pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E
            is still processing for this idempotency key.
          param: Idempotency-Key
          doc_url: https://docs.flowlix.eu/api-reference/errors
          request_id: req_direct409a
    ErrorDirectIdempotencyKeyReused:
      summary: Direct Payment key was reused for a different effective identity
      value:
        error:
          code: idempotency_key_reused
          message: >-
            Idempotency key was already used for direct payment
            pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E with different request parameters.
          param: Idempotency-Key
          doc_url: https://docs.flowlix.eu/api-reference/errors
          request_id: req_direct409b
    ErrorDirectObjectStateConflict:
      summary: Direct Payment state conflicts with the requested transition
      value:
        error:
          code: object_state_conflict
          message: The Payment cannot accept this update in its current state.
          doc_url: https://docs.flowlix.eu/api-reference/errors
          request_id: req_direct409c
    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
    ErrorRateLimitExceeded:
      summary: Direct Payment provider rate limit
      value:
        error:
          code: rate_limit_exceeded
          message: Request rate exceeded. Please retry later.
          doc_url: https://docs.flowlix.eu/guides/errors
          request_id: req_rate429a
    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
    ErrorProcessing:
      summary: Direct Payment provider response is unsafe to accept
      value:
        error:
          code: processing_error
          message: A processing error occurred. Please retry.
          doc_url: https://docs.flowlix.eu/guides/errors
          request_id: req_process502a
    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'
    DirectPaymentNotFound:
      description: |
        Flowlix could not find state registered while creating this Direct
        Payment. Preserve the same idempotency key, retain `request_id`, and
        contact support before attempting a different card or key.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          examples:
            object_not_found:
              $ref: '#/components/examples/ErrorDirectPaymentNotFound'
    DirectConflict:
      description: |
        The `Idempotency-Key` is still being processed, was reused for a
        different Direct Payment identity, or the Payment state conflicts with
        the requested transition. Card fields are excluded from the identity:
        unchanged non-card fields replay the original Payment, and a new card
        attempt requires a new key. Card-data retries must follow the PCI-safe
        guidance in the Idempotency guide.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          examples:
            idempotency_key_in_use:
              $ref: '#/components/examples/ErrorDirectIdempotencyKeyInUse'
            idempotency_key_reused:
              $ref: '#/components/examples/ErrorDirectIdempotencyKeyReused'
            object_state_conflict:
              $ref: '#/components/examples/ErrorDirectObjectStateConflict'
    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'
    RateLimited:
      description: |
        The provider rate-limited this Direct Payment submission. Wait for
        `Retry-After` when present, then retry from the same PCI-safe attempt
        with the same idempotency key.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          examples:
            rate_limit_exceeded:
              $ref: '#/components/examples/ErrorRateLimitExceeded'
    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'
    BadGateway:
      description: |
        Flowlix could not validate a safe Direct Payment provider response.
        Preserve the same idempotency key and retry only from the same PCI-safe
        attempt while the original request remains available inside your
        approved PCI handling boundary; do not persist the raw card-data body
        for retries. Include the `Request-Id` if you contact support.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          examples:
            processing_error:
              $ref: '#/components/examples/ErrorProcessing'
    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.