Placetopay Docs

POST/api/merchants

Crear un comercio

Valida el comercio completo y lo acepta para su registro. La respuesta llega antes de que el comercio exista: trae un processId con el que consultar el resultado.

El selector de la solicitud recorre tres escenarios: el cuerpo mínimo, un comercio con sus sitios y medios de pago —donde se ve lo que un sitio obliga a enviar— y el cuerpo con todos los campos que la petición acepta.

Las tres colecciones del cuerpo —integrations, paymentMethods y sites— tienen reglas propias de identidad y actualización que se explican en Integraciones, Medios de pago y Sitios.

Cabecera

Name
Authorization
Type
Authorization
is Required
REQUERIDO
Description
Token de acceso con el permiso onboarding:create.
Ejemplo:Bearer 1|tu-token-de-acceso
Name
Idempotency-Key
Type
Idempotency-Key
is Required
REQUERIDO
Description
Identificador único de la operación. Entre 16 y 64 caracteres, y solo puede contener letras, dígitos y los signos _, ., : y -. Reenviar la misma clave con el mismo contenido devuelve el proceso original en lugar de crear uno nuevo.
Ejemplo:8f1c2d3e4a5b6c7d8e9f0a1b
Patrón:^[A-Za-z0-9_.:-]{16,64}$
Longitud máxima:64
Longitud mínima:16
Name
Content-Type
Type
Content-Type
is Required
REQUERIDO
Description
Ejemplo:application/json
Name
Accept
Type
Accept
is optional
Description
Recomendado, para que los errores lleguen en formato JSON.
Ejemplo:application/json

Solicitud

Estado del comercio. Los campos viajan en la raíz del cuerpo, junto a las colecciones.

Una clave desconocida en la raíz se ignora en silencio; dentro de un elemento de cualquier colección, en cambio, responde 422 nombrándola.

Name
name
Type
string
is Required
REQUERIDO
Description
Razón social del comercio.
Ejemplo:Comercializadora Acme S.A.S.
Longitud máxima:80
Name
brand
Type
string
is Required
REQUERIDO
Description
Nombre comercial, el que ve el comprador.
Ejemplo:Acme
Longitud máxima:60
Name
active
Type
boolean
is optional
Description
Si el comercio queda habilitado.
Valor por defecto:true
Ejemplo:true
Name
url
Type
string|null
is optional
Description
Sitio web del comercio.
Ejemplo:https://acme.example.com
Formato:uri
Longitud máxima:255
Name
incrementType
Type
string
is optional
Description
Referencia usada para incrementos.
Valores permitidos:SMLMVIPC
Ejemplo:SMLMV
Name
mcc
Type
string
is optional
Description
Código de categoría de comercio. Debe existir en el catálogo.
Ejemplo:5411
Name
size
Type
string
is optional
Description
Tamaño del comercio, del catálogo de tamaños: XS microempresa (menos de 10 empleados), S pequeña empresa (menos de 50), M mediana empresa (menos de 250) y L gran empresa (más de 250).
Valores permitidos:XSSML
Ejemplo:M
Name
timezone
Type
string
is optional
Description
Zona horaria en formato IANA, del catálogo de zonas.
Ejemplo:America/Bogota
Name
languages
Type
array
is Required
REQUERIDO
Description
Idiomas con los que opera el comercio. Es un conjunto: repetir un valor responde 422, y la comparación ignora mayúsculas.
Ejemplo:esen
Name
currencies
Type
array
is Required
REQUERIDO
Description
Monedas que el comercio maneja, como códigos ISO del catálogo. Es un conjunto, igual que languages.
Ejemplo:COPUSD
Name
document
Type
Document
is Required
REQUERIDO
Description
Documento de identificación fiscal del comercio.
Name
address
Type
Address
is Required
REQUERIDO
Description
Dirección fiscal del comercio.
Name
legalRepresentative
Type
LegalRepresentative
is Required
REQUERIDO
Description
Name
billing
Type
Billing
is optional
Description
Datos de facturación del comercio.
Name
travelAgency
Type
TravelAgency
is optional
Description
Aplicable solo a comercios del sector turismo.
Name
control
Type
Control
is Required
REQUERIDO
Description
Estructura comercial bajo la que queda registrado el comercio.
Name
integrations
Type
array[Integration]
is optional
Description
Integraciones del comercio con proveedores externos. Es un upsert por type: una integración que el cuerpo no nombra sobrevive intacta, y no hay forma de eliminarla.
Name
paymentMethods
Type
array[PaymentMethod]
is optional
Description
Medios de pago que el comercio acepta. Un elemento o modifica uno existente por su id, o registra uno nuevo con code; nunca las dos cosas.
Name
sites
Type
array[Site]
is optional
Description
Sitios de venta del comercio, con sus propias colecciones.
Name
notification
Type
Notification
is optional
Description
URL donde recibir el resultado del proceso. Si se omite, no se envía notificación y el resultado se consulta con GET /api/processes/{processId}.

