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
idstringoptionalreferencestring?optionalsandboxbooleanoptionalcapabilitiesstring[]optionalprofileobjectoptionalcallbackstring?optionalstatusenumoptionalpayment_statusenumoptionalauthorization_urlstring?optionalmasterobject?optionalslaveobject?optionalpricingobject?optionalexpires_atdatetime?optionalcreated_atdatetimeoptionalCreating 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.xxxx" \
-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.
X-Syncheaderoptionalcurl https://api.wajub.com/payments \
-H "Authorization: sk.xxxx" \
-H "X-Sync: acc_7Yh2Mp" \
-d '{ "amount": 10000, "currency": "XAF", "email": "client@example.com" }'X-Sync is only meaningful on routes the platform calls with its own key — sending it on
/accounts/* itself has no effect on how you manage the subaccount, only on which team the
request is attributed to. It is honored across the API; the four resources below additionally
require the subaccount to hold the matching capabilities entry:
| If the request touches | Required capability |
|---|---|
/payments, /payment-links | payments |
/transfers | withdrawals |
/customers | customers |
/refunds | refunds |
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 subaccount is missing the capability required for the resource being called (see table above). 6.403— for/payments//payment-linksand/transfers, additionally blocked if the subaccount'spayment_statusisn'tactive(payouts and collection are suspended together, even ifcapabilitiesstill lists them).