> ## 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.

# Introduction

> Integrate card payments, refunds, payouts, and payment notifications

The Flowlix Merchant API lets your server create and retrieve card payments,
refund succeeded payments, submit card payouts, and receive payment and refund
notifications. Start with a Sandbox integration using the Quickstart below.

<Warning>
  **Coordinated `/v1` payment cutover.** Both `POST /v1/payments` and
  `POST /v1/payments/hpp` require `merchant_customer_id`. Deploy this field
  before the coordinated activation. There is no `/v2` endpoint or
  compatibility window for this change.
</Warning>

<Warning>
  **Experimental: Apple Pay and Google Pay.** Wallet support and this guidance
  are still being refined and are not final. The current Direct API contract
  accepts prepared decrypted wallet credentials for enabled integrations;
  encrypted wallet input is documented but rejected in this release. Confirm
  the supported wallet route and provider setup with Flowlix before enabling a
  new merchant. See the [wallet input reference](/guides/direct-api#wallet-input-reference)
  for the current contract.
</Warning>

## Choose a payment integration

<CardGroup cols={2}>
  <Card title="Hosted Payment Page" icon="globe" href="/guides/hosted-payment-page">
    Redirect the customer to a Flowlix-hosted card form. Flowlix collects the
    card details and handles any required browser authentication.
  </Card>

  <Card title="Direct API" icon="server" href="/guides/direct-api">
    Collect card details in your own checkout and submit them from your server.
    This path requires a PCI-compliant card-data environment.
  </Card>
</CardGroup>

Both paths create the same Payment resource. Your server retrieves that
Payment for its current status and can receive [Webhooks](/guides/webhooks)
when it changes; the browser return is never the authoritative result.

Not sure which path fits? Use the [Quickstart chooser](/guides/quickstart).

## Base URL

All requests in this documentation use:

```text theme={null}
https://api.flowlix.eu
```

Endpoints are versioned under `/v1`, for example
`https://api.flowlix.eu/v1/payments`. Send the appropriate secret key from your
server on every authenticated request.

## Core resources

| Resource | What it represents | How you read the latest state |
| - | - | - |
| **Payment** | One attempt to collect funds from a customer. | `GET /v1/payments/{id}` or `GET /v1/payments`. |
| **Refund** | A full or partial return against a succeeded Payment. | Retrieve the parent Payment and inspect its `refunds` array. |
| **Payout** | One card payout submission. | `GET /v1/payouts/{payout_id}` or `GET /v1/payouts`. |

IDs such as `pay_...`, `ref_...`, and `po_...` are opaque. Store them; do not
derive business meaning from their characters.

## Amounts and currencies

Amounts are integers in the currency's minor units, using its ISO 4217
exponent. For example, `4999` is EUR 49.99 (exponent 2).
Other exponents can occur in historical Payment and Refund records: for
example, `4999` is JPY 4999. Payout currencies are independently supported
and follow their own ISO exponents. Do not assume every stored currency has
two decimal places.

Requests use three-letter ISO 4217 currency codes. Flowlix returns their
canonical uppercase form. New Direct and Hosted Payment Page Payments accept
only EUR and GBP. New Refunds inherit the original Payment currency and are
available only for Payments in the supported payment currencies. Payout
currencies are independent; see [Payouts](/guides/payouts).

## Customer identity on payment creation

Send `merchant_customer_id` on every Direct and Hosted Payment Page create.
It is your stable identifier for the logical customer or recognized guest
within one merchant, and you must reuse the same value for that customer.

Use an opaque, non-PII value such as `cust_opaque_42`. Never send an email,
phone number, login, name, order ID, Payment ID, payment-attempt ID, or a fresh
per-payment UUID. The value must be nonblank, contain 1–255 Unicode scalar
values, and contain no U+0000. Flowlix preserves it exactly: case and all
leading, internal, and trailing whitespace are significant.

An omitted or explicit-null value returns `400 request_body_invalid`; invalid
content returns `400 parameter_invalid`. Both errors use
`param: merchant_customer_id`. See [API errors](/guides/errors#required-payment-customer-identity).

## Start here

<Steps>
  <Step title="Configure your test key">
    Follow [Authentication](/guides/authentication) and keep the key in a
    server-side environment variable or secrets manager.
  </Step>

  <Step title="Create a test payment">
    Open the [Quickstart chooser](/guides/quickstart), then complete either the
    Hosted Payment Page or Direct API path.
  </Step>

  <Step title="Confirm the final status">
    Retrieve the Payment until it reaches `SUCCEEDED`, `FAILED`, or `EXPIRED`.
    See [Payment lifecycle](/guides/payment-lifecycle).
  </Step>

  <Step title="Continue your integration">
    Add [Refunds](/guides/refunds), [Payouts](/guides/payouts),
    [Webhooks](/guides/webhooks), and robust
    [error handling](/guides/errors).
  </Step>
</Steps>

## Support

Contact [developers@flowlix.eu](mailto:developers@flowlix.eu). Include the
`Request-Id` response header from the failed API call, but never include API
keys or raw card data.


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