Ir al contenido

↑↓ navegar ↵ abrir Ctrl↵ nueva pestaña esc cerrar

Registra un merchant (tienda, marca o vendedor) de tu empresa, o actualiza el que ya existe con el mismo merchant_ref. La clave es el merchant_ref, el ID del vendedor en tu sistema: enviar el mismo registro de nuevo no crea otro merchant, y si nada cambió no se guarda nada.

Para muchos merchants a la vez, usa el Lote de merchants. El flujo completo está en la Guía de sincronización.

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

CampoTipoObligatorioLímite y regla
merchant_refstringSí1 a 100 caracteres. El ID del vendedor en tu sistema
namestringAl crear1 a 255. Único en tu empresa, sin distinguir mayúsculas ni acentos. No acepta null
statusenumNoactive o inactive. Al crear, active. Al actualizar, solo cambia si viene
store_namestringNohasta 255
merchant_urlURLNohasta 500, solo http o https
contact_phonestringNohasta 30
emailcorreoNohasta 255
mccstringNohasta 10
descriptionstringNohasta 10.000
logo_urlURLNohasta 500, solo http o https
termsstringNohasta 10.000
terms_urlURLNohasta 500, solo http o https
refund_policystringNohasta 10.000
refund_policy_urlURLNohasta 500, solo http o https
customer_service_instructionsstringNohasta 10.000
address_streetstringNohasta 255
address_numberstringNohasta 20
address_citystringNohasta 100
address_statestringNohasta 100
address_postal_codestringNohasta 20
address_countrystringNo3 letras (ej.: BRA), guardado en mayúsculas
on_name_conflictenumNoerror (por defecto) o append_ref. Ver Nombre repetido
  • El texto se recorta (salen los espacios del inicio y del final). "" y null limpian el campo.
  • Un campo fuera de la tabla se rechaza con 422 VALIDATION_ERROR (Unknown field: <nombre>).
  • Los datos de contacto y dirección son los que usa la Prevención: para solicitar la Prevención en un enrollment, el merchant necesita store_name, merchant_url y contact_phone y, según el caso, dirección completa y los datos de la tienda (ver Solicitar enrollment).

  1. Rapid busca un merchant de tu empresa con ese merchant_ref.
  2. Lo encontró: lo actualiza. El campo que no vino queda como está; null o "" lo limpia (menos name). El status solo cambia si viene. Vale también para el merchant unverified creado por una transacción con esa referencia: se actualiza y sigue unverified, salvo que venga status (active lo confirma).
  3. No lo encontró: lo crea, con el status enviado o active.
  4. Nada cambió: no guarda nada y no toca el updated_at. La respuesta dice unchanged.

Por eso puedes enviar tu base entera todos los días: lo que no cambió no genera modificación, y el filtro updated_since de Listar merchants no se llena de cambios falsos.

merchant_ref no distingue mayúsculas ni acentos

Sección titulada «merchant_ref no distingue mayúsculas ni acentos»

PB-a1 y pb-A1 son la misma referencia para Rapid. Si envías una referencia que solo difiere de la guardada en mayúsculas o acentos, la API la rechaza con 409 MERCHANT_REF_CONFLICT y no actualiza nada: dos vendedores tuyos nunca se vuelven un solo merchant. El params trae el merchant_id y el merchant_ref guardado.

El nombre es único en tu empresa, sin distinguir mayúsculas ni acentos. Si otro merchant tuyo ya tiene el nombre:

  • con on_name_conflict: "error" (por defecto), la API responde 409 MERCHANT_DUPLICATE, con el merchant_id (y el merchant_ref, cuando lo tiene) del merchant que ya tiene el nombre;
  • con on_name_conflict: "append_ref", el nombre se guarda como Nombre (merchant_ref), recortando el nombre para que quepa en 255 caracteres. Si aun así se repite, 409 MERCHANT_DUPLICATE.

El caso más común es el merchant que ya estaba registrado en el panel, sin referencia. Usa el merchant_id del 409 para guardar la referencia en él con Editar merchant (PATCH con merchant_ref): a partir de ahí este endpoint lo actualiza.

Aviso de dato que no se aplica en el momento

Sección titulada «Aviso de dato que no se aplica en el momento»

Si cambias store_name, merchant_url, contact_phone o algún campo de dirección de un merchant que ya tiene un enrollment activo, la respuesta trae el aviso SERVICE_FIELDS_NOT_APPLIED con los campos. El cambio queda guardado, pero no llega en el momento al servicio ya activo: habla con el soporte de Rapid para llevarlo adelante.


Ventana de terminal
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 es el registro completo, el mismo de Consultar merchant.

200 OK, con el mismo cuerpo y meta.result igual a updated o unchanged:

{
"data": { "id": "00000000-0000-0000-0000-000000000001", "...": "registro completo" },
"meta": {
"result": "updated",
"warnings": [{ "code": "SERVICE_FIELDS_NOT_APPLIED", "fields": ["merchant_url"] }]
}
}
meta.resultHTTPQué pasó
created201Merchant nuevo
updated200Merchant existente, algún campo cambió
unchanged200Merchant existente, nada cambió, nada guardado
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"
}
}
}

Referencia distinta solo en mayúsculas o acentos

Sección titulada «Referencia distinta solo en mayúsculas o acentos»
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" }
}
}
HTTPCódigoCuándo
422FIELD_REQUIREDFalta merchant_ref, o name al crear (params.field)
422FIELD_TOO_LONGCampo por encima del límite (params.field, params.max)
422FIELD_INVALIDURL fuera de http/https, correo o país inválido (params.field)
422FIELD_INVALID_OPTIONstatus u on_name_conflict fuera de la lista (params.field, params.options)
422VALIDATION_ERRORCampo desconocido, o cuerpo que no es un objeto JSON (params.field)
409MERCHANT_DUPLICATEOtro merchant tuyo ya tiene el nombre
409MERCHANT_REF_CONFLICTReferencia distinta de la guardada solo en mayúsculas o acentos
403KYB_NOT_APPROVEDEl registro de tu empresa todavía no fue aprobado
403COMPANY_NOT_ACTIVELa empresa no está activa
403COMPANY_BLOCKEDEmpresa bloqueada
429RATE_LIMIT_EXCEEDEDMás de 60 escrituras por minuto (ver Rate limit)
503SERVICE_UNAVAILABLENo disponible temporalmente: repite después del Retry-After

  • Repetir es seguro. Después de un 503 o de una caída de conexión, envía la misma llamada: la clave es el merchant_ref, y el resultado vuelve created, updated o unchanged, nunca un merchant duplicado.
  • El status es informativo. inactive no detiene alertas ni transacciones. Para dejar de recibir alertas de un merchant, solicita la desactivación de sus enrollments.
  • Solo tu empresa. La empresa viene de la credencial; no hay campo para elegir otra.
  • Actividad: cada registro y cada modificación aparece en la Actividad del panel como hecha por la integración.