Limites por provedor (expirationTime)
Visão geral
A API EYT expõe um piso e um teto da plataforma para o expirationTime (em segundos) das cobranças PIX:
- Mínimo:
30(30 segundos) - Máximo:
604800(7 dias) - Padrão:
86400(24 horas)
Acima desses limites, a API recusa o pedido com erro de validação. Adicionalmente, cada provedor PIX por trás da sua conta pode ter limites próprios, mais restritivos. Quando o expirationTime é menor que o mínimo do provedor da conta, a API responde 400 Bad Request com errorCode igual a PROVIDER_EXPIRATION_BELOW_MINIMUM e o detalhe do mínimo aceito. Quando é maior que o máximo do provedor, o errorCode é PROVIDER_EXPIRATION_ABOVE_MAXIMUM e details.providerMaxSeconds informa o teto aceito.
Tabela de limites por provedor
| Provedor | Mínimo | Máximo | Granularidade | Observação |
|---|---|---|---|---|
| Woovi | 300 (5 min) | 604800 (7 dias) | segundos | Limite imposto pela API Woovi |
| BRZip | 30 (30 s) | 604800 (7 dias) | segundos | — |
| Magen | 30 (30 s) | 604800 (7 dias) | segundos | — |
| Hyperwallet | 30 (30 s) | 604800 (7 dias) | segundos | — |
| GolPix | 86400 (1 dia) | 604800 (7 dias) | dias | A API do GolPix só aceita expiresInDays (1–30 inteiro). Sub-1 dia é rejeitado para evitar surpresa silenciosa. Valores não múltiplos de 86400 são arredondados para cima ao próximo dia inteiro. |
| OnlyUp | 30 (30 s) | 604800 (7 dias) | segundos | — |
| FyHub | 30 (30 s) | 604800 (7 dias) | segundos | — |
| Treeal | 30 (30 s) | 604800 (7 dias) | segundos | — |
| AvivPay | 60 (1 min) | 86400 (24 h) | segundos | A API AvivPay aceita entre 60 s e 24 h. Acima de 86400 a API responde PROVIDER_EXPIRATION_ABOVE_MAXIMUM. |
| NixFin | 30 (30 s) | 604800 (7 dias) | segundos | — |
| a55 | 30 (30 s) | 604800 (7 dias) | segundos | A API a55 aceita até 30 dias, mas vale o teto da plataforma (7 dias). O valor é enviado em segundos (expiresInSeconds), então janelas inferiores a 1 dia são respeitadas exatamente. |
| AvivPay IP | 30 (30 s) | 604800 (7 dias) | segundos | Mesma API da a55: aceita até 30 dias, mas vale o teto da plataforma (7 dias). O valor é enviado em segundos (expiresInSeconds), então janelas inferiores a 1 dia são respeitadas exatamente. |
Forma do erro
Quando o expirationTime enviado é menor que o mínimo do provedor da conta:
HTTP/1.1 400 Bad Request
Content-Type: application/json{
"statusCode": 400,
"code": "PIX_PROVIDER_EXPIRATION_BELOW_MINIMUM",
"errorCode": "PROVIDER_EXPIRATION_BELOW_MINIMUM",
"message": "Provider woovi requires expirationTime >= 300s (got 30s)",
"userMessage": "O provedor woovi exige tempo mínimo de 300 segundos para expiração.",
"details": {
"provider": "woovi",
"providerMinSeconds": 300,
"granularity": "seconds",
"userExpirationTime": 30
},
"errorId": "<correlation-id>",
"timestamp": "2026-05-05T12:34:56.789Z",
"path": "/api/pix/cash-in",
"method": "POST"
}Use o campo details.providerMinSeconds para reapresentar a tentativa com o valor mínimo aceito.
Como saber qual provedor minha conta usa?
A configuração de provedor é por conta e é definida na criação. Em caso de dúvida sobre qual provedor está ativo, consulte seu gerente de integração ou o painel administrativo. Para a maioria das integrações isso não impacta o código do cliente, exceto se você precisa de janelas de expiração inferiores a 5 minutos em uma conta Woovi (inferiores a 1 dia em uma conta GolPix, ou superiores a 24 horas em uma conta AvivPay).