Autenticación

Todas las peticiones a Onboarding se autentican con un token de acceso que Placetopay emite para tu aplicación y que viaja en el header Authorization.

Credenciales

Al habilitar el servicio recibes dos credenciales distintas:

  • Name
    Token de acceso
    Type
    string
    is Required
    REQUERIDO
    Description

    Autentica tus peticiones. Viaja en cada llamada dentro del header Authorization.

  • Name
    Secreto de firma
    Type
    string
    is optional
    Description

    Solo lo necesitas si vas a recibir notificaciones. Sirve para verificar que un webhook salió realmente de Onboarding. Ver Notificación.

Ambas credenciales se entregan una sola vez y no se pueden recuperar después. Guárdalas en un gestor de secretos antes de continuar. Si las pierdes, hay que emitir unas nuevas.

Trátalas como cualquier otro secreto de producción: nunca las incluyas en el código fuente, en un repositorio ni en código que se ejecute en el navegador.

Ambientes y URL base

Onboarding opera en ambientes separados. La URL base de cada uno se entrega junto con las credenciales, porque cada ambiente emite las suyas propias y no son intercambiables.

En esta documentación, {URL_BASE} representa la URL del ambiente en el que estés trabajando. Una petición completa se construye así:

{URL_BASE}/api/merchants

Un token emitido para un ambiente no funciona en otro. Si recibes un 401 con credenciales que sabes correctas, verifica que estés llamando a la URL base que corresponde a ese token.

Autorizar una petición

El token viaja como bearer token. Añade también los headers de contenido, para que las respuestas de error lleguen en formato JSON.

Headers

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

El header Accept: application/json importa. Sin él, algunos errores podrían responderse en un formato distinto al que espera tu integración.

Permisos

Un token lleva asociados uno o varios permisos, y cada operación exige el suyo. Esto permite emitir tokens limitados: por ejemplo, uno que solo pueda consultar procesos.

Permiso
Habilita
Operación
onboarding:create
POST /api/merchants
Crear un comercio
onboarding:update
PUT /api/merchants/{merchantId}
Actualizar un comercio
onboarding:read
GET /api/processes/{processId}
Consultar el proceso

Si tu token no incluye el permiso que la operación exige, la respuesta es 403.

Ten en cuenta que crear un comercio requiere dos permisos en la práctica: onboarding:create para enviarlo y onboarding:read para consultar el resultado del proceso.

Verificar tu token

Antes de escribir el resto de la integración, comprueba que tus credenciales funcionan. GET /api/user es el endpoint más simple y solo requiere que el token sea válido.

La respuesta describe el consumidor al que pertenece el token.

  • Name
    id
    Type
    integer
    is Required
    REQUERIDO
    Description

    Identificador de tu aplicación como consumidora de la API.

  • Name
    username
    Type
    string
    is Required
    REQUERIDO
    Description

    Nombre con el que está registrada tu aplicación.

  • Name
    environment
    Type
    string
    is Required
    REQUERIDO
    Description

    Ambiente al que pertenece el token.

  • Name
    active
    Type
    boolean
    is Required
    REQUERIDO
    Description

    Indica si el consumidor está habilitado.

Respuesta

GET
/api/user
{
  "status": {
    "status": "OK",
    "reason": null,
    "message": null,
    "date": "2026-08-17T10:14:03-05:00"
  },
  "id": 1,
  "username": "acme",
  "environment": "SANDBOX",
  "active": true
}

Errores de autenticación

401 Token ausente o inválido. No enviaste el header Authorization, o el token no existe, fue revocado o pertenece a otro ambiente.

403 El token no tiene el permiso necesario. El token es válido, pero no incluye el permiso que la operación exige. El mensaje no indica qué permiso falta, para no revelar la estructura interna de autorización: consulta la tabla de permisos de esta página.

Respuestas de error

{
  "status": {
    "status": "FAILED",
    "reason": 401,
    "message": "The access token is missing or invalid.",
    "date": "2026-08-17T10:14:03-05:00"
  }
}

Ninguna de las dos respuestas trae processId: son fallos de la llamada, no de un proceso. Esa distinción se explica en Errores.

¿Qué sigue?