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.
Authorizations
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
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.
255Body
Payout amount in the currency's minor units according to its ISO 4217 exponent.
x >= 12500
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.
3 - 16^\s*[A-Za-z]{3}\s*$"EUR"
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.
3 - 45^(((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:.]*)$"203.0.113.7"
Optional merchant-side reconciliation reference. The value must contain exactly 10 decimal digits and does not provide idempotency by itself.
1000000000 <= x <= 99999999991234567890
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.
Unique opaque public identifier for a payout (po_ prefix + random alphanumeric suffix).
^po_[A-Za-z0-9]{24}$"po_Q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E"
Payout amount in minor units.
x >= 12500
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.
3^[A-Z]{3}$"EUR"
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.
PENDING, PROCESSING, SUCCEEDED, FAILED "PROCESSING"
Canonical lower-case card-network brand, for example visa,
mastercard, or amex. The schema remains extensible; each operation
validates its supported brands separately.
"visa"
Last four digits of the destination card.
^[0-9]{4}$"1111"
Merchant-supplied recipient metadata stored with the payout.
Unix timestamp when the payout was created.
1719792000
Unix timestamp when the payout was last updated.
1719792060
Merchant-side reconciliation reference, if supplied.
1000000000 <= x <= 99999999991234567890
Stable Flowlix reason present only for a FAILED payout; never a raw provider code.
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 "do_not_honor"
Merchant-safe explanation present only for a FAILED payout.
1 - 255"The payout was declined by the issuer."