Sync

Sync is how a marketplace or a platform operates on behalf of the merchants it works with. A connection joins two Wajub accounts: yours, the platform, and theirs, the merchant. Once it is live, you call the ordinary API with one extra header and the request runs as if the merchant had sent it.

The part that catches people out is the first sentence. A connected account is not an account you create. It is a Wajub account that already exists, belonging to a merchant who signs in and authorises your platform. You create the invitation, they accept it.

What you need before you start

If Sync is unavailable, its routes answer 404 and the section is hidden from your Dashboard, whatever your plan says.

The four things Sync does

It connects an account. You create a connection, hand the merchant a link, and they authorise it from their own Dashboard.

It lends you their identity. With X-Sync on a request, the request acts as the connected merchant. The payment, the customer, the refund all belong to them.

It charges your commission. Each connection carries a pricing rule. When a payment attributed to that connection succeeds, the fee leaves the merchant's balance and lands on yours, held under the same retention as the sale itself, and it is given back if that sale is refunded or a dispute on it is lost, by the policy you set on the connection.

It copies their events to you. A payment, refund or transfer on a connected account, and a dispute on one of its payments, fires the webhook to the merchant and a second copy to your platform's endpoints.

What it does not do

Two more limits are worth knowing before you design around them. Who pays a merchant depends on the connection's mode: Wajub pays a lite merchant, on a schedule or when you call POST /accounts/{id}/payouts, and a direct merchant withdraws for themselves or through an ordinary transfer you send with the X-Sync header, drawn on their balance. Paying sellers covers all three modes. And once the merchant connects, capabilities and pricing can only be changed with their agreement, which the capabilities page explains.

The header, in one place

Every route in this section is the ordinary route. What changes is one header.

curl https://api.wajub.com/payments \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
  -H "X-Sync: acc_7Yh2MpL4tRb3nP8sZcXv" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "currency": "XAF",
    "customer": { "email": "[email protected]" }
  }'

The header carries the connection's id, the value that comes back as account.id when you create one. It is not the merchant's account id and not one of your keys.

X-Sync is read on every authenticated route, not only on payments. Customers, refunds, invoices, transfers and payment links all accept it, each subject to the capability it requires, and a resource that requires none, /accounts itself included, refuses the header outright. The capabilities page lists which resource takes which.

The resources

Everything else is the normal API, called with the header.