Who receives the money
A merchant is a saved payout destination — a bank account, a mobile-money number,
or a Lightning Address. Create one once, then reference its id from any payment. The
fields you provide depend on the destination country.
The merchant object
Two fields are always required; the rest depend on country. Use the selector on
the right to see exactly what each destination needs.
{
"name": "My SA Merchant",
"country": "SouthAfrica",
"bankName": "CAPITEC BANK",
"accountNumber": "1325558779"
}bankName/accountNumber,
networkProvider/contactNumber, or lnurl.Endpoints
Create a merchant
Register a payout destination. The payload varies by destination country; for bank
merchants, bankName must match a valid name for that country.
countryis the literal"SouthAfrica"(no space).namemust match/^[a-zA-Z0-9 @/().,_-]{0,254}$/.- Accounts are check-digit (CDV) validated on creation, catching mistyped account numbers.
- Pull valid bank names from Utils.
{
"name": "Test Merchant",
"country": "SouthAfrica",
"bankName": "CAPITEC BANK",
"accountNumber": "1325558779"
}List merchants
Paginated, like payments. Feed the offsetMarker back as offset to page;
null means the end.
{
"items": [
{
"id": "0c83ca77-c1e2-4e04-9932-9541e535b3e6",
"name": "My SA Merchant",
"country": "SouthAfrica",
"bankName": "CAPITEC BANK",
"accountNumber": "1325558779"
}
],
"offsetMarker": "%7B%22id%22%3A%220c83...%22%7D"
}Retrieve a merchant
Fetch a single merchant by ID — same shape as a list item.
{
"id": "0c83ca77-c1e2-4e04-9932-9541e535b3e6",
"name": "My SA Merchant",
"country": "SouthAfrica",
"bankName": "CAPITEC BANK",
"bankCode": "470010",
"accountNumber": "1325558779"
}Update a merchant
Send only the fields you want to change — it's a partial update. The response is the updated merchant. (There is no delete endpoint; merchants are updated, not removed.)
{
"name": "Renamed Merchant"
}