Skip to content

↑↓ navigate ↵ open Ctrl↵ new tab esc close

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.

PATCH https://api.rapidchargeback.com/api/v1/merchants/:merchant_id
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json

ParamTypeDescription
merchant_idstring (UUID)The merchant id

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; null or "" clears it (except name).
  • Empty body ({}): 422 VALIDATION_ERROR “Send at least one field”.
  • Name of another merchant of yours: 409 MERCHANT_DUPLICATE, with its merchant_id.
SituationResponse
The merchant has no referenceSaves the one sent
The one sent equals the saved oneNothing changes (unchanged, if no other field changed)
The merchant already has another reference409 MERCHANT_REF_IMMUTABLE: the reference cannot be changed
Another merchant of yours already uses that reference409 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.

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.


Save the reference from your system on a merchant that came from the dashboard:

Terminal window
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" }'

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).

HTTP/1.1 409 Conflict
{
"error": {
"code": "MERCHANT_REF_IMMUTABLE",
"message": "merchant_ref cannot be changed once set"
}
}
HTTPCodeWhen
404MERCHANT_NOT_FOUNDThe merchant does not exist, belongs to another company, or the id is not a UUID
409MERCHANT_DUPLICATEAnother merchant of yours already has the name
409MERCHANT_REF_IMMUTABLEThe merchant already has another reference
409MERCHANT_REF_TAKENAnother merchant of yours already uses the reference (params.merchant_id)
422VALIDATION_ERROR, FIELD_REQUIRED, FIELD_TOO_LONG, FIELD_INVALID, FIELD_INVALID_OPTIONSee Create or update merchant
403KYB_NOT_APPROVED, COMPANY_NOT_ACTIVE, COMPANY_BLOCKEDCompany without an approved registration, inactive or blocked
429RATE_LIMIT_EXCEEDEDMore than 60 writes per minute
503SERVICE_UNAVAILABLETemporarily 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.