Quickstart

Fund a sandbox balance, send a first payout and test its failures, then switch to live. A payout spends funds you already hold, so the first step collects money.

1. Put money in the balance

Create a sandbox payment for more than you intend to send, then pay it yourself on its checkout page. Accept a payment covers this call properly; here it is only a means to an end.

curl https://api.wajub.com/payments \
  -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 20000,
    "currency": "XAF",
    "email": "you@example.com",
    "description": "Funding my sandbox balance"
  }'

Open the authorization_url, pick Mobile Money, and pay with +237670000000. That number always succeeds in sandbox. A few seconds later the payment settles and the amount reaches your balance, minus the sandbox platform fee of 2 %: 20 000 collected leaves 19 600 to send.

2. Check what you can send

One call, no parameters. It answers with the balance of the environment your key belongs to, so the same line of code reads the sandbox wallet today and the real one tomorrow.

The call takes an optional currency to convert the figure into another one. Leave it out and you get your account currency.

curl https://api.wajub.com/balance \
  -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…"

Five figures come back.

available is the only figure a payout can draw on. Check environment if you ever doubt which key you used.

3. Send the payout

Pass the recipient inline and Wajub creates the beneficiary along with the payout, which is what you want for a first try. The channel is the operator that serves the number, and the phone number has to be a sandbox test number or the call is refused before anything is created.

Send an Idempotency-Key from the very first call. It costs nothing and it is the only thing that makes a retry safe, here and in production.

curl https://api.wajub.com/transfers \
  -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-payout-01" \
  -d '{
    "amount": 5000,
    "currency": "XAF",
    "description": "First test payout",
    "beneficiary": {
      "name": "Aminata Diallo",
      "channel": "cm.mtn",
      "phone": "+237670000000"
    }
  }'

Wajub answers 201 Created and the payout is already processing. Nothing is waiting for you to confirm it.

Store transfer.id. It is the one handle that is unique: the reference you can send comes back as you sent it but is never checked for uniqueness, and no call cancels a payout once it exists.

Your balance has moved twice. The 5 000 left it, and so did a sandbox payout fee of 2 %, charged on top rather than taken out of the amount. 19 600 becomes 14 500, and the recipient still receives the full 5 000.

4. Watch it resolve

About two seconds later the payout finishes, and the recipient's number decided the outcome long before that. The honest way to find out is the webhook, not a loop.

Statuses & webhooks covers registration, signatures and what belongs in each handler. While you are still exploring, read the payout back instead.

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

status is now succeeded and complete is true. Those two are not the same thing: complete means it worked, not that it is over, so a failed payout is finished and still reports false.

{
  "amount": 5000,
  "currency": "XAF",
  "beneficiary": {
    "name": "Aminata Diallo",
    "channel": "cm.mtn",
    "phone": "+237670000000"
  }
}

{
  "code": 201,
  "status": "Created",
  "transfer": {
    "id": "po_test_CSUGajfv9xh0XQ5wu2lx",
    "status": "processing"
  }
}

5. Break it on purpose

A payout that always succeeds teaches you nothing about the day one does not. The ending of the recipient's number picks the outcome, so run the same call again with each of these before you trust your handler.

Only the ending matters, not the operator, so the same five work behind any prefix the sandbox knows. A number that matches none of them is refused outright.

Then go live

Swap sk_test. for sk. and four things change, none of them in your code.

That third row is the one to plan for. A held payout is created with status review, its funds are reserved, and nothing you can call releases it. Send your first live payout to yourself, for a small amount, at a time when someone is watching, and never as the first iteration of a batch. Transfers & Payouts lists every check a live payout runs through, and Transfer reference documents the object in full.