Consultar el proceso

Cuando Onboarding acepta una petición devuelve un processId. GET /api/processes/{processId} es el endpoint que te dice qué pasó con ella, y es la fuente de verdad del resultado.

La petición

Solicitud

GET

/api/processes/{processId}

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

Requiere un token con el permiso onboarding:read. El processId es el que devolvió la petición de creación o actualización; también puedes usar directamente la URL que llegó en el header Location.

La respuesta

Name
status
Type
object
is Required
REQUERIDO
Description
Estado actual del proceso: status, reason, message y date. El campo date es el instante en que el proceso cambió de estado, no el momento de tu consulta.
Name
processId
Type
string
is Required
REQUERIDO
Description
Identificador del proceso, en minúsculas.
Name
action
Type
string
is Required
REQUERIDO
Description
La operación pedida: merchant.create o merchant.update.
Name
result
Type
object
is Required
REQUERIDO
Description
El resultado, disponible solo cuando el proceso termina bien. null mientras tanto.
Name
errors
Type
object
is optional
Description
Aparece solo cuando el fallo puede atribuirse a campos concretos que enviaste.
Name
notification
Type
object
is Required
REQUERIDO
Description
Estado de la entrega del webhook. null si no registraste una URL de notificación.

Respuesta

{
  "status": {
    "status": "PENDING",
    "reason": null,
    "message": "The request is waiting to be processed.",
    "date": "2026-08-17T10:14:03-05:00"
  },
  "processId": "01kz0609xy2hd666mnx6b0jxpc",
  "action": "merchant.create",
  "result": null,
  "notification": null
}

Los cuatro estados

`status.status`	Significado	¿Es final?	¿Trae `Retry-After`?
`PENDING`	La petición fue aceptada y espera su turno	No	Sí
`PENDING_PROCESS`	El registro se está ejecutando	No	Sí
`OK`	El comercio quedó registrado	Sí	No
`FAILED`	El registro no pudo completarse	Sí	No

React Flow

Los dos estados de la izquierda responden con el header Retry-After; los dos finales, no. Esa es la diferencia que determina cuándo parar.

Cómo hacer polling

La señal para dejar de consultar es la ausencia del header Retry-After, no un valor concreto de status.status. Mientras ese header esté presente, el proceso sigue avanzando; cuando desaparece, el resultado es definitivo.

Consultar así en lugar de con un intervalo fijo tiene dos ventajas: no malgastas peticiones cuando el proceso va a tardar, y tu integración no necesita cambiar si en el futuro se añaden estados intermedios nuevos.

Bucle de consulta

do {
    $response = Http::withToken($token)
        ->acceptJson()
        ->get("{$urlBase}/api/processes/{$processId}");

    $retryAfter = $response->header('Retry-After');

    if ($retryAfter !== '') {
        sleep((int) $retryAfter);
    }
} while ($retryAfter !== '');

$result = $response->json('result');

Añade siempre un límite de reintentos por tu lado, para que un problema inesperado no deje el bucle girando indefinidamente.

El resultado

Cuando el proceso termina bien, result describe lo que quedó registrado.

Name
result.merchantId
Type
integer
is Required
REQUERIDO
Description
Identificador del comercio. Está presente tanto en una creación como en una actualización.

Si enviaste colecciones, result incluye además una clave por cada una, con el detalle de lo que se escribió en ella:

Clave	Contiene	Detalle
`result.integrations`	Una entrada por integración escrita	Integraciones
`result.paymentMethods`	Una entrada por medio de pago escrito	Medios de pago
`result.sites`	Una entrada por sitio escrito	Sitios

Cada entrada lleva un campo action con el valor created, updated o unchanged, que te dice qué ocurrió realmente con ese elemento.

result es un objeto extensible: pueden aparecer claves nuevas sin que eso se considere un cambio incompatible. Al leerlo, ignora las claves que no conozcas en lugar de rechazar la respuesta.

El estado de la notificación

Si registraste una URL de notificación, notification te dice cómo va la entrega del webhook.

Name
notification.url
Type
string
is Required
REQUERIDO
Description
La URL que registraste.
Name
notification.state
Type
string
is Required
REQUERIDO
Description
PENDING mientras la entrega sigue pendiente o en reintentos, DELIVERED cuando tu endpoint respondió correctamente, y FAILED cuando se agotaron los intentos o tu endpoint rechazó el mensaje.
Name
notification.attempts
Type
integer
is Required
REQUERIDO
Description
Número de intentos de entrega realizados.

notification.state en FAILED no significa que el registro haya fallado. Son dos cosas distintas: el proceso puede estar en OK con el comercio perfectamente registrado y la notificación en FAILED. Lo único que se perdió es el aviso.

Un proceso fallido se consulta con 200

Un proceso en FAILED responde con código HTTP 200. No es una inconsistencia: la consulta funcionó y te está informando correctamente de que el registro no se completó.

status.reason trae un código que identifica la causa.
errors aparece cuando el fallo puede atribuirse a campos concretos, con las mismas rutas del cuerpo que usa el 422.

El catálogo de códigos y qué hacer ante cada uno está en Errores.

Errores de la consulta

404 El proceso no existe. También responde 404 un proceso que existe pero pertenece a otro consumidor.

Es deliberado que en ese caso no responda 403: un 403 confirmaría que el identificador existe, lo que permitiría descubrir procesos ajenos probando identificadores. Con un 404 uniforme, no hay diferencia observable entre «no existe» y «no es tuyo».

401 si el token es inválido y 403 si no incluye el permiso onboarding:read.

Respuesta de error

{
  "status": {
    "status": "FAILED",
    "reason": 404,
    "message": "The requested resource does not exist.",
    "date": "2026-08-17T10:14:03-05:00"
  }
}

¿Qué sigue?

Notificación — recibir el resultado sin consultar
Errores
Referencia de la API — el contrato completo de la respuesta