Solicitud

POST

/api/merchants

curl --request POST \
  --url '{URL_BASE}/api/merchants' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {TU_TOKEN}' \
  --header 'Idempotency-Key: 8f1c2d3e4a5b6c7d8e9f0a1b' \
  --data '{
    "name": "Comercializadora Acme S.A.S.",
    "brand": "Acme",
    "languages": ["es"],
    "currencies": ["COP"],
    "document": { "type": "NIT", "number": "9001234567" },
    "address": { "city": "Bogota", "country": "CO", "state": 11 },
    "legalRepresentative": { "name": "Ada", "surname": "Lovelace" },
    "control": { "reseller": 1 }
  }'

Respuesta

La clave de idempotencia ya se había usado con este mismo contenido. Devuelve el proceso original, con el mismo processId.

Name
status
Type
Status
is Required
REQUERIDO
Description
Estado de la petición o del proceso. Presente en todas las respuestas.

El código HTTP dice si la llamada funcionó; status.status dice qué pasó con el proceso.
Name
processId
Type
string
is Required
REQUERIDO
Description
Identificador del proceso, en minúsculas. Con él se consulta el resultado.
Ejemplo:01kz0609xy2hd666mnx6b0jxpc
Name
action
Type
string
is Required
REQUERIDO
Description
Operación pedida.
Valores permitidos:merchant.createmerchant.update
Ejemplo:merchant.create
Name
result
Type
object|null
is optional
Description
Siempre null en la aceptación. El resultado llega al consultar el proceso.
Ejemplo:null
Name
notification
Type
object|null
is optional
Description
Estado de la entrega del webhook, o null si no se registró una URL.

Respuesta

POST

/api/merchants

{
  "status": {
    "status": "OK",
    "reason": null,
    "message": "The request was accepted and will be processed shortly.",
    "date": "2026-08-17T10:14:03-05:00"
  },
  "processId": "01kz0609xy2hd666mnx6b0jxpc",
  "action": "merchant.create",
  "result": null,
  "notification": null
}

PATCH/api/merchants/{merchantId}

Actualizar un comercio

Escribe solo los campos que el cuerpo nombra. El resto del comercio conserva su valor, y ningún campo es obligatorio — pero el cuerpo debe nombrar al menos uno: un {} responde 422 con la clave de error body, y un cuerpo que solo trae notification cuenta igualmente como vacío.

Dentro de las colecciones, cada elemento o modifica una fila existente por su identificador, o crea una nueva. Un sitio sin id es un sitio que se crea, y entonces vuelven a ser obligatorios todos sus campos: el error lo dice explícitamente, The sites.0.displayName field is required when sites.0.id is not present.

Al actualizar, un sitio habilita un medio de pago del comercio con paymentMethodId, no con code — también un sitio que esta misma petición está creando, porque ese identificador señala una fila del comercio, que existe. Es al revés que al crear el comercio, donde code es la única forma posible. El detalle está en Medios de pago del sitio.

En el paymentMethods de la raíz, junto al id viajan los valores —accountNumber, accountType, commissionModel, commissionValue, order, creditRules, settings—, pero no la identidad: reafirmar code o financialEntity responde 422 aunque el valor sea el que la fila ya tiene.

Parámetros

Name
merchantId
Type
merchantId
is Required
REQUERIDO
Description
Identificador del comercio, tal como lo publica result.merchantId. Debe ser numérico: uno que no lo sea responde 404 sin llegar al endpoint.
Ejemplo:18

Cabecera

Name
Authorization
Type
Authorization
is Required
REQUERIDO
Description
Token de acceso con el permiso onboarding:update.
Ejemplo:Bearer 1|tu-token-de-acceso
Name
Idempotency-Key
Type
Idempotency-Key
is Required
REQUERIDO
Description
Identificador único de la operación. El comercio de la URL forma parte de la comparación: la misma clave apuntada a otro comercio responde 409.
Ejemplo:4b7e1a9c2d3f5e6a8b0c1d2e
Patrón:^[A-Za-z0-9_.:-]{16,64}$
Longitud máxima:64
Longitud mínima:16
Name
Content-Type
Type
Content-Type
is Required
REQUERIDO
Description
Ejemplo:application/json

Solicitud

Estado del comercio. Los campos viajan en la raíz del cuerpo, junto a las colecciones.

Una clave desconocida en la raíz se ignora en silencio; dentro de un elemento de cualquier colección, en cambio, responde 422 nombrándola.

