Create or update merchant
Creates a merchant (store, brand or seller) for your company, or updates the one that already exists with the same merchant_ref. The key is the merchant_ref, the seller ID in your system: sending the same registration again does not create another merchant, and if nothing changed nothing is saved.
For many merchants at once, use the Merchant batch. The full flow is in the Sync guide.
Endpoint
Section titled “Endpoint”https://api.rapidchargeback.com/api/v1/merchantsAuthentication
Section titled “Authentication”Authorization: Basic base64(client_id:client_secret)Content-Type: application/jsonRequest body
Section titled “Request body”| Field | Type | Required | Limit and rule |
|---|---|---|---|
merchant_ref | string | Yes | 1 to 100 characters. The seller ID in your system |
name | string | On create | 1 to 255. Unique in your company, ignoring case and accents. Does not accept null |
status | enum | No | active or inactive. On create, active. On update, it only changes if sent |
store_name | string | No | up to 255 |
merchant_url | URL | No | up to 500, http or https only |
contact_phone | string | No | up to 30 |
email | No | up to 255 | |
mcc | string | No | up to 10 |
description | string | No | up to 10,000 |
logo_url | URL | No | up to 500, http or https only |
terms | string | No | up to 10,000 |
terms_url | URL | No | up to 500, http or https only |
refund_policy | string | No | up to 10,000 |
refund_policy_url | URL | No | up to 500, http or https only |
customer_service_instructions | string | No | up to 10,000 |
address_street | string | No | up to 255 |
address_number | string | No | up to 20 |
address_city | string | No | up to 100 |
address_state | string | No | up to 100 |
address_postal_code | string | No | up to 20 |
address_country | string | No | 3 letters (e.g. BRA), saved in uppercase |
on_name_conflict | enum | No | error (default) or append_ref. See Repeated name |
- Text is trimmed (leading and trailing spaces are removed).
""andnullclear the field. - A field outside the table is rejected with
422 VALIDATION_ERROR(Unknown field: <name>). - The contact and address data is what Prevention uses: to request Prevention on an enrollment, the merchant needs
store_name,merchant_urlandcontact_phoneand, depending on the case, a full address and the store details (see Request enrollment).
How it works
Section titled “How it works”- Rapid looks for a merchant of your company with that
merchant_ref. - Found: updates it. A field that was not sent stays as it is;
nullor""clears it (exceptname).statusonly changes if sent. This also applies to anunverifiedmerchant created by a transaction with that reference: it is updated and staysunverifiedunlessstatusis sent (activeconfirms it). - Not found: creates it, with the
statussent oractive. - Nothing changed: saves nothing and does not touch
updated_at. The response saysunchanged.
That is why you can send your whole base every day: what did not change creates no change, and the updated_since filter in List merchants does not fill up with false changes.
merchant_ref ignores case and accents
Section titled “merchant_ref ignores case and accents”PB-a1 and pb-A1 are the same reference for Rapid. If you send a reference that differs from the saved one only in case or accents, the API rejects it with 409 MERCHANT_REF_CONFLICT and updates nothing: two of your sellers never become a single merchant. params brings the merchant_id and the saved merchant_ref.
Repeated name
Section titled “Repeated name”The name is unique in your company, ignoring case and accents. If another merchant of yours already has the name:
- with
on_name_conflict: "error"(default), the API responds409 MERCHANT_DUPLICATE, with themerchant_id(and themerchant_ref, when it has one) of the merchant that already has the name; - with
on_name_conflict: "append_ref", the name is saved asName (merchant_ref), cutting the name to fit 255 characters. If it still repeats,409 MERCHANT_DUPLICATE.
The most common case is a merchant already registered in the dashboard, with no reference. Use the merchant_id from the 409 to save the reference on it with Edit merchant (PATCH with merchant_ref): from then on this endpoint updates it.
Notice of data that does not apply right away
Section titled “Notice of data that does not apply right away”If you change store_name, merchant_url, contact_phone or any address field of a merchant that already has an active enrollment, the response brings the SERVICE_FIELDS_NOT_APPLIED notice with the fields. The change is saved, but it does not reach the active service right away: contact Rapid support to carry it forward.
Request example
Section titled “Request example”curl -X POST https://api.rapidchargeback.com/api/v1/merchants \ -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \ -H "Content-Type: application/json" \ -d '{ "merchant_ref": "PB-1001", "name": "Loja Exemplo", "store_name": "Loja Exemplo", "merchant_url": "https://lojaexemplo.com", "contact_phone": "+55 11 99999-0000", "address_country": "BRA" }'Response
Section titled “Response”Created
Section titled “Created”HTTP/1.1 201 Created{ "data": { "id": "00000000-0000-0000-0000-000000000001", "name": "Loja Exemplo", "merchant_ref": "PB-1001", "status": "active", "created_at": "2026-11-06T12:00:00.000Z", "updated_at": "2026-11-06T12:00:00.000Z", "store_name": "Loja Exemplo", "merchant_url": "https://lojaexemplo.com", "contact_phone": "+55 11 99999-0000", "email": null, "mcc": null, "description": null, "logo_url": null, "terms": null, "terms_url": null, "refund_policy": null, "refund_policy_url": null, "customer_service_instructions": null, "address_street": null, "address_number": null, "address_city": null, "address_state": null, "address_postal_code": null, "address_country": "BRA" }, "meta": { "result": "created", "warnings": [] }}data is the full registration, the same as in Get merchant.
Updated or unchanged
Section titled “Updated or unchanged”200 OK, with the same body and meta.result equal to updated or unchanged:
{ "data": { "id": "00000000-0000-0000-0000-000000000001", "...": "full registration" }, "meta": { "result": "updated", "warnings": [{ "code": "SERVICE_FIELDS_NOT_APPLIED", "fields": ["merchant_url"] }] }}meta.result | HTTP | What happened |
|---|---|---|
created | 201 | New merchant |
updated | 200 | Existing merchant, some field changed |
unchanged | 200 | Existing merchant, nothing changed, nothing saved |
Name of another merchant
Section titled “Name of another merchant”HTTP/1.1 409 Conflict{ "error": { "code": "MERCHANT_DUPLICATE", "message": "A merchant with this name already exists", "params": { "name": "Loja Exemplo", "merchant_id": "00000000-0000-0000-0000-000000000001" } }}Reference differing only in case or accents
Section titled “Reference differing only in case or accents”HTTP/1.1 409 Conflict{ "error": { "code": "MERCHANT_REF_CONFLICT", "message": "A merchant with this merchant_ref already exists with different case or accents", "params": { "merchant_id": "00000000-0000-0000-0000-000000000001", "merchant_ref": "PB-1001" } }}Invalid field
Section titled “Invalid field”HTTP/1.1 422 Unprocessable Entity{ "error": { "code": "FIELD_INVALID", "message": "merchant_url: Invalid url", "params": { "field": "merchant_url" } }}Errors
Section titled “Errors”| HTTP | Code | When |
|---|---|---|
| 422 | FIELD_REQUIRED | merchant_ref is missing, or name on create (params.field) |
| 422 | FIELD_TOO_LONG | Field above the limit (params.field, params.max) |
| 422 | FIELD_INVALID | URL other than http/https, invalid email or country (params.field) |
| 422 | FIELD_INVALID_OPTION | status or on_name_conflict outside the list (params.field, params.options) |
| 422 | VALIDATION_ERROR | Unknown field, or a body that is not a JSON object (params.field) |
| 409 | MERCHANT_DUPLICATE | Another merchant of yours already has the name |
| 409 | MERCHANT_REF_CONFLICT | Reference differs from the saved one only in case or accents |
| 403 | KYB_NOT_APPROVED | Your company’s registration has not been approved yet |
| 403 | COMPANY_NOT_ACTIVE | The company is not active |
| 403 | COMPANY_BLOCKED | Blocked company |
| 429 | RATE_LIMIT_EXCEEDED | More than 60 writes per minute (see Rate limit) |
| 503 | SERVICE_UNAVAILABLE | Temporarily unavailable: repeat after Retry-After |
- Repeating is safe. After a
503or a dropped connection, send the same call: the key is themerchant_ref, and the result comes backcreated,updatedorunchanged, never a duplicated merchant. statusis informational.inactivedoes not stop alerts or transactions. To stop receiving alerts for a merchant, request the deactivation of its enrollments.- Only your company. The company comes from the credential; there is no field to pick another one.
- Activity: every creation and every change shows up in the dashboard Activity as made by the integration.