Subaccounts
Create and manage merchant subaccounts for marketplaces and platforms.
Subaccounts let a platform connect merchants and route a share of each payment to them automatically. Part of the Sync product.
private key required
Creating and managing subaccounts requires the private key (sk...).
Endpoints
| Method | Path | Description |
|---|---|---|
POST | /accounts | Create |
GET | /accounts/{id} | Retrieve |
GET | /accounts | List |
PUT | /accounts/{id} | Update |
DELETE | /accounts/{id} | Delete |
POST | /accounts/{id}/token | Regenerate the OAuth authorization token |
The path is /accounts
This resource is exposed under /accounts, not /subaccounts, subaccounts here refers to the
product concept (merchants connected under your platform), matching the "Sync" product name.
The Account (subaccount) object
idstringfacultatifreferencestring?facultatifsandboxbooleanfacultatiftrue for a test-mode sub-account.capabilitiesstring[]facultatifprofileobjectfacultatifcallbackstring?facultatifredirect_uri on the authorization link is only honoured when it shares that origin, and refused otherwise. Without a callback, no redirect_uri is accepted.account_typeenumfacultatifdirect (the merchant runs a full Wajub account), lite (a hosted portal, always collecting on the Wajub rail) or relay (no merchant account — you collect and Wajub relays the payouts). Defaults to direct, and cannot be changed afterwards.commission_refund_policyenumfacultatifprorata (default, in proportion to the refund), full (all of it, on the first refund) or none. Settable at creation, and editable only while the connection is pending.statusenumfacultatifpayment_statusenumfacultatifactive or inactive, whether payment capability is currently enabled.authorization_urlstring?facultatifmasterobject?facultatif{ id, name }.slaveobject?facultatif{ id, name, email }.pricingobject?facultatif{ percentage_fee, fixed_fee, max_fee, currency }.expires_atdatetime?facultatifcreated_atdatetimefacultatifCreating a subaccount
The pricing object accepts percentage_fee, fixed_fee, max_fee, min_fee (all optional,
numeric), and currency (required if any fixed/min/max fee is set):
curl https://api.wajub.com/accounts \
-H "Authorization: sk.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…" \
-H "Content-Type: application/json" \
-d '{
"reference": "vendor-482",
"capabilities": ["payments"],
"pricing": { "percentage_fee": 10, "currency": "XAF" }
}'Acting on behalf of a subaccount - the X-Sync header
Once a subaccount is active, the platform can act as it by sending its id in the
X-Sync header alongside the platform's own API key. When present and valid, the request runs
against the subaccount's team instead of the platform's, resources are created under the
subaccount, and its own pricing is applied automatically.
What the platform sees is what this connection brought: its payments, their refunds, the customers who bought through it, the payouts it sent. The merchant's own sales and other platforms' are out of scope, whatever capabilities were granted.
X-Syncheaderfacultatifid (e.g. acc_7Yh2Mp), not its reference. Sent alongside the platform's Authorization key.curl https://api.wajub.com/payments \
-H "Authorization: sk.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…" \
-H "X-Sync: acc_7Yh2Mp" \
-d '{ "amount": 10000, "currency": "XAF", "email": "client@example.com" }'On a live connection, PUT /accounts/{id} does not change capabilities or pricing outright: it
answers 202 Accepted with the proposal in pending_changes, and the merchant accepts or declines
it in their own dashboard. payment_status and callback still apply immediately.
Every resource states the capability it takes, and a resource that states none cannot be reached
with X-Sync at all — that is the case for /accounts/*, which you always manage with your own
key, and for /keys/current, which revokes your key rather than the subaccount's:
| If the request touches | Required capability |
|---|---|
/payments, /links | payments |
/invoices | invoices |
/customers, /customers/{id}/tax_ids | customers |
/refunds | refunds |
/disputes | disputes |
/transfers, /beneficiaries, /identity | withdrawals |
/webhooks, /tax, /shield | settings |
/, /providers, /balance, /events, /listen | read |
/channels, /countries, /currencies | none — catalogues |
/accounts, /keys/current | not available with X-Sync |
Checks performed, in order
404, no subaccount exists for thatid. 2.403, the authenticated key's team isn't this subaccount's platform (only the platform that created it can act on its behalf). 3.403, the subaccount isn'tactive(stillpending, orcancelled/expired). 4.403, environment mismatch: the API key and the subaccount must both be live, or both sandbox. 5.403, the resource cannot be called on behalf of a subaccount at all (see the last row above). 6.403, the subaccount is missing the capability the resource requires.403, forpayments,withdrawalsandrefunds, additionally blocked if the subaccount'spayment_statusisn'tactive— collection, payouts and refunds are suspended together, even ifcapabilitiesstill lists them.