> ## 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. # 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. Payout currency eligibility is independent of the set of supported currencies for new Payments and Refunds. The Payout request still uses a three-letter ISO 4217 code, validated for Payouts when submitted. ## 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 a synthetic test number in Sandbox; never send a real card. 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. Flowlix makes bounded retries of eligible provider failures. If preparation still fails before execution was sent, the Payout can be `FAILED` with `processor_unavailable` or `processor_error`; this is not an issuer decline. If execution may have reached the provider, Flowlix reads the existing order to reconcile the result. The create response can already contain a terminal result, or remain `PENDING` or `PROCESSING` when it is unresolved. An unavailable provider read alone does not establish failure. 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. Percent-encode query values: `search=%25%25` searches for literal `%%`, and `search=%5F%5F` searches for literal `__`. Malformed percent escapes return `400 parameter_invalid`; correct the encoding before retrying. 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.