Payouts

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

POST /v1/payouts with a unique Idempotency-Key and store the returned Payout ID.
GET /v1/payouts/{payout_id} when you need the latest state recorded by Flowlix.
Use GET /v1/payouts to reconcile payouts and page or filter the result.
Subscribe to the four Payout 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:

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

curl "https://api.flowlix.eu/v1/payouts?limit=20&status=PROCESSING&currency=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&currency=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

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 and operation failures for conflict and error handling.

Get started

Build with Flowlix

Handle failures

API reference

Recommended flow

Create a Payout

List Payouts

Retrieve a Payout

Payout statuses

Retry safely

​Recommended flow

​Create a Payout

​List Payouts

​Retrieve a Payout

​Payout statuses

​Retry safely

Recommended flow

Create a Payout

List Payouts

Retrieve a Payout

Payout statuses

Retry safely