A payouts API over many providers. Every outcome classified.

What a payouts API should give you

A payouts API lets your platform send money to bank accounts, mobile-money wallets, and other payout methods through one interface, while the API absorbs each provider’s request format, status vocabulary, and failure modes. Flominzo Payouts is designed as that layer: one payout lifecycle over the providers you connect, with every attempt recorded and every outcome reconciled.

You integrate once. Providers are connected through rail adapters to the providers you use; rails, markets, and activation are agreed for your deployment. Because Flominzo Recon runs on the same core, a payout is not finished when a provider says paid - it is finished when the evidence agrees. That is what we mean by agentic payments with 100% reconciliation: every payment ends either matched against independent evidence - the provider’s records, the settlement file and the bank statement - or as an open exception with an owner and a reason. None is silently assumed paid.

What is public today, and what you get at integration

There is no public sandbox. Test environments and representative records are set up as part of an integration.

The payout lifecycle

A payout instruction is not the same thing as the request sent to a provider. Flominzo keeps them apart: the instruction is recorded once, and each attempt to execute it has its own state. The payout’s overall status is derived from its parts, never overwritten by the last message received.

Idempotency: one instruction, one payout

Every payout instruction carries an idempotency key. Repeating a request with the same key returns the original instruction instead of creating a second one, so a client-side retry after a dropped connection is safe.

The harder case is on the provider side. When a provider times out, the request may or may not have been processed. Sending it again is how duplicate payouts happen. The guide to duplicate payouts and unknown status explains the failure in detail.

Every provider result has a class

Adapters classify each provider response, so your code never has to guess what a provider meant.

SUCCESS

The provider completed the request.

RETRYABLE

Safe to retry with the same idempotency key.

NON_RETRYABLE

The provider rejected the instruction. Do not send it again.

UNKNOWN_OUTCOME

The request may have been processed. It is resolved by a status lookup, settlement evidence, or a recorded human decision - never by sending the payout again.

Webhooks verified before they are interpreted

• Signatures, source, and freshness are checked before a callback is parsed.
• The raw callback is stored with a hash and its provenance, so every normalised status links back to the original message.
• Duplicate and out-of-order deliveries are recognised instead of changing the payout twice.
• A callback that never arrives raises MISSING_CALLBACK after the provider’s declared window, and a status lookup can be requested.

Capability contracts

Providers overlap in what they can do, so each declares its capabilities rather than pretending to support everything. A provider without cancellation does not expose a cancel operation.

Routing across the enabled providers follows policies agreed for your environment, for example by corridor, balance, cost, or provider health. An unknown result is investigated before any retry or reroute is considered safe.

Routing and failover without losing the instruction

Adding a second or third payout provider is usually about resilience and reach: a backup when one provider is down, a better route for a corridor, or a new payout method. The risk is that each provider becomes its own integration, with its own statuses and its own idea of what happened.

In Flominzo the instruction stays the same whichever provider carries it. Each route is a separate attempt with its own reference and result class, so your systems and your support team always see one payout with a readable history. A failover is only considered after the first attempt’s outcome is known: if a provider timed out, the payout may already have arrived, and sending it elsewhere would pay twice.

An illustrative request

# Illustrative - not the live contract.
POST $FLOMINZO_API_BASE_URL/payouts
Idempotency-Key: 5d0c7a52-8f1e-4b0a-9a53-2f6c1e0b7d44

{
  "reference": "TX-20418",
  "amount": { "value": "3120.00", "currency": "GHS" },
  "beneficiary": { "name": "Ama Mensah", "method": "mobile_money", "network": "MTN" }
}

# Response
{
  "paymentId": "pay_01J…",
  "attempt": { "state": "SENT" },
  "reconciliation": "UNRECONCILED",
  "closure": "OPEN"
}

Illustrative - not the live contract. The exact paths, fields, and authentication are supplied for your environment during integration.

Comparing payout APIs: what to check

Questions

Related reading