SimPayDocs

    Refresh Liveness Result

    Asks the API to re-check the liveness verdict and pick it up when the status endpoint still reports `PENDING` after the end user has already finished the proof of life. Use it as a reconciliation escape hatch, not as a polling mechanism.

    POSThttps://api.somossimpay.com.br/v3/onboarding/{onboarding_requisition_id}/liveness/refresh
    curl --request POST \
  --url 'https://api.somossimpay.com.br/v3/onboarding/{onboarding_requisition_id}/liveness/refresh' \
  --header 'X-Onboarding-Token: kR4tX0pQ7sV9nL2mB6yH8wZ3cJ1fA5dE7gT0uI9oP4s'
    Response200
    {
  "worked": true,
  "enqueued": true
}

    Endpoint

    POST /v3/onboarding/{onboarding_requisition_id}/liveness/refresh

    Headers

    ParameterTypeDescriptionRequired or OptionalExample
    X-Onboarding-TokenStringThe access_token returned when the onboarding requisition was created. It authorizes every call made for that requisition.requiredkR4tX0pQ7sV9nL2mB6yH8wZ3cJ1fA5dE7gT0uI9oP4s

    🔐 This endpoint has no request body, so no Content-Type header is required. Keep the access token on your server side and never expose it in the end user's browser.

    Path Parameters

    ParameterTypeDescriptionRequiredExample
    onboarding_requisition_idIntegerIdentifier of the onboarding requisition, returned when it was created.Yes12345

    Request Examples

    Reconcile the liveness verdict of a requisition:

    POST /v3/onboarding/12345/liveness/refresh
X-Onboarding-Token: kR4tX0pQ7sV9nL2mB6yH8wZ3cJ1fA5dE7gT0uI9oP4s

    Another requisition:

    POST /v3/onboarding/67890/liveness/refresh
X-Onboarding-Token: bN8vK2rM5tQ7wE1yU3iO6pA9sD4fG0hJ2lZ5xC7vB1n

    Response Details

    A final verdict was found and is being applied:

    {
  "worked": true,
  "enqueued": true
}

    There is nothing new yet:

    {
  "worked": true,
  "enqueued": false
}
    FieldTypeDescription
    workedBooleanAlways returns true when the request is successful
    enqueuedBooleantrue when a final liveness verdict was found and picked up for processing — poll the status endpoint shortly after to read it. false when there is nothing new to apply yet.

    Error Responses

    HTTP CodeError MessageDescription
    404Onboarding requisition not found.The requisition does not exist, or the X-Onboarding-Token header is missing or does not match the access token issued for this requisition.
    422Validation errorThe requisition identifier in the path is not a valid integer.

    Business Rules

    What This Endpoint Is For:

    • The end user finished the proof of life, but the onboarding status endpoint (GET /v3/onboarding/12345) still reports liveness_status as PENDING.
    • This call asks us to re-check the verdict and pick it up, so the requisition catches up with what the end user already did.
    • It is a reconciliation escape hatch for a verdict that seems stuck on PENDING — it is not part of the normal flow, which resolves on its own.

    Reading the Response:

    • "enqueued": true — a final verdict was found and is being applied. The result is applied asynchronously, so poll the onboarding status endpoint shortly after this call to read the new liveness_status (PASSED or FAILED) and current_step.
    • "enqueued": false — there is nothing new to apply. The final verdict has not been produced yet, it has already been applied, or the re-check could not be completed this time. Keep polling the status endpoint normally, and retry this call later if the liveness is still PENDING.

    No-Op Conditions:

    • The call returns "enqueued": false and changes nothing when liveness_status is not PENDING — an already PASSED or FAILED liveness is never re-checked or overwritten.
    • It also returns "enqueued": false when the liveness journey has not produced a final verdict yet, or when it never started.
    • This endpoint never opens a new liveness journey and never consumes a liveness attempt. To start a new attempt after a FAILED liveness, use the liveness retry endpoint.

    Usage Limits:

    • The request carries no body. Any body sent is ignored.
    • Call it sparingly and only after a reasonable wait — allow the normal flow at least a couple of minutes to resolve before reconciling.
    • Do not use this endpoint as a polling loop. Poll the onboarding status endpoint to follow the journey, and call this endpoint only when the liveness stays PENDING far longer than expected.
    • The call is safe to repeat: it either finds a final verdict or reports that there is none.

    Access:

    • Every call for a requisition must carry the X-Onboarding-Token header with the access token issued when that requisition was created.
    • A missing or incorrect token returns 404 with the same message as an unknown requisition — the API does not reveal whether the requisition exists.