Transfer reference

A transfer sends money from your balance to someone else's wallet. This page is the reference for the object and its calls; Transfers & Payouts covers what a payout costs and what has to be true before one executes.

Payouts need a secret key, or a restricted key whose permissions cover transfers. A publishable key gets 406 Private Key Required. A secret key used from a browser is refused; a restricted key used from one sets off a security alert, and will be refused the same way later (private keys in the browser).

The four calls

There is nothing else. A transfer cannot be updated, cancelled or deleted through the API.

{id} is the po_ string the API returns. In sandbox it carries a po_test_ prefix instead, which is how you tell the two environments apart in a log.

The transfer object

This is what the three single-transfer calls return, and what each accepted batch line carries under transfer. beneficiary and payment_method are always present, a beneficiary deleted since included.

A few of those fields do not behave the way their name suggests, and one of them is a trap.

Wajub adds keys of its own to metadata, such as reservation. Read your own keys by name rather than assuming you own the whole object.

Creating one

The recipient goes in beneficiary, and there are several ways to name them. Pick the case that matches what you hold.

Whatever the case, every payout needs its own Idempotency-Key: a saved beneficiary is a destination, not a guard against paying twice.

A saved beneficiary

Send the id as a string. Nothing else about the payout changes.

Only the id is matched, in the environment of your key: a sandbox beneficiary does not exist for a live key. A phone number or an e-mail address is not matched, even though they identify the beneficiary elsewhere on the API. Each refusal is a 422 with an error_code:

The last one is deliberate: a leaked key must not be able to pay a destination your integration never created.

A new recipient, created by the payout

Send the payee's details as an object, and the beneficiary is created as part of the call. That is what you want for a first payout, or for someone you pay once: one call instead of two. The fields are the beneficiary's own, and Beneficiaries documents them in full.

curl https://api.wajub.com/transfers \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-892" \
  -d '{
    "amount": 10000,
    "currency": "XAF",
    "description": "Supplier payment #892",
    "metadata": { "vendor_id": "v_892" },
    "beneficiary": {
      "name": "Aminata Diallo",
      "channel": "cm.mtn",
      "phone": "+237670000000"
    }
  }'

The answer is 201 Created, and the transfer's beneficiary.id is the new beneficiary's. It is a normal one: it shows up in GET /beneficiaries, beneficiary.created is sent for it, and the next payout to that person can send this id instead of the details.

A recipient you already saved, sent inline again

Sending the details of someone you already saved does not create a second beneficiary. When an active beneficiary of yours already uses that number on that channel, the payout goes to it: the transfer's beneficiary.id is the existing one, and the name, email and note you just sent are ignored, not written over the saved ones. To change them, use PUT /beneficiaries/{id}.

A number without its operator

A payout names its channel, and Cameroon is the one exception: when you hold a Cameroonian number but not its operator, send cm.mobile with phone. The operator, cm.mtn or cm.orange, is worked out from the number. A number that matches neither is refused with a 422 on channel and phone, rather than sent to a guess.

No other country has a generic channel: ke.mobile, eg.mobile or any other {country}.mobile is refused as an unknown channel. Name the operator's channel, such as ke.mpesa or eg.vodafone; Payout providers lists them. In Cameroon too, name the operator when you know it: cm.mobile is for a number and nothing else.

Another Wajub account

To pay someone who has a Wajub account, send channel: "wajub" and their 11-digit account number in account_number. The money goes from your balance to theirs at once, with no network in between, and the payout is free. The account has to exist, cannot be your own, and cannot be one Wajub has frozen. Paying another Wajub account has the details.

Create first, pay later

You can also create the beneficiary on its own with POST /beneficiaries, then pay it by id. That is two calls instead of one, and it is worth it when you want to:

• check the name the operator holds for a wallet before any money moves, with POST /beneficiaries/{id}/verify;
• show the payee in your own interface, or have someone approve them, before the first payout.

What the API cannot pay

• A beneficiary added from the Konsole, a payout account included. Pay it from the Dashboard.
• A bank account. The API creates Mobile Money, phone-addressed wallet (such as Djamo) and Wajub account beneficiaries only. A bank payout goes to a wire payout account, created and paid from the Dashboard.
• Another platform's or the merchant's own beneficiary, through X-Sync. A platform paying for a connected account pays only the beneficiaries of that connection.
• An inline recipient in a batch. Each line of POST /transfers/batch names a saved beneficiary by id; the object form is for single payouts.

Amounts are in the major unit

A transfer's amount is in the currency's major unit and accepts decimals: 10000 sends ten thousand francs. This is the opposite of an invoice, whose lines are whole units of the currency, so do not carry a conversion from one to the other.

