List merchants
Lists your company’s merchants (stores, brands or sellers). This is where the merchant_id comes from, which create transaction, send event from the server and request enrollment require.
To create and edit merchants through the API, see Create or update merchant, Merchant batch and the Sync guide.
Endpoint
Section titled “Endpoint”https://api.rapidchargeback.com/api/v1/merchantsAuthentication
Section titled “Authentication”Authorization: Basic base64(client_id:client_secret)Query params
Section titled “Query params”All optional.
| Param | Type | Default | Description |
|---|---|---|---|
page | int (≥ 1) | 1 | Page |
per_page | int (1–100) | 20 | Items per page |
merchant_ref | string (up to 100) | - | The seller ID in your system, the same merchant_ref accepted in create transaction. Returns 0 or 1 item. The comparison ignores case and accents |
status | enum | - | active, inactive or unverified |
updated_since | ISO 8601 date and time with time zone | - | Only merchants changed from that moment on (e.g. 2026-11-06T12:00:00Z or 2026-11-06T09:00:00-03:00). Without a time zone, the API rejects it with 422 |
Without updated_since, the list comes in registration order (oldest first). To go through all of them, increase page until it reaches total_pages: a merchant registered along the way goes to the end, so you never skip or repeat an item.
Syncing what changed
Section titled “Syncing what changed”With updated_since, the list brings only what changed from that moment on, oldest first (updated_at, then id). To follow the changes without missing any:
- Keep the highest
updated_atyou received. - On the next query, send that value minus 2 minutes as
updated_since. - Skip the (
id,updated_at) pair you already processed. - Read the pages up to
total_pages.
The 2-minute margin covers a change saved out of order or during your read.
Examples
Section titled “Examples”All merchants
Section titled “All merchants”curl -G "https://api.rapidchargeback.com/api/v1/merchants" \ --data-urlencode "per_page=100" \ -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="By the seller ID in your system
Section titled “By the seller ID in your system”curl -G "https://api.rapidchargeback.com/api/v1/merchants" \ --data-urlencode "merchant_ref=PB-1001" \ -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="What changed since the last read
Section titled “What changed since the last read”curl -G "https://api.rapidchargeback.com/api/v1/merchants" \ --data-urlencode "updated_since=2026-11-06T11:58:00Z" \ --data-urlencode "per_page=100" \ -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="Response
Section titled “Response”Success
Section titled “Success”{ "data": [ { "id": "00000000-0000-0000-0000-000000000001", "name": "Loja Exemplo", "merchant_ref": "PB-1001", "status": "active", "created_at": "2026-03-10T12:00:00.000Z", "updated_at": "2026-11-06T12:00:00.000Z" } ], "meta": { "page": 1, "per_page": 20, "total": 1, "total_pages": 1 }}| Field | Description |
|---|---|
id | The merchant_id the other APIs require |
name | Merchant name |
merchant_ref | The seller ID in your system, saved by the merchants API or by a new merchant_ref in create transaction. null when it was never provided |
status | active, inactive or unverified: the registration status. unverified is the merchant created automatically by a new merchant_ref in create transaction, until Rapid checks the registration or you confirm it with status: "active" in Create or update merchant or Edit merchant. The status changes nothing in how it works: the merchant’s transactions and events are accepted the same way |
created_at | When it was registered |
updated_at | When the registration last changed |
The list brings only these fields. The full registration (contact, address, terms) is in Get merchant.
No results
Section titled “No results”{ "data": [], "meta": { "page": 1, "per_page": 20, "total": 0, "total_pages": 0 }}Invalid parameter (e.g. per_page=500)
Section titled “Invalid parameter (e.g. per_page=500)”{ "error": { "code": "VALIDATION_ERROR", "message": "Number must be less than or equal to 100" }}updated_since without a time zone
Section titled “updated_since without a time zone”{ "error": { "code": "VALIDATION_ERROR", "message": "updated_since must be an ISO 8601 date and time with a time zone (e.g. 2026-11-06T12:00:00Z)", "params": { "field": "updated_since" } }}- Only your company’s merchants. The company comes from the credential; there is no parameter to pick another one.
- Unknown parameters are still ignored on this route, but they will start being rejected with
422, as on the new routes: send only the parameters in the table (see API changelog). - Blocked company receives
403 COMPANY_BLOCKED, as in the other APIs. - Auth, rate limit, error codes: see Authentication and Response codes.