Relay
Collect for sellers who have no Wajub account, and let Wajub work out and pay what each one is owed.
In relay, you are the merchant of record. Your sellers have no Wajub account: each one is a
connection tied to their mobile money wallet. You collect every sale on your own balance, and Wajub
keeps, sale by sale, what each seller is owed, then pays them on the schedule you set.
Open in live once Wajub has reviewed your platform
Every call on this page works with a sandbox key. In live, Relay is open to every platform Wajub
has approved for it: ask for the review under Settings, Sync, Platform. Until it is approved, or
if the approval is withdrawn, POST /accounts with account_type: relay, a call carrying X-Sync
on a live Relay connection, and a Relay part of a shared payment answer 403 with
error_code: sync_mode_not_approved.
One connection per seller
Create the connection with the seller's wallet: either a beneficiary you already have, or the
details to create one, with the same fields as POST /beneficiaries.
curl https://api.wajub.com/accounts \
-H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
-H "Content-Type: application/json" \
-d '{
"account_type": "relay",
"capabilities": ["payments", "refunds"],
"pricing": { "percentage_fee": 10, "currency": "XAF" },
"payout_schedule": "weekly",
"beneficiary": "ben_LRQqYvlhrgUOE225KMKU"
}'| The wallet | The connection |
|---|---|
| Its name is confirmed by the operator | active, with payment_status: active, straight away |
| Not checked yet, or the operator could not be asked | pending; relay.pending_reason says why. It turns active as soon as a check succeeds, with POST /beneficiaries/{id}/verify or on its own |
| Known to the operator under another name | pending with wallet_name_mismatch: correct the name, then check again |
There is no onboarding and no authorization_url. A wallet carries one Relay connection per
platform: a second answers 409 with error_code: relay_wallet_taken.
What each seller is owed
Charge with X-Sync as for any connection. The payment is yours: it lands on your balance. For each
sale that succeeds, Wajub records the seller's due:
| The due | What the sale credited you, less Wajub's fee, less your commission (the connection's pricing) |
| Held | Until the sale clears retention, like the money itself |
| Payable | After that, until a payout takes it |
| Card reserve | A card sale keeps 10% of its due for 120 days by default, on your balance, against chargebacks: paid to the seller by the first payout after that (The card reserve) |
A sale you collected on your own provider account never reached Wajub, so it creates no due.
Payouts
payout_schedule (manual, daily, weekly, monthly) and payout_min_amount work as for
lite, and POST /accounts/{id}/payouts pays the seller now. Each payout sends the seller's payable
dues, oldest first and whole, less what they owe after a refund, from your balance to their wallet.
When what they owe absorbs the whole payout, nothing is sent: the call answers 200 with
transfer: null and the amount netted.
A Relay seller gets one payout a day at most. When two runs meet the same day (the schedule and
your POST /accounts/{id}/payouts, or a call you retried), the second answers with that day's payout
and sends nothing more; dues recorded in between leave with the next day's payout, on a payout of
their own. A due is only ever marked paid by the payout that carried it.
| What holds a payout back | payout_hold.reason |
|---|---|
| Your balance does not hold the amount | insufficient_balance: nothing leaves, the next run tries again |
| Your exposure cap | exposure_cap (Your exposure cap) |
| Wajub withdrew your approval | approval_withdrawn |
| The seller passed the name-only tier | identity_required (below) |
| The seller is new, and only their older dues are paid | new_seller (Seller risk) |
| You, or Wajub, froze the seller | frozen (Seller risk) |
A sale you hold until delivery keeps its due unpaid until you release it, without a
payout_hold.
Each hold sends account.payout_limited once, except identity_required, which sends
account.identity_required. A payout goes through every check of an ordinary
transfer, your reserve and refunds on their way included.
When a sale is refunded
The refund comes out of your balance, as for any payment of yours: it waits with
insufficient_balance if you do not hold it. On the seller's side:
| The due | What happens |
|---|---|
| Not paid yet | It is reduced by the refunded share, and cancelled if nothing is left |
| Already paid | What the seller owes is recorded on their beneficiary, and taken out of their next payout |
A lost dispute works the same way. Each refund or dispute counts once, however often it is replayed.
The seller's identity, past a tier
A seller is paid on their wallet's name alone until what Wajub paid that wallet over the last 12
months reaches a ceiling (500 000 XAF or XOF). Past it, the part of a payout above the ceiling waits
for an identity document: you receive account.identity_required, and send it with
POST /accounts/{id}/identity, as multipart/form-data.
| Field | |
|---|---|
full_name | As the document prints it |
document_type | national_id, passport, driving_license or residence_permit |
document_number | Never stored in clear |
birth_date | YYYY-MM-DD |
document_expires_at | Optional; an expired document is refused |
document | JPG, PNG or PDF, 10 MB at most |
Wajub reviews it, usually within a working day: account.identity_verified, and the held payouts
leave from the next run, or account.identity_rejected with the reason. In sandbox it is approved at
once. The ceiling may change: Wajub tells Relay platforms before it does.