跳到主要内容

发起提现

使用此端点通过一次调用，将资金从您的账户发送给客户或合作方。

作为替代方案，两步流程会在实际出款前确认 PIX 密钥属于预期的持有人：创建提现意向，然后确认提现意向。

可用环境​

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

端点​

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

请求体​

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

所有金额字段（amount）都必须以分为单位、以整数形式传入。

示例：

  • R$10.00 = 1000
  • R$99.99 = 9999
  • R$100.50 = 10050

请勿使用： 99.99、10.00、负数 请使用： 9999、1000（始终为整数）

名称类型必填说明校验规则
amountnumber是提现金额（整数，以分为单位）必须为以分为单位的整数；最小 10（R$0.10），最大 10000000（R$100,000.00）
methodstring (enum) - PIX（默认值：PIX）否提现方式必须为有效的枚举值
webhookUrlstring (URL)否用于接收通知的 HTTPS URL必须为有效的 URL 且必须使用 https；不得包含片段（#）；必须包含主机名与顶级域名；允许带查询参数
externalCodestring否您的参考编号长度须在 8 到 255 个字符之间
observationstring否关于该笔提现的内部备注最多 255 个字符
idempotencyKeystring是用于避免重复提交的唯一标识长度须在 8 到 255 个字符之间
ℹ️ observation 仅供内部使用

observation 字段会被保存，但不会在查询提现或查询提现列表中返回。

提现的收款方​

名称类型必填说明校验规则
pixKeystring是目标 PIX 密钥须按照所传入的 pixKeyType 进行校验：
  • CPF：11 位数字
  • CNPJ：14 位数字
  • EMAIL：有效的邮箱格式
  • PHONE：巴西手机号格式（+5511999999999）
  • EVP：有效的 UUID
pixKeyTypestring (enum) - CPF, CNPJ, EMAIL, PHONE, EVP是密钥类型必须为有效的枚举值

请求示例​

curl --request POST \
--url https://api.gateway.com.br/core/withdrawal \
--header 'Authorization: Bearer your-jwt-token' \
--header 'Content-Type: application/json' \
--data '{
    "amount": 10000,
    "pixKey": "12345678910",
    "pixKeyType": "CPF",
    "webhookUrl": "https://sua-api.com/webhooks/withdrawal",
    "externalCode": "SAQUE-123",
    "observation": "Repasse referente ao pedido 4521",
    "idempotencyKey": "unique-key-12345"
}'

成功响应​

字段类型必填说明
idstring (UUID)是提现的唯一标识
externalCodestring否您的参考编号
amountnumber是提现金额（整数，以分为单位）
statusstring (enum) - PENDING是
  • PENDING：提现已创建，等待处理

响应示例​

{
  "id": "553e8400-e29b-41d4-a716-436251480000",
  "externalCode": "SAQUE-123",
  "amount": 10000,
  "status": "PENDING"
}

可能的错误​

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