Send Payout

Sends money from one of your settlement accounts to a bank account previously resolved with Validate Bank Account. See the folder description above for how to handle the 200 / 400 / 202 outcomes.

Idempotency-Key header is required. Reusing the same key for a retried request returns the original result instead of creating a second payout — always reuse the same key when retrying after a network error or timeout on your end, and always generate a new one for a genuinely new payout.

Headers

Body (JSON) - checked by Joi (settlementPayoutSchema).

Outcomes

• 200 - provider confirmed. data.reference = the payout reference (same as verify_id).
• 202 - debit recorded, provider has not answered within about 18 s. Poll Check Payout Status or wait for the Payout Outcome webhook. Don’t retry.
• 400 Transfer failed: ... - provider declined. The debit (amount + fee) has been reversed to your settlement balance, and the error text ends with [FAILED - REVERSED: <provider reason>].

Business errors (400)

• Transaction already processed - same idempotencyKey reused, or this verify_id already has a payout in flight.
• Transaction does not exist - unknown verify_id, or one whose payout already finished.
• Insufficient funds for transfer - balance must be strictly greater than amount + fee.

Idempotency: retrying with the same key does not return the original result. You get a 400 as above, so check status instead.