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.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…" \
  -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

Pass the operator directly when you know it, cm.mtn or cm.orange. Pass the country's generic channel, cm.mobile, when you do not, and the operator is worked out from the number itself.

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

If you already know the operator, name it. The generic form is there for the case where you hold a 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 — 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.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…"

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 it goes through the search index, which 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.

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.

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