Limites de expiração (expirationTime)
Visão geral
A API FyPay aceita, no campo transaction.expirationTime do POST /api/pix/cash-in, um valor em segundos dentro do intervalo da plataforma:
- Mínimo:
30(30 segundos) - Máximo:
604800(7 dias) - Padrão:
86400(24 horas), quando o campo é omitido
Fora desse intervalo, a API recusa o pedido com erro de validação (400).
Além disso, o liquidante PIX da sua conta pode aceitar uma faixa mais estreita. Essa checagem acontece antes de a cobrança ser criada, então um pedido recusado não gera transação.
| Situação | Resposta | errorCode | Campo útil em details |
|---|---|---|---|
expirationTime abaixo do mínimo do liquidante | 400 Bad Request | PROVIDER_EXPIRATION_BELOW_MINIMUM | providerMinSeconds |
expirationTime acima do máximo do liquidante | 400 Bad Request | PROVIDER_EXPIRATION_ABOVE_MAXIMUM | providerMaxSeconds |
Faixas que existem hoje
A maioria dos liquidantes aceita a faixa inteira da plataforma (30 s a 7 dias). As exceções configuradas hoje são:
| Mínimo | Máximo | Granularidade | Observação |
|---|---|---|---|
300 (5 min) | 604800 (7 dias) | segundos | Janelas abaixo de 5 minutos são recusadas |
60 (1 min) | 86400 (24 h) | segundos | Janelas acima de 24 horas são recusadas |
86400 (1 dia) | 604800 (7 dias) | dias | Abaixo de 1 dia é recusado. Valores que não são múltiplos de 86400 são arredondados para cima, para o próximo dia inteiro |
A faixa vale para a conta, não para a requisição. Se você não sabe qual faixa se aplica à sua conta, use a resposta de erro (details.providerMinSeconds ou details.providerMaxSeconds) ou fale com o suporte em suporte@fypay.me [A DEFINIR].
Forma do erro
Exemplo de resposta quando o expirationTime enviado é menor que o mínimo do liquidante da conta:
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"
}No caso de valor acima do máximo, o errorCode é PROVIDER_EXPIRATION_ABOVE_MAXIMUM e details.providerMaxSeconds traz o teto aceito.
Como tratar
- Leia
details.providerMinSeconds(oudetails.providerMaxSeconds) e reenvie a cobrança com um valor dentro da faixa, mantendo o mesmoexternalId(a cobrança recusada não foi criada). - Para janelas curtas (PDV, checkout), use pelo menos 5 minutos (
300): esse valor é aceito por todos os liquidantes, exceto os de granularidade em dias. - Se a sua operação depende de janelas muito curtas (abaixo de 5 minutos) ou longas (acima de 24 horas), confirme a faixa da conta com o suporte antes de entrar em produção.