Beneficiaries

A beneficiary is a destination you have saved: a name, a Mobile Money number, and the operator that serves it. You create it once and pay it by id afterwards, which keeps the number out of every payout call you make and out of the logs those calls leave behind.

It is also the only way to pay the same person twice without retyping where the money goes, and retyping is how money reaches the wrong phone.

Creating one

Send it with the secret key. Beneficiary creation carries its own tighter rate limit than the rest of the API, since adding a destination is half of what an attacker needs to move money.

curl https://api.wajub.com/beneficiaries \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: beneficiary-amina" \
  -d '{
    "channel": "cm.mtn",
    "name": "Amina Traoré",
    "phone": "+237670000000"
  }'

The answer is 201 Created. The id is what every payout takes, prefixed ben_ in live and ben_test_ in sandbox, so the two environments can never be confused for one another.

The channel decides the operator

Name the operator's channel: ke.mpesa, eg.vodafone, cm.mtn, cm.orange. Cameroon is the one exception: when you hold a Cameroonian number but not its operator, pass cm.mobile, and the operator, cm.mtn or cm.orange, is worked out from the number itself. In live it comes from the country's numbering plan, as it does for a payment; in sandbox it comes from the test prefixes. No other country has a generic channel: ke.mobile or any other {country}.mobile is refused as an unknown channel.

That resolution can fail, and it fails loudly rather than picking one at random.

If you already know the operator, name it. cm.mobile is there for the case where you hold a Cameroonian number and nothing else.

Paying another Wajub account

When the person you pay already has a Wajub account, use the wajub channel and their 11-digit account number. The money never leaves Wajub: one balance is debited and the other credited, with no network in between and nothing to wait for.

The account has to exist, it cannot be your own, and it cannot be an account Wajub has frozen: each is refused with 422 when you create the beneficiary, and a payout to an account frozen since then fails on its own. Paying it is an ordinary transfer, with the same limits and the same statuses; it simply succeeds at once, and it is free, since there is no network to pay between two Wajub accounts. On an account whose beneficiaries Wajub checks, the name is matched against the recipient's compliance file instead of an operator's records.

Paying one

Pass the id where a payout expects a recipient. Everything else about the transfer is unchanged.

The body is the same one Transfer reference documents, with a string where the inline object would have been.

What you can change, and what you cannot

The update accepts five fields, and the destination is not among them.

Retrieving one

The same object creation returned, read back by its id. Use it to check a payee is still active before a payout, and remember it still will not tell you the number the money goes to.

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

A 404 covers three different situations without distinguishing them: the id does not exist, it belongs to another account, or it belongs to the other environment. A ben_test_ id read with a live key is the common one.

Listing them

Results come back newest first, twenty-five at a time unless you raise per_page, which caps at 100. The envelope is items and meta, and passing cursor switches the pagination mode and the shape of meta with it, the same way it does on transfers.

search does not behave the same in both environments. In sandbox it is a direct match on the name, the email, the phone and the id. In live, search also covers the country code and the type, so a live search returns results a sandbox search would not.

is_active filters on the flag. type is the filter worth understanding.

The list returns standard only unless you ask otherwise, and that default is deliberate. A privileged beneficiary can sit unverified, and a live payout to an unverified destination is refused with This beneficiary payment method has not been verified yet and cannot receive live payouts. Pass type=privileged or type=all when you genuinely want to see them.

Your own beneficiaries are marked verified the moment they are created, because the merchant vouches for its own payees. That is what makes a standard beneficiary payable straight away. On a Relay account, the seller's wallet is first matched against the name its operator holds, and Paying sellers covers that case.

Checking the name on a wallet

The call takes no body. It asks the operator whose name the wallet is registered under and compares it with the name you declared. The comparison ignores word order, accents and punctuation, and tolerates small spelling differences.

On your own beneficiaries the answer is information. The beneficiary stays payable whatever comes back, the call answers 200, and registered_name carries the name the operator holds, so you can show it to whoever is about to send the money.

The operators that answer today are MTN, Orange Money and Express Union in Cameroon, cm.mtn, cm.orange and cm.eu, and a Wajub account, wajub. Every other channel returns lookup_unavailable.

The beneficiary keeps the last outcome: verification carries it on every read, and is absent until a check has run. verified is a different thing. It says whether Wajub will pay the beneficiary in live mode, and here a name_mismatch does not change it. One exception: a beneficiary left unverified, a seller the operator could not confirm while your account was on Relay for instance, becomes payable when the names match, and is then paid under the name the operator holds. A mismatch or an operator that cannot answer leaves it unpayable.

The call has a ceiling of its own, whatever your plan: 10 checks a minute and 200 a day per account in live, 10 a minute in sandbox. Past it the answer is 429. It is meant for your own payees, checked as you add them, not for looking numbers up in bulk.

Payout accounts

A payout account is where your own money goes: the destination of the daily settlement and of the payouts you make to yourself. You create it under Settings, Transfers, Payout Accounts, on Mobile Money, Djamo, a Wajub account, or a bank account through wire. It is stored as a privileged beneficiary and starts unverified. Verifying it from the same page matches the account against the name its operator holds. If the names cannot be matched, Wajub asks the account owner to confirm the account. Wajub processes wire payouts, for a fixed fee, within 48 business hours by default.

Statements and debts

Three more routes hang off a beneficiary.

A recorded debt sends beneficiary.receivable_recorded. With netting on for your account, the next batch payout to that beneficiary is reduced by it and sends beneficiary.receivable_recovered. Paying sellers walks through both.

Deleting one

The answer is 200. The record stops appearing in lists and can no longer be paid, while transfers that already went to it keep pointing at it, so your history stays readable: their beneficiary carries deleted: true, and GET /beneficiaries/{id}/statement still answers for it.

There is no restore on the API. Creating the same destination again gives you a new beneficiary with a new id, not the old one back.

What reaches your webhook