跳到主要内容

创建定期提现

使用此端点为指定的目标 PIX 密钥设置自动、周期性的提现。

创建定期提现时，接口会根据传入的频率与持续次数自动生成全部排期（schedulings）。每条排期都会在各自的预计日期按普通提现单独处理。

可用环境​

https://api.gateway.com.br/core

端点​

  • 方法：POST
  • 端点：/recurring-withdrawal
  • 认证方式：Bearer token

请求体​

⚠️ 重要：金额以分为单位

金额字段（amount）必须以分为单位，并以整数发送。

示例：

  • R$10.00 = 1000
  • R$99.99 = 9999
ℹ️ frequencyType 与 frequencyUnit 的组合
  • REPEAT_EVERY（每隔 X 天／月重复一次）：frequencyUnit 可为 DAYS 或 MONTHS。frequencyValue 是两次执行之间的间隔（例如 frequencyValue: 15 搭配 frequencyUnit: DAYS 表示每 15 天一次）。
  • FIXED_DAY（每月固定某一天）：要求 frequencyUnit: MONTHS。frequencyValue 是提现应发生的当月日期（1 到 31）。若当月没有该日期，提现在该月最后一天执行。
名称类型必填说明校验规则
amountnumber是每次提现的金额（整数，以分为单位）必须为以分为单位的整数；最小 10（R$0.10），最大 10000000（R$100,000.00）
descriptionstring是定期提现的说明长度须在 2 到 255 个字符之间
pixKeystring是目标 PIX 密钥需按传入的 pixKeyType 校验：
  • CPF：11 位数字
  • CNPJ：14 位数字
  • EMAIL：有效的邮箱格式
  • PHONE：巴西号码格式（+5511999999999）
  • EVP：有效的 UUID
pixKeyTypestring (enum) - CPF, CNPJ, EMAIL, PHONE, EVP是密钥类型必须为有效的枚举值
frequencyTypestring (enum) - REPEAT_EVERY, FIXED_DAY是频率类型必须为有效的枚举值
frequencyUnitstring (enum) - DAYS, MONTHS是频率单位若 frequencyType 为 FIXED_DAY，则必须为 MONTHS
frequencyValuenumber是间隔（REPEAT_EVERY 时）或每月的第几天（FIXED_DAY 时）最小 1；若 frequencyType 为 FIXED_DAY，最大 31
durationnumber是需要排期的执行次数必须为整数；最小 1；最大 255

请求示例​

curl --request POST \
--url https://api.gateway.com.br/core/recurring-withdrawal \
--header 'Authorization: Bearer your-jwt-token' \
--header 'Content-Type: application/json' \
--data '{
    "amount": 10000,
    "description": "Repasse mensal para fornecedor",
    "pixKey": "12345678910",
    "pixKeyType": "CPF",
    "frequencyType": "FIXED_DAY",
    "frequencyUnit": "MONTHS",
    "frequencyValue": 5,
    "duration": 12
}'

成功响应​

字段类型必填说明
idstring (UUID)是定期提现的唯一标识
amountnumber是每次提现的金额（整数，以分为单位）
statusstring (enum) - ACTIVE是
  • ACTIVE：定期提现已创建，排期处于生效状态

响应示例​

{
  "id": "553e8400-e29b-41d4-a716-436251480000",
  "amount": 10000,
  "status": "ACTIVE"
}

可能的错误​

状态码说明处理方式
401凭据无效请检查您的凭据
403无权限或未授权请联系技术支持
422数据无效或缺失请检查数据格式
422校验失败请联系技术支持
500内部错误请联系技术支持