Edit merchant
Changes the registration of one of your company’s merchants by merchant_id. It is also how you save the merchant_ref on a merchant that already existed without a reference (for example, one registered in the dashboard): after that, Create or update merchant and the Merchant batch update it by the reference.
Endpoint
Section titled “Endpoint”https://api.rapidchargeback.com/api/v1/merchants/:merchant_idAuthentication
Section titled “Authentication”Authorization: Basic base64(client_id:client_secret)Content-Type: application/jsonURL parameters
Section titled “URL parameters”| Param | Type | Description |
|---|---|---|
merchant_id | string (UUID) | The merchant id |
Request body
Section titled “Request body”Any field of Create or update merchant, all optional, with the same limits. on_name_conflict does not exist here.
- Send only what changes. A field that was not sent stays as it is;
nullor""clears it (exceptname). - Empty body (
{}):422 VALIDATION_ERROR“Send at least one field”. - Name of another merchant of yours:
409 MERCHANT_DUPLICATE, with itsmerchant_id.
merchant_ref: saved once
Section titled “merchant_ref: saved once”| Situation | Response |
|---|---|
| The merchant has no reference | Saves the one sent |
| The one sent equals the saved one | Nothing changes (unchanged, if no other field changed) |
| The merchant already has another reference | 409 MERCHANT_REF_IMMUTABLE: the reference cannot be changed |
| Another merchant of yours already uses that reference | 409 MERCHANT_REF_TAKEN, with its merchant_id |
The reference cannot be changed because transactions and webhook deliveries already made with it keep pointing to the same merchant. If two merchants need to become one, contact Rapid support.
status
Section titled “status”active or inactive. It is informational: inactive does not stop alerts or transactions. To stop receiving alerts for a merchant, request the deactivation of its enrollments.
Request example
Section titled “Request example”Save the reference from your system on a merchant that came from the dashboard:
curl -X PATCH https://api.rapidchargeback.com/api/v1/merchants/00000000-0000-0000-0000-000000000001 \ -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \ -H "Content-Type: application/json" \ -d '{ "merchant_ref": "PB-1001" }'Response
Section titled “Response”Success
Section titled “Success”HTTP/1.1 200 OK{ "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", "...": "full registration" }, "meta": { "result": "updated", "warnings": [] }}data is the full registration, the same as in Get merchant. meta.result is updated or unchanged (nothing changed, nothing saved); meta.warnings may bring the SERVICE_FIELDS_NOT_APPLIED notice (see Notice of data that does not apply right away).
Reference already saved
Section titled “Reference already saved”HTTP/1.1 409 Conflict{ "error": { "code": "MERCHANT_REF_IMMUTABLE", "message": "merchant_ref cannot be changed once set" }}Errors
Section titled “Errors”| HTTP | Code | When |
|---|---|---|
| 404 | MERCHANT_NOT_FOUND | The merchant does not exist, belongs to another company, or the id is not a UUID |
| 409 | MERCHANT_DUPLICATE | Another merchant of yours already has the name |
| 409 | MERCHANT_REF_IMMUTABLE | The merchant already has another reference |
| 409 | MERCHANT_REF_TAKEN | Another merchant of yours already uses the reference (params.merchant_id) |
| 422 | VALIDATION_ERROR, FIELD_REQUIRED, FIELD_TOO_LONG, FIELD_INVALID, FIELD_INVALID_OPTION | See Create or update merchant |
| 403 | KYB_NOT_APPROVED, COMPANY_NOT_ACTIVE, COMPANY_BLOCKED | Company without an approved registration, inactive or blocked |
| 429 | RATE_LIMIT_EXCEEDED | More than 60 writes per minute |
| 503 | SERVICE_UNAVAILABLE | Temporarily unavailable: repeat after Retry-After |
- Repeating is safe: the same edit again comes back
unchanged. - Activity: every change shows up in the dashboard Activity as made by the integration.