Name
name
Type
string
is Required
REQUERIDO
Description
Razón social del comercio.
Ejemplo:Comercializadora Acme S.A.S.
Longitud máxima:80
Name
brand
Type
string
is Required
REQUERIDO
Description
Nombre comercial, el que ve el comprador.
Ejemplo:Acme
Longitud máxima:60
Name
active
Type
boolean
is optional
Description
Si el comercio queda habilitado.
Valor por defecto:true
Ejemplo:true
Name
url
Type
string|null
is optional
Description
Sitio web del comercio.
Ejemplo:https://acme.example.com
Formato:uri
Longitud máxima:255
Name
incrementType
Type
string
is optional
Description
Referencia usada para incrementos.
Valores permitidos:SMLMVIPC
Ejemplo:SMLMV
Name
mcc
Type
string
is optional
Description
Código de categoría de comercio. Debe existir en el catálogo.
Ejemplo:5411
Name
size
Type
string
is optional
Description
Tamaño del comercio, del catálogo de tamaños: XS microempresa (menos de 10 empleados), S pequeña empresa (menos de 50), M mediana empresa (menos de 250) y L gran empresa (más de 250).
Valores permitidos:XSSML
Ejemplo:M
Name
timezone
Type
string
is optional
Description
Zona horaria en formato IANA, del catálogo de zonas.
Ejemplo:America/Bogota
Name
languages
Type
array
is Required
REQUERIDO
Description
Idiomas con los que opera el comercio. Es un conjunto: repetir un valor responde 422, y la comparación ignora mayúsculas.
Ejemplo:esen
Name
currencies
Type
array
is Required
REQUERIDO
Description
Monedas que el comercio maneja, como códigos ISO del catálogo. Es un conjunto, igual que languages.
Ejemplo:COPUSD
Name
document
Type
Document
is Required
REQUERIDO
Description
Documento de identificación fiscal del comercio.
Name
address
Type
Address
is Required
REQUERIDO
Description
Dirección fiscal del comercio.
Name
legalRepresentative
Type
LegalRepresentative
is Required
REQUERIDO
Description
Name
billing
Type
Billing
is optional
Description
Datos de facturación del comercio.
Name
travelAgency
Type
TravelAgency
is optional
Description
Aplicable solo a comercios del sector turismo.
Name
control
Type
Control
is Required
REQUERIDO
Description
Estructura comercial bajo la que queda registrado el comercio.
Name
integrations
Type
array[Integration]
is optional
Description
Integraciones del comercio con proveedores externos. Es un upsert por type: una integración que el cuerpo no nombra sobrevive intacta, y no hay forma de eliminarla.
Name
paymentMethods
Type
array[PaymentMethod]
is optional
Description
Medios de pago que el comercio acepta. Un elemento o modifica uno existente por su id, o registra uno nuevo con code; nunca las dos cosas.
Name
sites
Type
array[Site]
is optional
Description
Sitios de venta del comercio, con sus propias colecciones.
Name
notification
Type
Notification
is optional
Description
URL donde recibir el resultado del proceso. Si se omite, no se envía notificación y el resultado se consulta con GET /api/processes/{processId}.

Solicitud

PATCH

/api/merchants/{merchantId}

curl --request PATCH \
  --url '{URL_BASE}/api/merchants/18' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {TU_TOKEN}' \
  --header 'Idempotency-Key: 4b7e1a9c2d3f5e6a8b0c1d2e' \
  --data '{
    "name": "Comercializadora Acme S.A.S.",
    "brand": "Acme Pagos",
    "url": "https://pagos.acme.example.com"
  }'

Respuesta

Replay de una clave de idempotencia ya usada con el mismo contenido.

Name
status
Type
Status
is Required
REQUERIDO
Description
Estado de la petición o del proceso. Presente en todas las respuestas.

El código HTTP dice si la llamada funcionó; status.status dice qué pasó con el proceso.
Name
processId
Type
string
is Required
REQUERIDO
Description
Identificador del proceso, en minúsculas. Con él se consulta el resultado.
Ejemplo:01kz0609xy2hd666mnx6b0jxpc
Name
action
Type
string
is Required
REQUERIDO
Description
Operación pedida.
Valores permitidos:merchant.createmerchant.update
Ejemplo:merchant.create
Name
result
Type
object|null
is optional
Description
Siempre null en la aceptación. El resultado llega al consultar el proceso.
Ejemplo:null
Name
notification
Type
object|null
is optional
Description
Estado de la entrega del webhook, o null si no se registró una URL.

Respuesta

PATCH

/api/merchants/{merchantId}

{
  "status": {
    "status": "OK",
    "reason": null,
    "message": "The request was accepted and will be processed shortly.",
    "date": "2026-08-17T10:20:41-05:00"
  },
  "processId": "01kz0a13bc4de777pqy8c1kxqd",
  "action": "merchant.update",
  "result": null,
  "notification": null
}