Consultar un comercio

GET /api/merchants/{merchantId} devuelve un comercio completo en una sola respuesta: sus datos, sus medios de pago, sus integraciones y todos sus sitios, cada uno con sus propios medios de pago e integraciones.

A diferencia de la creación y la actualización, es síncrona y de solo lectura: responde de inmediato con el comercio, no crea proceso, no envía notificación y no modifica nada. Sirve, por ejemplo, para leer un comercio después de crearlo o antes de actualizarlo.

La petición

curl --request GET \
  --url '{URL_BASE}/api/merchants/18' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {TU_TOKEN}'

Requiere un token con el permiso onboarding:read, el mismo que consultar el proceso. No lleva cuerpo, no admite parámetros de consulta y no pagina: la respuesta trae todas las colecciones completas, así que su tamaño crece con los sitios y los medios de pago del comercio.

De dónde sale el merchantId

Es el result.merchantId que devolvió el proceso de creación, y el mismo que usa PATCH /api/merchants/{merchantId}. Debe ser numérico: uno que no lo sea responde 404.

La consulta no se limita a los comercios que creó tu aplicación: con el permiso onboarding:read puedes leer cualquier comercio que exista en el registro de Placetopay, y la respuesta es la misma para todos los consumidores. Por eso, a diferencia de lo que ocurre con un proceso, aquí un 404 significa siempre que el comercio no existe.

La respuesta

{
  "status": {
    "status": "OK",
    "reason": null,
    "message": null,
    "date": "2026-09-22T21:27:20+00:00"
  },
  "id": 18,
  "name": "Comercializadora Acme S.A.S.",
  "brand": "Acme",
  "active": true,
  "languages": ["en", "es"],
  "currencies": ["COP", "USD"],
  "document": {
    "type": "NIT",
    "number": "9001234567"
  },
  "paymentMethods": [
    {
      "id": 64,
      "customerId": 18,
      "code": "CR_VS",
      "commissionModel": "P",
      "commissionValue": 2.5,
      "financialEntity": 7
    }
  ],
  "integrations": [
    {
      "id": 42,
      "customerId": 18,
      "type": "kount",
      "settings": {
        "sandbox": false,
        "website": "ACME",
        "merchant": "201000"
      }
    }
  ],
  "sites": [
    {
      "id": 214,
      "login": "aabbccdd1234567890aabbccdd123456",
      "tranKey": "exampleTranKey16",
      "md5Hash": "exampleMd5Hash16",
      "language": "ES",
      "active": true,
      "createdAt": "2026-09-22 16:27:16",
      "control": {
        "minAmount": "1000.00",
        "maxAmount": "5000000.00"
      },
      "paymentMethods": [
        {
          "id": 131,
          "customerPaymentId": 64,
          "code": "CR_VS",
          "financialEntity": null
        }
      ]
    }
  ]
}

Credenciales en claro

Todas las respuestas llegan con Cache-Control: no-cache, private, también las de error: ninguna caché compartida —un proxy, una CDN— debe guardarlas, y un cliente que las conserve debe revalidarlas antes de reutilizarlas.

Ten presente también el alcance del permiso: un token con onboarding:read puede leer las credenciales de cualquier comercio, no solo las de los que creó tu aplicación. Protégelo con el mismo cuidado que un token de escritura.

Por la misma razón, esta consulta es la forma de recuperar las credenciales de un sitio si perdiste el resultado del proceso que las generó. Ver Sitios.

Cómo leer los valores

La respuesta es una lectura del registro, y algunos valores no tienen la misma forma que en la escritura:

• Montos como texto. Los de control, threeDS y securityFilters de un sitio salen como texto con dos decimales ("1000.00"), y los de las promociones, con cuatro ("5000.0000"). El resto de los valores numéricos sale como número —comisiones y montos de medios de pago, subscriptionValidation.amount, operation.taxPercentage— y, si no tiene parte decimal, se escribe sin decimales (1200, no 1200.0). Un cliente tipado debe aceptar entero y decimal en esos campos.
• Objetos vacíos como []. Un objeto sin claves sale como lista vacía, no como {}. Pasa en settings, creditRules, branding y metadata, así que un cliente tipado debe aceptar las dos formas en esos campos.
• Deshabilitados incluidos. Un comercio o un sitio deshabilitado se devuelve igual, con active: false. El active de un sitio es true solo si el sitio y su comercio están habilitados.
• Orden. Los medios de pago, las integraciones del comercio y los sitios salen por su id, igual que los medios de pago de cada sitio. Las integraciones de un sitio salen por type, y languages y currencies, en orden alfabético.
• Mayúsculas. languages conserva la grafía con que se registró y puede venir en minúscula (es), mientras que sites[].language sale en mayúscula (ES). Compáralos sin distinguir mayúsculas.
• Fechas. status.date va en UTC y con su zona (+00:00). sites[].createdAt y sites[].expiration van como YYYY-MM-DD HH:MM:SS, sin zona, y createdAt está en hora de Colombia (UTC−5). productionDate y la vigencia de las promociones son solo fecha, YYYY-MM-DD.

Valores que el sistema completa

Algunos campos salen con un valor aunque el comercio no lo tenga registrado:

document.number y address.phone salen como "", no como null, cuando no hay nada registrado. Y document.number solo trae el tramo entre el primer y el segundo espacio del documento registrado: uno guardado como CC 123 456 sale como 123.

