Skip to content

↑↓ navigate ↵ open Ctrl↵ new tab esc close

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.

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

FieldTypeRequiredLimit and rule
merchant_refstringYes1 to 100 characters. The seller ID in your system
namestringOn create1 to 255. Unique in your company, ignoring case and accents. Does not accept null
statusenumNoactive or inactive. On create, active. On update, it only changes if sent
store_namestringNoup to 255
merchant_urlURLNoup to 500, http or https only
contact_phonestringNoup to 30
emailemailNoup to 255
mccstringNoup to 10
descriptionstringNoup to 10,000
logo_urlURLNoup to 500, http or https only
termsstringNoup to 10,000
terms_urlURLNoup to 500, http or https only
refund_policystringNoup to 10,000
refund_policy_urlURLNoup to 500, http or https only
customer_service_instructionsstringNoup to 10,000
address_streetstringNoup to 255
address_numberstringNoup to 20
address_citystringNoup to 100
address_statestringNoup to 100
address_postal_codestringNoup to 20
address_countrystringNo3 letters (e.g. BRA), saved in uppercase
on_name_conflictenumNoerror (default) or append_ref. See Repeated name
  • Text is trimmed (leading and trailing spaces are removed). "" and null clear 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_url and contact_phone and, depending on the case, a full address and the store details (see Request enrollment).

  1. Rapid looks for a merchant of your company with that merchant_ref.
  2. Found: updates it. A field that was not sent stays as it is; null or "" clears it (except name). status only changes if sent. This also applies to an unverified merchant created by a transaction with that reference: it is updated and stays unverified unless status is sent (active confirms it).
  3. Not found: creates it, with the status sent or active.
  4. Nothing changed: saves nothing and does not touch updated_at. The response says unchanged.

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.

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.

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 responds 409 MERCHANT_DUPLICATE, with the merchant_id (and the merchant_ref, when it has one) of the merchant that already has the name;
  • with on_name_conflict: "append_ref", the name is saved as Name (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.


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

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.

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.resultHTTPWhat happened
created201New merchant
updated200Existing merchant, some field changed
unchanged200Existing merchant, nothing changed, nothing saved
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"
}
}
}
HTTP/1.1 422 Unprocessable Entity
{
"error": {
"code": "FIELD_INVALID",
"message": "merchant_url: Invalid url",
"params": { "field": "merchant_url" }
}
}
HTTPCodeWhen
422FIELD_REQUIREDmerchant_ref is missing, or name on create (params.field)
422FIELD_TOO_LONGField above the limit (params.field, params.max)
422FIELD_INVALIDURL other than http/https, invalid email or country (params.field)
422FIELD_INVALID_OPTIONstatus or on_name_conflict outside the list (params.field, params.options)
422VALIDATION_ERRORUnknown field, or a body that is not a JSON object (params.field)
409MERCHANT_DUPLICATEAnother merchant of yours already has the name
409MERCHANT_REF_CONFLICTReference differs from the saved one only in case or accents
403KYB_NOT_APPROVEDYour company’s registration has not been approved yet
403COMPANY_NOT_ACTIVEThe company is not active
403COMPANY_BLOCKEDBlocked company
429RATE_LIMIT_EXCEEDEDMore than 60 writes per minute (see Rate limit)
503SERVICE_UNAVAILABLETemporarily unavailable: repeat after Retry-After

  • Repeating is safe. After a 503 or a dropped connection, send the same call: the key is the merchant_ref, and the result comes back created, updated or unchanged, never a duplicated merchant.
  • status is informational. inactive does 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.