Crear o actualizar merchant
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.
Endpoint
Sección titulada «Endpoint»https://api.rapidchargeback.com/api/v1/merchantsAutenticación
Sección titulada «Autenticación»Authorization: Basic base64(client_id:client_secret)Content-Type: application/jsonCuerpo de la solicitud
Sección titulada «Cuerpo de la solicitud»| Campo | Tipo | Obligatorio | Límite y regla |
|---|---|---|---|
merchant_ref | string | Sí | 1 a 100 caracteres. El ID del vendedor en tu sistema |
name | string | Al crear | 1 a 255. Único en tu empresa, sin distinguir mayúsculas ni acentos. No acepta null |
status | enum | No | active o inactive. Al crear, active. Al actualizar, solo cambia si viene |
store_name | string | No | hasta 255 |
merchant_url | URL | No | hasta 500, solo http o https |
contact_phone | string | No | hasta 30 |
email | correo | No | hasta 255 |
mcc | string | No | hasta 10 |
description | string | No | hasta 10.000 |
logo_url | URL | No | hasta 500, solo http o https |
terms | string | No | hasta 10.000 |
terms_url | URL | No | hasta 500, solo http o https |
refund_policy | string | No | hasta 10.000 |
refund_policy_url | URL | No | hasta 500, solo http o https |
customer_service_instructions | string | No | hasta 10.000 |
address_street | string | No | hasta 255 |
address_number | string | No | hasta 20 |
address_city | string | No | hasta 100 |
address_state | string | No | hasta 100 |
address_postal_code | string | No | hasta 20 |
address_country | string | No | 3 letras (ej.: BRA), guardado en mayúsculas |
on_name_conflict | enum | No | error (por defecto) o append_ref. Ver Nombre repetido |
- El texto se recorta (salen los espacios del inicio y del final).
""ynulllimpian 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_urlycontact_phoney, según el caso, dirección completa y los datos de la tienda (ver Solicitar enrollment).
Cómo funciona
Sección titulada «Cómo funciona»- Rapid busca un merchant de tu empresa con ese
merchant_ref. - Lo encontró: lo actualiza. El campo que no vino queda como está;
nullo""lo limpia (menosname). Elstatussolo cambia si viene. Vale también para el merchantunverifiedcreado por una transacción con esa referencia: se actualiza y sigueunverified, salvo que vengastatus(activelo confirma). - No lo encontró: lo crea, con el
statusenviado oactive. - Nada cambió: no guarda nada y no toca el
updated_at. La respuesta diceunchanged.
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.
Nombre repetido
Sección titulada «Nombre repetido»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 responde409 MERCHANT_DUPLICATE, con elmerchant_id(y elmerchant_ref, cuando lo tiene) del merchant que ya tiene el nombre; - con
on_name_conflict: "append_ref", el nombre se guarda comoNombre (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.
Ejemplo de solicitud
Sección titulada «Ejemplo de solicitud»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" }'Respuesta
Sección titulada «Respuesta»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.
Actualizado o sin cambios
Sección titulada «Actualizado o sin cambios»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.result | HTTP | Qué pasó |
|---|---|---|
created | 201 | Merchant nuevo |
updated | 200 | Merchant existente, algún campo cambió |
unchanged | 200 | Merchant existente, nada cambió, nada guardado |
Nombre de otro merchant
Sección titulada «Nombre de otro 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" } }}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" } }}Campo inválido
Sección titulada «Campo inválido»HTTP/1.1 422 Unprocessable Entity{ "error": { "code": "FIELD_INVALID", "message": "merchant_url: Invalid url", "params": { "field": "merchant_url" } }}Errores
Sección titulada «Errores»| HTTP | Código | Cuándo |
|---|---|---|
| 422 | FIELD_REQUIRED | Falta merchant_ref, o name al crear (params.field) |
| 422 | FIELD_TOO_LONG | Campo por encima del límite (params.field, params.max) |
| 422 | FIELD_INVALID | URL fuera de http/https, correo o país inválido (params.field) |
| 422 | FIELD_INVALID_OPTION | status u on_name_conflict fuera de la lista (params.field, params.options) |
| 422 | VALIDATION_ERROR | Campo desconocido, o cuerpo que no es un objeto JSON (params.field) |
| 409 | MERCHANT_DUPLICATE | Otro merchant tuyo ya tiene el nombre |
| 409 | MERCHANT_REF_CONFLICT | Referencia distinta de la guardada solo en mayúsculas o acentos |
| 403 | KYB_NOT_APPROVED | El registro de tu empresa todavía no fue aprobado |
| 403 | COMPANY_NOT_ACTIVE | La empresa no está activa |
| 403 | COMPANY_BLOCKED | Empresa bloqueada |
| 429 | RATE_LIMIT_EXCEEDED | Más de 60 escrituras por minuto (ver Rate limit) |
| 503 | SERVICE_UNAVAILABLE | No disponible temporalmente: repite después del Retry-After |
- Repetir es seguro. Después de un
503o de una caída de conexión, envía la misma llamada: la clave es elmerchant_ref, y el resultado vuelvecreated,updatedounchanged, nunca un merchant duplicado. - El
statuses informativo.inactiveno 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.