Skip to main content
POST
Submit a card payout

Authorizations

Authorization
string
header
required

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.

Headers

Idempotency-Key
string
required

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.

Maximum string length: 255

Body

application/json
amount
integer<int64>
required

Payout amount in the currency's minor units according to its ISO 4217 exponent.

Required range: x >= 1
Example:

2500

currency
string
required

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.

Required string length: 3 - 16
Pattern: ^\s*[A-Za-z]{3}\s*$
Example:

"EUR"

destination
object
required
initiator_ip_address
string
required

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.

Required string length: 3 - 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:.]*)$
Example:

"203.0.113.7"

recipient
object
required
merchant_reference
integer<int64>

Optional merchant-side reconciliation reference. The value must contain exactly 10 decimal digits and does not provide idempotency by itself.

Required range: 1000000000 <= x <= 9999999999
Example:

1234567890

Response

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.

Public, PAN-free lifecycle representation of a card payout.

id
string
required

Unique opaque public identifier for a payout (po_ prefix + random alphanumeric suffix).

Pattern: ^po_[A-Za-z0-9]{24}$
Example:

"po_Q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E"

amount
integer<int64>
required

Payout amount in minor units.

Required range: x >= 1
Example:

2500

currency
string
required

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.

Required string length: 3
Pattern: ^[A-Z]{3}$
Example:

"EUR"

status
enum<string>
required

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.

Available options:
PENDING,
PROCESSING,
SUCCEEDED,
FAILED
Example:

"PROCESSING"

card_brand
string
required

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"

card_last4
string
required

Last four digits of the destination card.

Pattern: ^[0-9]{4}$
Example:

"1111"

recipient
object
required

Merchant-supplied recipient metadata stored with the payout.

created_at
integer<int64>
required

Unix timestamp when the payout was created.

Example:

1719792000

updated_at
integer<int64>
required

Unix timestamp when the payout was last updated.

Example:

1719792060

merchant_reference
integer<int64> | null

Merchant-side reconciliation reference, if supplied.

Required range: 1000000000 <= x <= 9999999999
Example:

1234567890

failure_code
enum<string> | null

Stable Flowlix reason present only for a FAILED payout; never a raw provider code.

Available options:
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:

"do_not_honor"

failure_message
string | null

Merchant-safe explanation present only for a FAILED payout.

Required string length: 1 - 255
Example:

"The payout was declined by the issuer."