Terminar una sesión del Widget

Generas un patToken, se lo entregas al widget, y el usuario se va — o tu propio sistema cancela la orden un minuto después. El token permanece válido hasta el exp con el que lo firmaste, así que sin una forma de revocarlo el usuario podría volver más tarde y completar un pago que ya no quieres. terminateWidgetSession finaliza la sesión del lado del servidor. Al usuario se le niega el acceso la próxima vez que navegue dentro del widget, y cualquier intento de pago contra esa sesión es rechazado.

Requisitos previos: la API Key de tu aplicación para autenticación Basic, y ya sea el operator token que emitiste o su jti.

Autenticación

Esta mutación se autentica con las credenciales de tu aplicación, no con un access token de usuario — el mismo encabezado Basic que ya usas para generateUserAccessToken:

Authorization: Basic <YOUR_API_KEY>

Envía la API Key del Developer Console tal cual; ya está codificada en base64 y decodifica al par app_id:apiSecret que verifica el servidor. Usa la key de la misma aplicación cuyo apiSecret firmó el operator token.

Staging y producción son aplicaciones separadas con credenciales separadas. Una key del entorno incorrecto devuelve 401 con el mismo mensaje que una mal formada — consulta If the token request returns 401 para la lista completa de verificación.

Solo puedes terminar sesiones que pertenezcan a la aplicación con la que te autenticas. Un jti emitido por una aplicación diferente no se ve afectado por tu llamada — obtendrás una respuesta exitosa con wasActive: false, y la sesión de esa aplicación seguirá en ejecución. La autenticación Basic no está disponible para aplicaciones con estado PERSONAL.

Identificar la sesión

Proporciona ya sea el operator token o su jti. Se requiere al menos uno.

Por token (preferido)
Por jti

Pasa el mismo patToken que entregaste al widget. Se verifica contra el secreto de tu aplicación, por lo que un token que no es tuyo se rechaza de inmediato.Un token ya expirado igualmente es aceptado — terminar una sesión expirada es inofensivo, y significa que no tienes que rastrear la expiración antes de llamar.El propio exp del token también limita cuánto tiempo se recuerda la terminación, por lo que esta es la mejor opción cuando aún lo tienes.

Úsalo cuando ya no tengas el token. El jti es el UUID v4 que generaste cuando firmaste el patToken — consulta Set Up Your Server.También se devuelve a tu URL de callback como el parámetro de consulta fluz_jti, para que puedas terminar una sesión desde un callback sin haber almacenado el token.Debido a que no hay un token del cual leer un exp, una terminación solo con jti se recuerda por un período fijo en lugar de exactamente por el tiempo que la sesión podría haberse usado.

Proporcionar ambos está permitido siempre que describan la misma sesión. El token prevalece, y el jti se trata como una afirmación sobre este — un jti que no coincida con el propio del token se rechaza en lugar de ignorarse silenciosamente, por lo que una confusión no puede terminar la sesión equivocada.

Argumentos

input (TerminateWidgetSessionInput!): identifica la sesión a terminar.

Campos de TerminateWidgetSessionInput

Field	Type	Description	Required
`token`	`String`	El operator token (`patToken`) que entregaste al usuario para abrir el widget.	Al menos uno de `token` o `jti`
`jti`	`String`	El claim `jti` de ese token. Mismo valor entregado a tu URL de callback como `fluz_jti`.	Al menos uno de `token` o `jti`

Mutación de ejemplo

mutation {
  terminateWidgetSession(input: { jti: "11111111-1111-4111-8111-111111111111" }) {
    jti
    wasActive
    terminatedAt
  }
}

Ejemplo con cURL

curl -X POST \
  https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic YOUR_API_KEY' \
  -d '{
    "query": "mutation { terminateWidgetSession(input: { jti: \"11111111-1111-4111-8111-111111111111\" }) { jti wasActive terminatedAt } }"
  }'

Respuesta de ejemplo

{
  "data": {
    "terminateWidgetSession": {
      "jti": "11111111-1111-4111-8111-111111111111",
      "wasActive": true,
      "terminatedAt": "2026-09-01T14:32:07.412Z"
    }
  }
}

Campos de la respuesta

