> ## 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. # Submit a card payout > Submits a Host-to-Host Original Credit Transaction to a recipient Visa or Mastercard. Inspect the response status: `PENDING` and `PROCESSING` are nonterminal; `SUCCEEDED` and `FAILED` are terminal. `PROCESSING` does not confirm delivery or settlement. A `503 service_unavailable` response may be returned when payout processing is temporarily unavailable. In that case, retry with the same `Idempotency-Key` and an equivalent effective request identity. Supply the IP address of the human initiating the payout and the recipient's country. For an end-user cash-out, the initiator is normally the recipient. For a manual merchant-portal payout, the initiator is the authenticated merchant operator. Recipient first and last names are required for every new Visa and Mastercard payout. Each must contain 1–255 characters, including at least one non-whitespace character. Names are forwarded unchanged; no cardholder-name fallback is used. Card expiry, CVC/CVV, return URLs, redirects, shopper 3D Secure, and hosted payout pages are not part of this operation. The card number in the request example illustrates payload shape only. It does not guarantee Payout eligibility or any particular outcome. Replace it with test data supplied for the current Sandbox account. Use the `Idempotency-Key` header for every request and reuse the same key only when retrying the original Payout operation. Use `GET /v1/payouts/{payout_id}` for the current state; repeating creation can return the saved creation response. ## OpenAPI ````yaml /api-reference/payments-api.yaml post /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: post: tags: - Payouts summary: Submit a card payout description: >- Submits a Host-to-Host Original Credit Transaction to a recipient Visa or Mastercard. Inspect the response status: `PENDING` and `PROCESSING` are nonterminal; `SUCCEEDED` and `FAILED` are terminal. `PROCESSING` does not confirm delivery or settlement. A `503 service_unavailable` response may be returned when payout processing is temporarily unavailable. In that case, retry with the same `Idempotency-Key` and an equivalent effective request identity. Supply the IP address of the human initiating the payout and the recipient's country. For an end-user cash-out, the initiator is normally the recipient. For a manual merchant-portal payout, the initiator is the authenticated merchant operator. Recipient first and last names are required for every new Visa and Mastercard payout. Each must contain 1–255 characters, including at least one non-whitespace character. Names are forwarded unchanged; no cardholder-name fallback is used. Card expiry, CVC/CVV, return URLs, redirects, shopper 3D Secure, and hosted payout pages are not part of this operation. The card number in the request example illustrates payload shape only. It does not guarantee Payout eligibility or any particular outcome. Replace it with test data supplied for the current Sandbox account. Use the `Idempotency-Key` header for every request and reuse the same key only when retrying the original Payout operation. Use `GET /v1/payouts/{payout_id}` for the current state; repeating creation can return the saved creation response. operationId: createPayout parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePayoutRequest' examples: basic: summary: Payout payload shape value: 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 responses: '201': description: >- Payout response. PENDING and PROCESSING are nonterminal; SUCCEEDED and FAILED are terminal. A same-key replay can return the saved creation response; use GET to read the current state. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Payout' examples: pending: $ref: '#/components/examples/PayoutPending' processing: $ref: '#/components/examples/PayoutProcessing' succeeded: $ref: '#/components/examples/PayoutSucceeded' failed: $ref: '#/components/examples/PayoutFailed' '400': $ref: '#/components/responses/CreateBadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/PayoutForbidden' '404': $ref: '#/components/responses/PayoutAttemptNotFound' '409': $ref: '#/components/responses/PayoutConflict' '422': $ref: '#/components/responses/PayoutUnprocessableEntity' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailable' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: true description: > A unique key to ensure one effective operation is processed only once. If the same key and an equivalent operation-specific effective request identity have already completed successfully, the original response is returned. A different identity returns `409 idempotency_key_reused`. Non-2xx responses are not cached, so callers may retry after errors. No fixed retention period is promised by this contract. For one-shot requests, such as creating a payment from a checkout button, a random UUIDv4 is fine. For requests tied to a specific business operation, such as refunding an order, a deterministic key is preferred so retries collapse correctly across processes. schema: type: string maxLength: 255 example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 schemas: CreatePayoutRequest: type: object additionalProperties: false required: - amount - currency - destination - initiator_ip_address - recipient properties: amount: type: integer format: int64 minimum: 1 description: | Payout amount in the currency's minor units according to its ISO 4217 exponent. example: 2500 currency: $ref: '#/components/schemas/CurrencyInput' merchant_reference: $ref: '#/components/schemas/MerchantReference' destination: $ref: '#/components/schemas/PayoutDestinationInput' initiator_ip_address: allOf: - $ref: '#/components/schemas/CustomerIpAddress' description: | IP address of the human who initiated the payout, observed at the merchant's or Flowlix's trusted ingress. This may be the recipient in an end-user cash-out or a merchant operator in a manual flow. recipient: $ref: '#/components/schemas/PayoutRecipientInput' 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 CurrencyInput: type: string minLength: 3 maxLength: 16 pattern: ^\s*[A-Za-z]{3}\s*$ description: > Three-letter ISO 4217 currency code supplied when creating a payment or payout. Accepted case-insensitively and with surrounding whitespace, then normalized to a canonical uppercase code before the operation is created. A value that is not three letters is rejected with `400 parameter_invalid` (`param=currency`); a well-formed code that Flowlix does not accept for that operation is rejected with `422 currency_not_supported`. Neither creates a payment or payout. The available set is validated per request instead of being enumerated here, so enabling another currency is not a breaking contract change. example: EUR 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 PayoutDestinationInput: type: object additionalProperties: false required: - card_number properties: card_number: type: string pattern: ^[0-9]{13,19}$ description: | Destination card number as digits only. Flowlix validates Luhn and accepts eligible Visa and Mastercard ranges before registration. example: '4111111111111111' CustomerIpAddress: type: string minLength: 3 maxLength: 45 pattern: >- ^(((25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])|[0-9A-Fa-f:]*:[0-9A-Fa-f:.]*)$ description: > Shopper IPv4 or IPv6 address observed by the merchant during checkout. Send one literal address, not a hostname, port, or comma-separated proxy chain. Flowlix validates the complete IPv4 or IPv6 literal before registering the payment; the pattern is only an initial schema-level character and length guard. example: 203.0.113.7 PayoutRecipientInput: type: object additionalProperties: false required: - country - first_name - last_name properties: country: $ref: '#/components/schemas/CountryCode' first_name: type: string minLength: 1 maxLength: 255 pattern: >- ^[\s\S]*[^\u0009-\u000D\u0020\u0085\u00A0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000\uFEFF][\s\S]*$ description: >- Recipient first name. Must contain a non-whitespace character; preserved without trimming or normalization. example: Jenny last_name: type: string minLength: 1 maxLength: 255 pattern: >- ^[\s\S]*[^\u0009-\u000D\u0020\u0085\u00A0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000\uFEFF][\s\S]*$ description: >- Recipient last name. Must contain a non-whitespace character; preserved without trimming or normalization. example: Rosen 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 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 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 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 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 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 ApiError: type: object description: Error response wrapper. properties: error: $ref: '#/components/schemas/ApiErrorBody' CountryCode: type: string pattern: ^[A-Z]{2}$ description: Canonical ISO 3166-1 alpha-2 country code. example: DE 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. 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: PayoutPending: summary: Payout pending value: id: po_Q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E amount: 2500 currency: EUR merchant_reference: 1234567890 status: PENDING card_brand: visa card_last4: '1111' created_at: 1719792000 updated_at: 1719792000 recipient: country: DE first_name: Jenny last_name: Rosen PayoutProcessing: summary: Payout processing value: id: po_Q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E amount: 2500 currency: EUR merchant_reference: 1234567890 status: PROCESSING card_brand: visa card_last4: '1111' created_at: 1719792000 updated_at: 1719792000 recipient: country: DE first_name: Jenny last_name: Rosen PayoutSucceeded: summary: Payout succeeded value: id: po_Q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E amount: 2500 currency: EUR merchant_reference: 1234567890 status: SUCCEEDED card_brand: visa card_last4: '1111' created_at: 1719792000 updated_at: 1719792000 recipient: country: DE first_name: Jenny last_name: Rosen PayoutFailed: summary: Payout failed value: id: po_Q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E amount: 2500 currency: EUR merchant_reference: 1234567890 status: FAILED card_brand: visa card_last4: '1111' created_at: 1719792000 updated_at: 1719792000 recipient: country: DE first_name: Jenny last_name: Rosen failure_code: generic_decline failure_message: The payout was declined. ErrorRequestBodyInvalid: summary: Request body cannot be read value: error: code: request_body_invalid message: Request body is invalid. doc_url: https://docs.flowlix.eu/guides/errors request_id: req_body400a ErrorParameterMissing: summary: Required header is missing value: error: code: parameter_missing message: Idempotency-Key header is required. param: Idempotency-Key doc_url: https://docs.flowlix.eu/guides/errors request_id: req_param400b ErrorParameterInvalid: summary: Request parameter has an invalid value value: error: code: parameter_invalid message: Request validation failed. param: amount doc_url: https://docs.flowlix.eu/guides/errors request_id: req_param400a 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 ErrorPayoutSubmissionUnavailable: summary: Merchant cannot submit new Payouts value: error: code: payout_submission_unavailable message: Payout submission is unavailable. doc_url: https://docs.flowlix.eu/api-reference/errors request_id: req_payout403a ErrorPayoutAttemptNotFound: summary: Payout state is unavailable during creation value: error: code: object_not_found message: The Payout could not be found while the request was being completed. doc_url: https://docs.flowlix.eu/api-reference/errors request_id: req_payout404a ErrorPayoutIdempotencyKeyInUse: summary: Original Payout request is still processing value: error: code: idempotency_key_in_use message: >- The original payout request for po_Q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E is still processing. param: Idempotency-Key doc_url: https://docs.flowlix.eu/api-reference/errors request_id: req_payout409a ErrorPayoutIdempotencyKeyReused: summary: Payout key was reused for a different effective identity value: error: code: idempotency_key_reused message: >- Idempotency key was already used for payout po_Q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E with different request parameters. param: Idempotency-Key doc_url: https://docs.flowlix.eu/api-reference/errors request_id: req_payout409b ErrorPayoutObjectStateConflict: summary: Payout state conflicts with the requested transition value: error: code: object_state_conflict message: The Payout cannot accept this update in its current state. doc_url: https://docs.flowlix.eu/api-reference/errors request_id: req_payout409c ErrorPayoutCurrencyNotSupported: summary: Currency is not accepted for Payouts value: error: code: currency_not_supported message: Currency USD is not supported for payouts. param: currency doc_url: https://docs.flowlix.eu/api-reference/errors request_id: req_currency422o ErrorMerchantNotProvisioned: summary: Merchant is not provisioned for this operation value: error: code: merchant_not_provisioned message: The merchant is not provisioned on the payment gateway. doc_url: https://docs.flowlix.eu/api-reference/errors request_id: req_merchant422a ErrorInvalidCard: summary: Destination card number is invalid value: error: code: invalid_card message: The destination card number is invalid. param: destination.card_number doc_url: https://docs.flowlix.eu/guides/errors request_id: req_card422a ErrorUnsupportedCard: summary: Destination card is not eligible for Payouts value: error: code: unsupported_card message: The destination card is not supported for payouts. param: destination.card_number doc_url: https://docs.flowlix.eu/guides/errors request_id: req_card422b 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: CreateBadRequest: description: | The create request could not be read or failed request validation. Correct the JSON, required headers, or parameter named by `error.param`. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: malformed_body: $ref: '#/components/examples/ErrorRequestBodyInvalid' missing_idempotency_key: $ref: '#/components/examples/ErrorParameterMissing' invalid_parameter: $ref: '#/components/examples/ErrorParameterInvalid' 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' PayoutForbidden: description: | The API key is valid, but the merchant cannot submit this Payout. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: payout_submission_unavailable: $ref: '#/components/examples/ErrorPayoutSubmissionUnavailable' PayoutAttemptNotFound: description: | Flowlix could not find state registered while creating this Payout. Preserve the same idempotency key, retain `request_id`, and contact support before attempting a different key. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: object_not_found: $ref: '#/components/examples/ErrorPayoutAttemptNotFound' PayoutConflict: description: | The `Idempotency-Key` is still being processed, was reused for a different Payout effective request identity, or the Payout state conflicts with the requested transition. Preserve the original key for retries of the same business Payout. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: idempotency_key_in_use: $ref: '#/components/examples/ErrorPayoutIdempotencyKeyInUse' idempotency_key_reused: $ref: '#/components/examples/ErrorPayoutIdempotencyKeyReused' object_state_conflict: $ref: '#/components/examples/ErrorPayoutObjectStateConflict' PayoutUnprocessableEntity: description: | The Payout request passed basic validation, but its currency, merchant provisioning, or destination card is not eligible for the operation. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: currency_not_supported: $ref: '#/components/examples/ErrorPayoutCurrencyNotSupported' merchant_not_provisioned: $ref: '#/components/examples/ErrorMerchantNotProvisioned' invalid_card: $ref: '#/components/examples/ErrorInvalidCard' unsupported_card: $ref: '#/components/examples/ErrorUnsupportedCard' 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 ``` ````