Transfers & Payouts

Everything else in these docs is money coming in. This section is money going the other way: to a supplier, a driver, a seller on your marketplace, or to your own account.

A payout is not the mirror image of a payment. A payment either succeeds or does not cost you anything, while a payout spends funds you already hold, which is why it passes through more checks than anything else on the API.

What ships today

A batch takes up to 500 payouts in one call, on every plan. Its Idempotency-Key header is required, and each line carries a reference unique within the batch. Every line passes the same checks as a single payout, the currency's bounds included, and names its beneficiary by id only: a phone number or an e-mail is refused with beneficiary_not_found. Each line succeeds or fails on its own, so one seller without a verified destination does not stop the others. Sending the same batch again with the same key only sends the lines that did not go through. The Dashboard has no CSV import for payouts.

Two things refuse a batch whole, before any line runs. A malformed line, such as a missing field, a currency that is not three letters or a reference repeated in the batch, answers 422 for the whole call, with the faulty line named in errors (transfers.3.amount). The other is a missing or empty Idempotency-Key header. Keep that key to letters, digits and . _ : -.

For the hourly velocity ceiling, a batch is one payout call whatever its number of lines, and each line adds its amount to the hourly amount.

A recurring transfer pays one beneficiary a fixed amount every hour, day, week or month. Each run creates an ordinary payout, through every check below, and a paused schedule can be resumed.

Where the money leaves from

Wajub holds a balance per currency for your account. Collections land in it, payouts draw from it, and nothing reaches a recipient that the balance did not cover first.

One call answers for the environment your key belongs to, and splits the money into five figures that do not mean the same thing.

available is the only figure a payout can draw on. pending is money collected but not yet settled to you, and reserved is money already committed to payouts in flight. Pass ?currency= to read the same balance converted into another currency.

What a payout costs

On the Wajub rail, a payout is charged a flat 1 % by default, and your plan can set a different rate per channel. A payout to another Wajub account (wajub) is free, and a bank transfer (wire) carries a fixed fee instead of a rate, see Fees & pricing. The fee is charged when the transfer completes, but it is held with the principal at creation: sending 10 000 XAF reserves 10 100 XAF, not 10 000.

Routing to your own provider account changes that. A payout that leaves through a provider you brought yourself is not funded from your Wajub balance, so it carries no Wajub fee and reserves nothing. The provider bills you directly on its own terms.

What has to be true before a payout executes

This is the part worth reading before your first live transfer. Creating one runs through a series of checks, each of which answers 422 with its own message and its own error_code rather than a generic failure. Branch on the code; the full list is in Errors.

The order matters less than the principle: nothing is reserved until every check has passed, and a transfer that fails one of them never existed. One thing does outlive the refusal: a beneficiary you passed inline, as an object, is created before the checks run. It stays on your account and in GET /beneficiaries, without a webhook. A retry with the same channel and number pays that same beneficiary, under the name it was first created with, rather than creating a second one.

The two thresholds that are yours live under Settings, Transfers: manual confirmation, with an optional amount below which it does not apply, on the General tab, and the review amount and the daily count and amount caps on the Security tab. A hold they trigger is still resolved by Wajub, not from your own Dashboard, so a session that was taken over cannot clear it.

The same Security tab carries two switches that apply to payouts started from the Dashboard, on every plan. To protect API payouts, use restricted keys and an API IP allow-list. Require 2FA refuses a payout unless the member confirmed their password and their second factor in the last 30 minutes. IP whitelist refuses every payout as long as the team has no Dashboard IP list: the list itself lives in team security, and this switch only makes sure it exists. Both settings are edited in live, by the owner or a member with manage_settings.

Creating one

A transfer takes an amount, a currency, and a recipient. The recipient is either a beneficiary you registered earlier, passed as its id, or the details themselves, in which case the beneficiary is created as part of the call.

curl https://api.wajub.com/transfers \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-892" \
  -d '{
    "beneficiary": "ben_7Kq2mX9vL4tRb3nP8sZc",
    "amount": 10000,
    "currency": "XAF",
    "description": "Supplier payment #892"
  }'

The answer is 201 Created and the transfer comes back as processing, already on its way. Both environments behave the same way here: a sandbox transfer draws on your sandbox balance and settles itself a couple of seconds later, with the outcome decided by the recipient's test number.

The resources

/identity/resolve answers 501 in live: it only works in sandbox, so it cannot vouch for a real recipient. The name check that counts is POST /beneficiaries/{id}/verify: it asks the operator in live mode and returns the name it holds, for information. Checking the name on a wallet

All of them need the secret key. A public key is refused, and so is a browser: payout routes are the most tightly held on the API. If you are paying out on behalf of a connected account, the X-Sync header selects it, which Sync covers.