Create a payout
{baseUrl}/api/payoutsSends money from one of your balances to a bank account. Pay out in the same currency, or in a different one: Orbita converts first, then pays the beneficiary.
Authentication
Send your API key and a request signature on every call. Requests must also come from an IP address on your allowlist — see Authentication.
Headers
application/json, or multipart/form-data when the endpoint accepts a file.Body parameters
409. You can look the payout up by it later.sourceCurrency, in major units (e.g. 250000.50). Must be greater than 0.ngn, usd, gbp.sourceCurrency for an ordinary payout; a different currency makes this a cross-currency payout.LOCAL, FX_LOCAL or FX_OFFSHORE. Use FX_OFFSHORE to pay a bank outside Nigeria; this makes the offshore fields and a supporting document required.destinationCurrency. When set, the account fields below are not needed.completed conversion whose toCurrency equals sourceCurrency, to link this payout to the conversion that funded it. Each conversion can fund only one payout.tradeType is FX_OFFSHORE. Send the request as multipart/form-data to attach it; see signing multipart requests.Beneficiary account
Send these when you are not using a saved beneficiaryId.
beneficiaryId is set.beneficiaryId is set (for FX_OFFSHORE, recipientIBAN can be sent instead).058. Take it from List banks — codes depend on the payment provider. Required unless beneficiaryId is set or tradeType is FX_OFFSHORE.FX_OFFSHORE without beneficiaryId.Offshore payouts (FX_OFFSHORE)
Required when tradeType is FX_OFFSHORE and no beneficiaryId is sent, unless marked optional.
destinationAccountName is not sent.GB). Must be a country Orbita pays to.GB). Must be a country Orbita pays to.routingNumber is sent.swiftCode is sent.Behaviour
Your business must have completed KYC verification. The amount debited from your sourceCurrency balance must be covered by that balance and fall within your daily and monthly limits.
Domestic payouts carry no fee. Offshore payouts carry a payout fee, applied one of two ways depending on how the fee is configured: deducted from the payout (your balance is debited amount; the beneficiary receives amount − fee, shown as amountSent) or charged on top (your balance is debited amount + fee; the beneficiary receives amount). The response's fee and amountSent show which applied.
customerReference makes retries safe: a reference that's already been used is rejected with 409, and so is a second request with the same reference while the first is still being processed — so a retried request can't pay twice. Look the payout up by that reference with Get a payout, and check its details match before treating the retry as successful.
Same-currency payouts start as queued, except NGN payouts, which go straight into review and start as pending. Track progress with Get a payout.
Send JSON, or multipart/form-data when attaching a supporting document.
Cross-currency payouts Rolling out
When destinationCurrency differs from sourceCurrency, Orbita converts amount at the current rate, then pays the beneficiary the full converted amount once the conversion completes. quoteCode isn't supported here, and conversionId is rejected.
Before any money moves, Orbita checks the customerReference, your destinationCurrency transaction limit and — when the payout fee is charged on top — that your destinationCurrency balance can cover it, using an estimate at the current rate. The conversion then debits sourceCurrency straight away.
The response has type: "cross_currency" and describes the conversion, not a payout. Track it with Get a conversion using conversionId: payoutIntent.status moves from pending to created (with payoutId) or failed (with failureReason). Until the payout is created, Get a payout by customerReference returns 404.
Everything is checked again against the real converted amount when the payout is created. If it fails then, the converted funds stay in your destinationCurrency balance — pay them out with a same-currency payout, passing the conversionId. If the conversion itself fails, the source amount is refunded.
Response
data.type says which flow ran. For payout, the rest of data is the new payout. For cross_currency, see the table below. Every response is wrapped in the standard envelope.
payout for a same-currency payout, cross_currency for a cross-currency one.0 when no fee applies — same-currency payouts only carry a fee when they are offshore.amount minus fee when the fee is deducted from the payout; equal to amount when the fee is charged on top or there is no fee.destinationCurrency, before any deducted fee.refunded once a failed payout's funds have been returned to your balance, otherwise null.true when the payout has been flagged for additional compliance review.null.When type is cross_currency
cross_currency.processing when accepted.sourceCurrency.1600 for ngn→usd.Errors
Errors specific to this endpoint:
bankCountry or recipientCountry Orbita doesn't support. data.errors lists each problem.conversionId was sent with different currencies.You must be verified to swap currency).sourceCurrency balance can't cover the debit: amount, plus fee when the fee is charged on top.tradeType is FX_OFFSHORE and no file was attached.conversionId doesn't exist on your business.conversionId points to a conversion that isn't completed.toCurrency isn't sourceCurrency.destinationCurrency.customerReference was used before.customerReference hasn't finished yet. Wait, then look the payout up.conversionId already funds another payout.Plus the errors every endpoint can return — authentication, signing, rate limiting and server errors. See Responses & errors.