Expiration limits (expirationTime)
Overview
The FyPay API accepts, in the transaction.expirationTime field of POST /api/pix/cash-in, a value in seconds within the platform range:
- Minimum:
30(30 seconds) - Maximum:
604800(7 days) - Default:
86400(24 hours), when the field is omitted
Outside that range, the API rejects the request with a validation error (400).
Additionally, your account's PIX settlement provider may accept a narrower range. This check happens before the charge is created, so a rejected request does not create a transaction.
| Situation | Response | errorCode | Useful field in details |
|---|---|---|---|
expirationTime below the settlement provider's minimum | 400 Bad Request | PROVIDER_EXPIRATION_BELOW_MINIMUM | providerMinSeconds |
expirationTime above the settlement provider's maximum | 400 Bad Request | PROVIDER_EXPIRATION_ABOVE_MAXIMUM | providerMaxSeconds |
Ranges that exist today
Most settlement providers accept the full platform range (30 s to 7 days). The exceptions configured today are:
| Minimum | Maximum | Granularity | Note |
|---|---|---|---|
300 (5 min) | 604800 (7 days) | seconds | Windows below 5 minutes are rejected |
60 (1 min) | 86400 (24 h) | seconds | Windows above 24 hours are rejected |
86400 (1 day) | 604800 (7 days) | days | Below 1 day is rejected. Values that are not multiples of 86400 are rounded up to the next whole day |
The range applies to the account, not to the request. If you do not know which range applies to your account, use the error response (details.providerMinSeconds or details.providerMaxSeconds) or contact support at suporte@fypay.me [A DEFINIR].
Error shape
Example response when the submitted expirationTime is below the account settlement provider's minimum:
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"
}When the value is above the maximum, the errorCode is PROVIDER_EXPIRATION_ABOVE_MAXIMUM and details.providerMaxSeconds carries the accepted ceiling.
How to handle it
- Read
details.providerMinSeconds(ordetails.providerMaxSeconds) and resend the charge with a value within the range, keeping the sameexternalId(the rejected charge was not created). - For short windows (POS, checkout), use at least 5 minutes (
300): this value is accepted by every settlement provider, except those with day granularity. - If your operation depends on very short windows (below 5 minutes) or long ones (above 24 hours), confirm the account's range with support before going to production.