Límites de expiración (expirationTime)
Visión general
La API FyPay acepta, en el campo transaction.expirationTime de POST /api/pix/cash-in, un valor en segundos dentro del intervalo de la plataforma:
- Mínimo:
30(30 segundos) - Máximo:
604800(7 días) - Predeterminado:
86400(24 horas), cuando se omite el campo
Fuera de ese intervalo, la API rechaza la solicitud con un error de validación (400).
Además, el liquidador PIX de su cuenta puede aceptar un rango más estrecho. Esta verificación ocurre antes de crear el cobro, por lo que una solicitud rechazada no genera transacción.
| Situación | Respuesta | errorCode | Campo útil en details |
|---|---|---|---|
expirationTime por debajo del mínimo del liquidador | 400 Bad Request | PROVIDER_EXPIRATION_BELOW_MINIMUM | providerMinSeconds |
expirationTime por encima del máximo del liquidador | 400 Bad Request | PROVIDER_EXPIRATION_ABOVE_MAXIMUM | providerMaxSeconds |
Rangos que existen hoy
La mayoría de los liquidadores acepta el rango completo de la plataforma (30 s a 7 días). Las excepciones configuradas hoy son:
| Mínimo | Máximo | Granularidad | Observación |
|---|---|---|---|
300 (5 min) | 604800 (7 días) | segundos | Las ventanas menores a 5 minutos son rechazadas |
60 (1 min) | 86400 (24 h) | segundos | Las ventanas mayores a 24 horas son rechazadas |
86400 (1 día) | 604800 (7 días) | días | Menos de 1 día es rechazado. Los valores que no son múltiplos de 86400 se redondean hacia arriba, al siguiente día completo |
El rango vale para la cuenta, no para la solicitud. Si no sabe qué rango se aplica a su cuenta, use la respuesta de error (details.providerMinSeconds o details.providerMaxSeconds) o hable con el soporte en suporte@fypay.me [A DEFINIR].
Forma del error
Ejemplo de respuesta cuando el expirationTime enviado es menor que el mínimo del liquidador de la cuenta:
HTTP/1.1 400 Bad Request
Content-Type: application/json{
"statusCode": 400,
"code": "PROVIDER_EXPIRATION_BELOW_MINIMUM",
"errorCode": "PROVIDER_EXPIRATION_BELOW_MINIMUM",
"message": "Provider <liquidante> requires expirationTime >= 300s (got 30s)",
"userMessage": "O provedor <liquidante> exige tempo mínimo de 300 segundos para expiração.",
"details": {
"provider": "<liquidante>",
"providerMinSeconds": 300,
"granularity": "seconds",
"userExpirationTime": 30
},
"errorId": "<correlation-id>",
"timestamp": "2026-05-05T12:34:56.789Z",
"path": "/api/pix/cash-in",
"method": "POST"
}En el caso de un valor por encima del máximo, el errorCode es PROVIDER_EXPIRATION_ABOVE_MAXIMUM y details.providerMaxSeconds trae el techo aceptado.
Cómo tratarlo
- Lea
details.providerMinSeconds(odetails.providerMaxSeconds) y reenvíe el cobro con un valor dentro del rango, manteniendo el mismoexternalId(el cobro rechazado no fue creado). - Para ventanas cortas (PDV, checkout), use al menos 5 minutos (
300): este valor es aceptado por todos los liquidadores, excepto los de granularidad en días. - Si su operación depende de ventanas muy cortas (menos de 5 minutos) o largas (más de 24 horas), confirme el rango de la cuenta con el soporte antes de entrar en producción.