Transfers & Payouts

This section covers money going out: to a supplier, a driver, a seller on your marketplace, or to your own account. A payout spends funds you already hold, which is why it passes through more checks than anything else on the API.

What you can use

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.

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 . _ : -.

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 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 from 1 %, depending on the country and the channel, and your plan can lower that rate. 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, and beneficiary.created is sent for it. 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.

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 entered a security verification code and passed 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

To check the name on a wallet, use POST /beneficiaries/{id}/verify: it asks the operator in live mode and returns what 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.