过期时间限制（expirationTime）

概述

FyPay API 在 POST /api/pix/cash-in 的 transaction.expirationTime 字段中接受以秒为单位、处于平台区间内的值：

最小值： 30（30 秒）
最大值： 604800（7 天）
默认值： 86400（24 小时），省略该字段时使用

超出该区间时，API 会以验证错误（400）拒绝请求。

此外，您账户的 PIX 清算机构可能只接受更窄的范围。该检查在收款创建之前进行，因此被拒绝的请求不会生成交易。

情形	响应	`errorCode`	`details` 中的有用字段
`expirationTime` 低于清算机构的最小值	`400 Bad Request`	`PROVIDER_EXPIRATION_BELOW_MINIMUM`	`providerMinSeconds`
`expirationTime` 高于清算机构的最大值	`400 Bad Request`	`PROVIDER_EXPIRATION_ABOVE_MAXIMUM`	`providerMaxSeconds`

目前存在的范围

大多数清算机构接受平台的完整范围（30 秒到 7 天）。目前配置的例外情况如下：

最小值	最大值	粒度	备注
`300`（5 分钟）	`604800`（7 天）	秒	低于 5 分钟的窗口会被拒绝
`60`（1 分钟）	`86400`（24 小时）	秒	高于 24 小时的窗口会被拒绝
`86400`（1 天）	`604800`（7 天）	天	低于 1 天会被拒绝。非 `86400` 整数倍的值会向上取整到下一个完整天数

该范围按账户生效，而不是按请求生效。如果您不确定账户适用哪个范围，请使用错误响应（details.providerMinSeconds 或 details.providerMaxSeconds），或通过 suporte@fypay.me [A DEFINIR] 联系支持团队。

错误结构

当提交的 expirationTime 小于账户清算机构的最小值时，响应示例如下：

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"
}

当值高于最大值时，errorCode 为 PROVIDER_EXPIRATION_ABOVE_MAXIMUM，details.providerMaxSeconds 给出可接受的上限。

如何处理

读取 details.providerMinSeconds（或 details.providerMaxSeconds），并使用范围内的值重新提交收款，保持相同的 externalId（被拒绝的收款并未创建）。
对于短窗口（POS、结账），请至少使用 5 分钟（300）：除按天计粒度的清算机构外，所有清算机构都接受该值。
如果您的业务依赖非常短（低于 5 分钟）或非常长（高于 24 小时）的窗口，请在上线生产前向支持团队确认账户的范围。

过期时间限制（expirationTime）

概述

目前存在的范围

错误结构

如何处理

本页目录