Quickstart

Four steps, and the third one is not yours to do. A connection only becomes usable once the merchant signs in and accepts it, so plan for a round trip through a human before your first payment.

Everything here needs your platform's secret key and a Scale plan.

1. Create the connection

You declare what the connection may do and what you will retain on it. Capabilities are required and cannot be empty, pricing is optional. callback is the page the merchant comes back to once they have accepted, not a webhook URL: no event is ever sent there.

curl https://api.wajub.com/accounts \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "shop-amina",
    "capabilities": ["read", "payments", "refunds"],
    "pricing": { "percentage_fee": 2.5, "currency": "XAF" },
    "callback": "https://example.com/connected"
  }'

The answer is 201 Created. Two fields matter more than the rest.

id is the value you will send as X-Sync. authorization_url is the link the merchant has to open, and this response is the only place it appears. Send it or store it now, because reading the subaccount later will not give it back. POST /accounts/{id}/token mints a replacement.

2. Send the merchant their link

Put authorization_url in front of the merchant however suits you: an email, a button in your own onboarding, a QR code. They open it, sign in to their Wajub account, review the capabilities you asked for, and accept.

Once they accept, status flips to active and slave carries their business name and email. You find out either by polling the account or by receiving account.connected on one of your platform's webhook endpoints. Register the endpoint in the Dashboard or with POST /webhooks and list account.connected by name: a * subscription does not receive it. Sync lifecycle deliveries describes what arrives.

3. Wait for payments to be switched on

In sandbox, payment_status turns active the moment the merchant accepts, and you can charge straight away. In live it depends on the merchant: already verified, the connection is active at once; still under review, it stays inactive until their verification clears, and Wajub then sends account.payment_activated. A lite connection also waits for the Wajub rail to be granted to the merchant.

4. Take a payment on it

From here it is the ordinary payments API. One header decides who the payment belongs to.

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]" },
    "callback": "https://example.com/return"
  }'

The payment belongs to the merchant from this point on. It appears in their Dashboard, settles into their balance, and their webhooks fire. Yours fire too, with a copy of the same event.

What you get back when it succeeds

When the payment completes, Wajub applies the connection's pricing, computes your commission on the payment amount, and credits it to your platform. You are told by webhook.

The reference under account repeats the connection id rather than your own reference. Reconcile commissions per connection, on account.id.

The merchant receives the mirror of it, fee.charged, on their own endpoints. Between the two, both sides of the commission are auditable without either of you asking the other.