Cuando la configuración guardada de un sitio no se puede leer, allowWallet, allowConfirmationFlow, filterLockedByTries y branding salen en null.

El representante legal

El representante legal se guarda como un solo nombre completo —por eso nombre y apellido viajan en pareja al escribir—, así que al leerlo name y surname se reconstruyen con una regla aproximada y pueden no coincidir con los que enviaste:

• Con una palabra, todo es nombre y surname es null.
• Con dos, la segunda es el apellido.
• Con más, las dos últimas son apellidos, y las partículas de, del, la, las, los, y, i, san, van, von, mac y mc se agrupan con la palabra que las sigue: María José de la Torre Pérez sale como María José y de la Torre Pérez.
• Con ocho palabras o más, normalmente el nombre completo sale en name, y surname es null.

Si necesitas comparar lo que leíste con lo que enviaste, compara el nombre completo, no cada mitad por separado.

Medios de pago

paymentMethods[].id es el identificador con el que un PATCH modifica cada medio de pago, así que esta consulta es también la forma de obtenerlo para uno que no creaste desde esta API. Ver Medios de pago.

• disabled indica si el medio de pago está deshabilitado en el catálogo de Placetopay, no en el comercio.
• franchise es la franquicia que el catálogo asocia al medio de pago, y es solo informativa: puede ser null también en medios de tarjeta, y en algunos no coincide con la marca de su nombre. No es la franquicia con la que se procesa una transacción, así que no la uses para deducir la marca.
• settings sale en claro y tal como está guardado, salvo en dos casos. En los medios de CREDIBANCO, un pfxID que corresponde a un certificado registrado sale sustituido por las credenciales de ese certificado —username, password, retailCode y terminalNumber, donde las dos primeras pueden ser null—; si no corresponde a ninguno, sale el pfxID tal cual. Y selection_rules no devuelve su contenido: sale siempre como {}, o como null si su configuración es inválida.

Sitios

• Credenciales. Cada sitio trae login y tranKey completos, junto con md5Hash.
• URL de notificación. integration.notificationUrl es la URL guardada en el sitio, que no siempre es la del comercio. Si el sitio tiene una integración notifier, ahí está la dirección del servicio de notificaciones de Placetopay, y el destino del comercio queda en settings.additional.uri de esa integración. Ver El efecto del tipo notifier.
• Bloques que solo se leen. historic, creditBureau, riskEngine e integration.allowConfirmationFlow no forman parte del cuerpo de escritura. En creditBureau y riskEngine, behaviour es el valor registrado, codificado en bits, y su lectura está en behaviours: para cada caso, el nivel activo —REJECTED, MANUAL, IGNORE o PROCESS— o false. En configuraciones antiguas, behaviour puede venir como texto, decimal o booleano.
• Promociones. promotions trae las promociones generales vigentes hoy, según la fecha actual en Colombia: primero las del sitio y después las que aplican a todos los sitios del comercio, cada grupo en orden de creación. No incluye las asociadas a un medio de pago, ni las deshabilitadas, las que aún no empiezan o las vencidas.
• Metadatos. metadata es el documento tal como quedó después de las fusiones, o null si el sitio no tiene.
• Logo. Si el sitio tiene un logo registrado, branding incluye logoUrl con su URL pública, o null si no se puede construir.

Medios de pago del sitio

Cada elemento de sites[].paymentMethods habilita en el sitio un medio de pago del comercio: el de paymentMethods[] cuyo id es customerPaymentId. En un PATCH, ese mismo valor se envía como paymentMethodId.

Los campos salen como están registrados en el sitio, sin combinarlos con los del comercio: un null significa que el sitio hereda ese valor. Es una diferencia con el resultado del proceso, que en result.sites[].paymentMethods[].financialEntity publica la entidad efectiva.

Para obtener el valor que rige al transaccionar:

Ver La comisión por sitio.

Integraciones

Las integraciones del comercio y las de cada sitio traen un id, pero es solo informativo: al escribir, una integración se direcciona por su type, y enviar id responde 422. Su settings sale en claro, tal como está guardado.

No es un cuerpo para reenviar

La respuesta describe el comercio, pero no se puede devolver tal cual en un PATCH:

• Identificadores de más. El PATCH pide que cada elemento se identifique de una sola forma —id, code o, en los medios de pago de un sitio, paymentMethodId—, y la respuesta trae varias a la vez.
• Campos que la escritura rechaza, como customerId o siteId dentro de un elemento, o los bloques que solo se leen.
• Formas distintas. Montos como texto, [] en lugar de objetos vacíos, valores que el sistema completó y algunos null que la escritura no acepta.
• CREDIBANCO. La escritura espera pfxID, no las credenciales que devuelve la consulta.

Para actualizar, envía solo lo que cambia, como se explica en Actualizar un comercio. Lo que esta consulta sí te da son los identificadores que ese cuerpo necesita: paymentMethods[].id, sites[].id y, dentro de un sitio, paymentMethods[].id o customerPaymentId.

Errores de la consulta

En todas, status.reason trae el código HTTP como número. El catálogo completo está en Errores.

{
  "status": {
    "status": "FAILED",
    "reason": 404,
    "message": "The requested resource does not exist.",
    "date": "2026-09-22T21:27:20+00:00"
  }
}

¿Qué sigue?

• Actualizar un comercio
• Sitios — las credenciales y los metadatos del sitio
• Referencia de la API — el ejemplo completo y el contrato campo a campo