Each currency has a floor and a ceiling, checked before anything else happens. Cross either one and the answer is 422 naming both bounds.

These are the platform's bounds for a single call, and the rest of the ceilings are yours: the daily cap you set yourself, the limit tied to your KYC tier, and the operator's own per-transfer ceiling. Transfers & Payouts lists the whole sequence.

Idempotency is optional, and it is your only protection

Send an Idempotency-Key header and a retry of the same call returns the original transfer instead of sending the money twice. Leave it out and nothing stops a duplicate, and there is no cancel to fall back on.

The key is at most 128 characters of letters, digits, and . _ : -; anything else answers 422. It is spent for good, per account and per environment: a key that created a transfer always returns that transfer, and never sends a second one.

Payout creation carries its own rate limit on top of the one your plan sets: 20 calls a minute per account and environment, regardless of plan, shared by POST /transfers, POST /transfers/batch, POST /accounts/{id}/payouts, POST /beneficiaries, POST /beneficiaries/{id}/receivables and POST /beneficiaries/{id}/receivables/{receivable}/settle. A loop that creates a beneficiary and then pays it counts twice.

Under heavy concurrent load, a live payout can be refused with 429, error_code: payout_queue_busy and a Retry-After header. Nothing was created: send it again after that delay, with the same Idempotency-Key. A batch line in that case is rejected with the same code and can be sent again with the batch.

What comes back, and in what state

A payout is created as processing and is already on its way, or as review when a safeguard holds it. A payout you create is never pending when you read it: only a Dashboard payout awaiting your confirmation reads pending. Confirmed, it is checked like a new payout and may be held for review (review) or leave as processing; rejected, it ends cancelled.

transfer.created fires on every payout at creation, including one held for review. Statuses & webhooks covers the five events and what to do in each handler.

A payout stopped before anything was sent, rejected in the Dashboard or cancelled by Wajub, ends cancelled, with merchant_rejected or cancelled_by_wajub as its failure_reason. A payout Wajub refuses after a review ends failed, with admin_rejected.

Why a live payout is held

A live payout that trips any of these is created as review instead of processing. Its funds are reserved, no operator has seen it, and it waits for Wajub to release or refuse it.

A held payout eventually leaves review in one of two directions. Released, it moves to processing and continues as normal. Refused, it becomes failed with failure_reason: admin_rejected and the reservation goes back to your available balance.

Sandbox payouts are never held. This is the one behaviour you cannot rehearse before going live, which is why your first live payout deserves a person watching it rather than an unattended script.

When it fails

A failed payout carries failure_reason, a short code, and failure_message, a sentence. Both are absent on any other status, so read them behind a status check rather than assuming the keys exist.

Once a payout has reached an operator, the code can be the operator's own. Treat the field as a label to log and to show a human, not as an enum to branch on.

Sandbox is the exception: its vocabulary is fixed at failure, network_error and invalid_recipient, one per test number.

On a Wajub-rail payout, a failure releases the reservation: the principal and the fee estimate both return to available, and nothing was charged. You are free to create the payout again, under a new idempotency key.

Testing it

Sandbox payouts draw on your sandbox balance and resolve themselves about two seconds later. The outcome is not random: it is decided by the recipient's number, which must be a recognised test number or the call is refused outright.

The suffix is what matters, not the prefix, so the same five endings work behind any operator prefix the sandbox knows: +2250700000002 fails the same way +237670000002 does.

Sandbox payouts are charged a 2 % platform fee on top of the amount, and it is not given back when the payout fails. That rate is the sandbox's own and does not match live pricing.

Listing

There is no date filter and no amount filter, so a reconciliation job walks the list and does its own narrowing on created_at.

curl -G https://api.wajub.com/transfers \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
  -d status=failed \
  -d per_page=50

The list is sorted by creation date, newest first, and you cannot change that. It is paginated by page number by default, with meta carrying current_page, last_page, per_page and total, plus the next_cursor and has_more that let you go on with a cursor. Pass that next_cursor as cursor and meta changes shape, to per_page, next_cursor, prev_cursor and has_more. Pick one of the two and write your loop against it, because a handler that reads last_page breaks the moment someone adds a cursor.

Retrieving one

Only the po_ id resolves. A transfer that belongs to another account, or to the other environment, answers 404 Transfer Not Found rather than telling you it exists somewhere else.

curl https://api.wajub.com/transfers/po_CSUGajfv9xh0XQ5wu2lx \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…"

Retrieving is for reconciliation and for support, not for following a payout. Wait on the webhook instead: a payout that reaches an operator can sit there for minutes, and polling it teaches you nothing the event would not have told you first.