Field	Type	Description
`jti`	`String!`	El identificador de la sesión que fue terminada.
`wasActive`	`Boolean!`	`true` cuando la sesión tenía una reserva activa que esta llamada revocó — el usuario estaba en el widget o podía haberlo estado. `false` cuando no había nada activo que revocar. Solo informativo; la sesión se termina de cualquier manera.
`terminatedAt`	`DateTime!`	Cuándo se registró la terminación.

wasActive: false es un éxito, no un fallo. Es la respuesta normal cuando el usuario nunca abrió el widget — que también es el momento más seguro para cancelar. Terminar una sesión que nunca se abrió está completamente soportado y es la forma recomendada de abortar un pago que ya entregaste.

Cuando se rechaza la terminación

La terminación es idempotente — terminar una sesión ya terminada tiene éxito. Se rechaza en exactamente dos casos, cada uno significando que la cuestión del dinero ya está resuelta:

Error	Code	Status	Qué significa
`WidgetSessionInProgress`	`WIDGET-006`	`409`	El pago de la sesión se está ejecutando actualmente. Espera el resultado — no reintentes a ciegas. Recibirás un evento de finalización o de fallo de cualquier manera.
`WidgetSessionAlreadyCompleted`	`WIDGET-007`	`409`	El pago ya se realizó. No queda nada por terminar.

Otros errores que puedes ver:

Error	Code	Status	Causa
`MissingParameter`	`WIDGET-001`	`400`	No se proporcionó ni `token` ni `jti`, o el token no tiene claim `jti`.
`InvalidParameter`	`WIDGET-002`	`400`	El token no verifica contra el secreto de tu aplicación, no fue emitido para esta aplicación, o el `jti` proporcionado no coincide con el propio del token.
`MisconfiguredApplication`	`WIDGET-003`	`400`	La aplicación no está configurada para abrir sesiones del widget.

Lo que ve el usuario

La terminación entra en vigor en la próxima navegación o actualización del usuario dentro del widget. No cierra una pantalla que ya está renderizada. Cuando vuelva a moverse, verá un mensaje de “Sesión finalizada” que nombra tu aplicación y le indica cerrar la ventana e iniciar de nuevo desde tu producto. Si llega hasta confirmar un pago, esa confirmación se rechaza con el mismo mensaje, y el pago se rechaza del lado del servidor con WidgetSessionTerminated (WIDGET-005, 410).

Terminar no detiene por sí mismo un pago que ya comenzó a ejecutarse — ese caso devuelve 409 en su lugar, y debes esperar el evento de finalización o de fallo en lugar de asumir que el dinero está detenido.

Cuánto tiempo se recuerda una terminación

Una sesión terminada se rechaza durante tanto tiempo como de otro modo podría haberse usado:

Terminada por token — hasta el propio exp del token, y nunca menos de una hora.
Terminada solo por jti — por 30 días. Nada limita por cuánto tiempo puedes firmar un operator token, así que sin un exp que leer la terminación se conserva muy por encima de cualquier vida útil plausible de la sesión.

Después de esa ventana, el registro se descarta. En la práctica, el operator token ya habrá expirado hace tiempo, por lo que la sesión no puede usarse de todos modos.

Próximos pasos

Configura tu servidor

Genera el patToken y el jti que toma esta mutación.

Integra el widget

Etiqueta de script, llamada de init, vinculación del botón.

Resumen de Widgets embebidos

Cómo encajan las sesiones del widget, grants de OAuth y tokens de transacción preaprobados.

Idempotencia

Por qué cada llamada que mueve dinero necesita un jti único.

​Autenticación

​Identificar la sesión

​Argumentos

​Campos de TerminateWidgetSessionInput

​Mutación de ejemplo

​Ejemplo con cURL

​Respuesta de ejemplo

​Campos de la respuesta

​Cuando se rechaza la terminación

​Lo que ve el usuario

​Cuánto tiempo se recuerda una terminación

​Próximos pasos

Configura tu servidor

Integra el widget

Resumen de Widgets embebidos

Idempotencia

Autenticación

Identificar la sesión

Argumentos

Campos de TerminateWidgetSessionInput

Mutación de ejemplo

Ejemplo con cURL

Respuesta de ejemplo

Campos de la respuesta

Cuando se rechaza la terminación

Lo que ve el usuario

Cuánto tiempo se recuerda una terminación

Próximos pasos