> ## 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. # List card payouts > Returns merchant-scoped card payouts ordered newest first. `total_count` is the exact number matching the filters before cursor pagination. ## OpenAPI ````yaml /api-reference/payments-api.yaml get /v1/payouts 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** and **GBP 49.99** (exponent 2), but **JPY 4999** (exponent 0, no minor unit). Do not assume two decimal places. Currencies are three-letter ISO 4217 codes. Requests are accepted case-insensitively; Flowlix normalizes them and always returns canonical uppercase codes such as `EUR`. The currencies accepted for a Payment or Payout are validated separately per request rather than listed in this contract, so enabling another currency is not a breaking change. 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. A refund is always made in the currency of the original payment, and the refund request does not accept a currency. 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/payouts: get: tags: - Payouts summary: List card payouts description: | Returns merchant-scoped card payouts ordered newest first. `total_count` is the exact number matching the filters before cursor pagination. operationId: listPayouts parameters: - name: search in: query description: > Literal case-insensitive search over Payout IDs, merchant references, and recipient names. Exactly four digits also match the card's last four digits. With exactly one currency filter, a decimal amount also matches that exact major-unit amount: `search=49.99¤cy=EUR` matches an amount of 4999 minor units. A decimal comma is accepted. Without one currency, numeric search uses only the text/card fields. `%` and `_` are literal characters. Structured filters still apply. required: false schema: type: string minLength: 2 maxLength: 255 - name: limit in: query description: >- Maximum number of payouts to return. Accepts values between 1 and 100. required: false schema: type: integer minimum: 1 maximum: 100 default: 10 - name: starting_after in: query description: | Cursor for forward pagination. Provide the `id` of the last Payout in the previous page. Mutually exclusive with `ending_before`. required: false schema: $ref: '#/components/schemas/PayoutId' - name: ending_before in: query description: > Cursor for backward pagination. Provide the `id` of the first Payout in the current page. Mutually exclusive with `starting_after`. required: false schema: $ref: '#/components/schemas/PayoutId' - name: status in: query description: Repeat to filter by multiple aggregate payout statuses. required: false schema: type: array maxItems: 100 items: $ref: '#/components/schemas/PayoutStatus' style: form explode: true - name: currency in: query description: Repeat to filter by multiple uppercase ISO 4217 currency codes. required: false schema: type: array maxItems: 100 items: $ref: '#/components/schemas/CurrencyCode' style: form explode: true - name: card_brand in: query description: Repeat to filter by multiple canonical lower-case card brands. required: false schema: type: array maxItems: 100 items: $ref: '#/components/schemas/CardBrand' style: form explode: true - name: card_last4 in: query description: Exact last four digits of the destination card. required: false schema: type: string pattern: ^[0-9]{4}$ - name: created_gte in: query description: Return payouts created on or after this Unix timestamp in seconds. required: false schema: type: integer format: int64 minimum: 0 - name: created_lt in: query description: Return payouts created before this Unix timestamp in seconds. required: false schema: type: integer format: int64 minimum: 0 - name: amount_gte in: query description: >- Return payouts with amount greater than or equal to this minor-unit amount. required: false schema: type: integer format: int64 minimum: 0 - name: amount_lte in: query description: >- Return payouts with amount less than or equal to this minor-unit amount. required: false schema: type: integer format: int64 minimum: 0 responses: '200': description: Matching payouts, ordered newest first. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/PayoutList' examples: page: $ref: '#/components/examples/PayoutListPage' '400': $ref: '#/components/responses/PayoutListBadRequest' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailable' components: schemas: PayoutId: type: string pattern: ^po_[A-Za-z0-9]{24}$ description: >- Unique opaque public identifier for a payout (`po_` prefix + random alphanumeric suffix). example: po_Q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E PayoutStatus: type: string enum: - PENDING - PROCESSING - SUCCEEDED - FAILED description: > Merchant-visible payout state. `PROCESSING` means the provider acknowledged the payout. `SUCCEEDED` and `FAILED` are terminal outcomes confirmed from a validated provider result, not submission acknowledgement. example: PROCESSING 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 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 PayoutList: type: object additionalProperties: false required: - data - has_more - total_count properties: data: type: array description: One page of payouts ordered newest first. items: $ref: '#/components/schemas/Payout' has_more: type: boolean description: >- True when more payouts exist beyond this page in the requested direction. example: true total_count: type: integer format: int64 minimum: 0 description: >- Exact number of payouts matching the merchant, mode, and filters before cursor pagination. example: 125 Payout: type: object additionalProperties: false required: - id - amount - currency - status - card_brand - card_last4 - recipient - created_at - updated_at description: Public, PAN-free lifecycle representation of a card payout. properties: id: $ref: '#/components/schemas/PayoutId' amount: type: integer format: int64 minimum: 1 description: Payout amount in minor units. example: 2500 currency: $ref: '#/components/schemas/CurrencyCode' merchant_reference: type: integer nullable: true description: Merchant-side reconciliation reference, if supplied. allOf: - $ref: '#/components/schemas/MerchantReference' status: $ref: '#/components/schemas/PayoutStatus' failure_code: type: string allOf: - $ref: '#/components/schemas/OperationFailureCode' nullable: true description: >- Stable Flowlix reason present only for a FAILED payout; never a raw provider code. example: do_not_honor failure_message: type: string nullable: true minLength: 1 maxLength: 255 description: Merchant-safe explanation present only for a FAILED payout. example: The payout was declined by the issuer. card_brand: $ref: '#/components/schemas/CardBrand' card_last4: type: string pattern: ^[0-9]{4}$ description: Last four digits of the destination card. example: '1111' recipient: $ref: '#/components/schemas/PayoutRecipient' created_at: type: integer format: int64 description: Unix timestamp when the payout was created. example: 1719792000 updated_at: type: integer format: int64 description: Unix timestamp when the payout was last updated. example: 1719792060 ApiError: type: object description: Error response wrapper. properties: error: $ref: '#/components/schemas/ApiErrorBody' 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 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 PayoutRecipient: type: object additionalProperties: false required: - country - first_name - last_name description: Merchant-supplied recipient metadata stored with the payout. properties: country: $ref: '#/components/schemas/CountryCode' first_name: type: string minLength: 1 maxLength: 255 description: >- Merchant-supplied recipient first name, preserved without trimming or normalization. example: Jenny last_name: type: string minLength: 1 maxLength: 255 description: >- Merchant-supplied recipient last name, preserved without trimming or normalization. example: Rosen 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. CountryCode: type: string pattern: ^[A-Z]{2}$ description: Canonical ISO 3166-1 alpha-2 country code. example: DE 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: PayoutListPage: summary: Page containing one submitted Payout value: data: - id: po_R8Ln3Oq9Ws5Yu7Za0Bc4De6F amount: 2500 currency: EUR merchant_reference: 1234567890 status: PROCESSING card_brand: visa card_last4: '1111' created_at: 1719792000 updated_at: 1719792060 recipient: country: DE first_name: Jenny last_name: Rosen has_more: false total_count: 1 ErrorInvalidRequest: summary: Read request contains an invalid value value: error: code: invalid_request message: Request validation failed. doc_url: https://docs.flowlix.eu/api-reference/errors request_id: req_read400a ErrorPayoutInvalidSearchCriteria: summary: Payout list cursors are incompatible value: error: code: invalid_search_criteria message: starting_after and ending_before are mutually exclusive. doc_url: https://docs.flowlix.eu/api-reference/errors request_id: req_posearch400a ErrorListParameterInvalid: summary: List query parameter has an invalid value value: error: code: parameter_invalid message: Request parameter is invalid. param: created_gte doc_url: https://docs.flowlix.eu/guides/errors request_id: req_list400a 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 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 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: PayoutListBadRequest: description: | A Payout list filter, cursor, or query value is invalid. Correct the parameter named by `error.param` when it is present. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: invalid_request: $ref: '#/components/examples/ErrorInvalidRequest' invalid_search_criteria: $ref: '#/components/examples/ErrorPayoutInvalidSearchCriteria' invalid_parameter: $ref: '#/components/examples/ErrorListParameterInvalid' Unauthorized: description: > The API key is missing, invalid, expired, or revoked. Send the secret key for the intended merchant and mode in `Authorization: Bearer `. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: invalid_api_key: $ref: '#/components/examples/ErrorInvalidApiKey' 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' 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 ``` ````