> ## Documentation Index > Fetch the complete documentation index at: https://docs.flowlix.eu/llms.txt > Use this file to discover all available pages before exploring further. # Payouts > Create card payouts and track their processing and final result Use the Payout API to submit funds to an eligible Visa or Mastercard. Payouts are available through server-to-server Direct API requests. This is not shopper 3D Secure: a Payout never sends the recipient through a browser challenge or return URL. ## Recommended flow 1. `POST /v1/payouts` with a unique `Idempotency-Key` and store the returned Payout ID. 2. `GET /v1/payouts/{payout_id}` when you need the latest state recorded by Flowlix. 3. Use `GET /v1/payouts` to reconcile payouts and page or filter the result. 4. Subscribe to the four [Payout webhooks](/guides/webhooks) to receive lifecycle changes. Retrieve the Payout when reconciling delayed or out-of-order events. ## Create a Payout Send card data only from your secure server environment: ```bash theme={null} curl -X POST https://api.flowlix.eu/v1/payouts \ -H "Authorization: Bearer $FLOWLIX_API_KEY" \ -H "Idempotency-Key: payout-ord_5678-1" \ -H "Content-Type: application/json" \ -d '{ "amount": 2500, "currency": "EUR", "merchant_reference": 1234567890, "destination": { "card_number": "4111111111111111" }, "initiator_ip_address": "203.0.113.7", "recipient": { "country": "DE", "first_name": "Jenny", "last_name": "Rosen" } }' ``` The card number in this request is a payload shape example only. It does not guarantee Payout eligibility or any particular outcome. Replace it with test data supplied for your current Sandbox account. Amounts use minor units. `initiator_ip_address` is the IP address of the human initiating the Payout. `recipient.country`, first and last names are required. Each name must contain a non-whitespace character and be 1–255 characters long. Names are preserved as submitted; do not rely on trimming or normalization. The response is `201 Created` with a Payout object. Store its `id`, masked destination summary, `status`, and timestamps. A `201` response acknowledges the Payout submission; interpret the status using the table below. Every returned Payout includes both recipient names as strings, including reads and webhook snapshots. A provider rate limit or another uncertain provider response is recorded as a `201` Payout with `status: PENDING`, not as a retryable provider HTTP error. Store the Payout ID and retrieve its latest recorded state; do not resubmit it with a new key. ## List Payouts ```bash theme={null} curl "https://api.flowlix.eu/v1/payouts?limit=20&status=PROCESSING¤cy=EUR" \ -H "Authorization: Bearer $FLOWLIX_API_KEY" ``` The list is merchant-scoped and ordered newest first. It supports: * literal, case-insensitive `search` across Payout IDs, merchant references, and recipient names; exactly four digits also match the destination card's last four digits; * cursor pagination with `starting_after` or `ending_before`; * repeated `status`, `currency`, and `card_brand` filters; * `card_last4`, creation-time, and amount-range filters. With exactly one currency filter, `search` also matches an exact major-unit amount. For example, `search=49.99¤cy=EUR` matches `amount: 4999`. A decimal comma is accepted. Without one currency, numeric search matches only text or the card's last four digits. `%` and `_` are literal characters, not wildcards; all structured filters still constrain the results. For the next page, pass the last returned Payout `id` as `starting_after`. For a previous page, pass the first returned Payout `id` as `ending_before`. The response does not contain separate cursor fields. `total_count` is the number of matching Payouts before cursor pagination. ## Retrieve a Payout ```bash theme={null} curl https://api.flowlix.eu/v1/payouts/po_7Qr3Lm9Ns2Vx6Za8Bc4Df1Gh \ -H "Authorization: Bearer $FLOWLIX_API_KEY" ``` The ID is scoped to the authenticated merchant and mode. Use the returned Payout as the latest recorded state. Retrieval does not itself advance the Payout. ## Payout statuses Payouts have two nonterminal states and two terminal states: | Status | What it means | What you should do | | ------------ | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `PENDING` | Flowlix accepted the request; the result has not yet been established. | Keep it pending and follow events or retrieve its current state. Do not create another Payout for the same intent. | | `PROCESSING` | The provider acknowledged the submission. `PROCESSING` does not confirm delivery or settlement. | Continue tracking the existing Payout. | | `SUCCEEDED` | The provider's final successful result has been recorded. | Mark the Payout successful. | | `FAILED` | A definitive failure has been recorded. | Use `failure_code` and `failure_message`. Retain the Payout ID and the `Request-Id` response header; contact support if the result is unexpected. | A Payout can move directly from `PENDING` to a terminal state; you do not need to observe `PROCESSING` first. There is no guaranteed completion deadline. The Payout result is not a separate banking-settlement receipt. Every response includes the recipient summary and masked destination. The `failure_code` and `failure_message` fields are returned only for `FAILED` and omitted in other states. These are public operation-failure fields, not the HTTP `error.code` envelope or raw provider details. ## Retry safely If the create request times out or returns a retryable HTTP error, retry only while the same destination card data remains available inside your approved PCI handling boundary. Preserve the same `Idempotency-Key` and an equivalent effective request identity, but do not persist the complete card-data body for retries. Never substitute a new key just because the response was lost. Use a new key only for a distinct business Payout. A same-key retry returns the saved creation response, which can still show `PROCESSING` after the Payout has completed. Use `GET /v1/payouts/{payout_id}` to read the current state; replaying POST is not polling. See [Idempotency](/guides/idempotency) and [operation failures](/guides/operation-failures) for conflict and error handling.