Skip to content

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.

A Relay seller
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 walletThe connection
Its name is confirmed by the operatoractive, with payment_status: active, straight away
Not checked yet, or the operator could not be askedpending; 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 namepending 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 dueWhat the sale credited you, less Wajub's fee, less your commission (the connection's pricing)
HeldUntil the sale clears retention, like the money itself
PayableAfter that, until a payout takes it
Card reserveA 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 backpayout_hold.reason
Your balance does not hold the amountinsufficient_balance: nothing leaves, the next run tries again
Your exposure capexposure_cap (Your exposure cap)
Wajub withdrew your approvalapproval_withdrawn
The seller passed the name-only tieridentity_required (below)
The seller is new, and only their older dues are paidnew_seller (Seller risk)
You, or Wajub, froze the sellerfrozen (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 dueWhat happens
Not paid yetIt is reduced by the refunded share, and cancelled if nothing is left
Already paidWhat 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_nameAs the document prints it
document_typenational_id, passport, driving_license or residence_permit
document_numberNever stored in clear
birth_dateYYYY-MM-DD
document_expires_atOptional; an expired document is refused
documentJPG, 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.

What did you think of this content?