创建提现意向

使用此端点在实际出款前校验提现的收款方，确认该 PIX 密钥确实属于您预期的持有人。

响应会返回收款人姓名以及一个 intentId，随后您将其传给确认提现意向。这是两步流程的第一步；若要通过一次调用直接创建提现，请使用发起提现。

可用环境

生产环境

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

端点

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

请求体

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

amount 必须以分为单位、以整数形式传入。

示例：

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

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

ℹ️ holderDocument 会与密钥进行比对

平台会查询该 PIX 密钥的持有人，并与您传入的 holderDocument 进行比对。若两者并非同一人，则不会创建意向，请求将被拒绝。

正是这项检查让本流程区别于直接创建：您能在资金转出之前就发现该密钥并不属于预期的持有人。

ℹ️ 意向将在 5 分钟后过期

intentId 的有效期为 5 分钟。超过该时间后，确认接口会返回意向不存在或已过期，您需要重新创建一个。

名称	类型	必填	说明	校验规则
`amount`	number	是	提现金额（整数，以分为单位）	必须为以分为单位的整数；最小 `10`（R$0.10），最大 `10000000`（R$100,000.00）
`method`	string (enum) - `PIX`（默认值：`PIX`）	否	提现方式	必须为有效的枚举值
`holderDocument`	string	是	您预期在该密钥上查到的持有人证件号	必须为有效的 CPF 或 CNPJ，且须与密钥的持有人一致
`webhookUrl`	string (URL)	否	用于接收通知的 HTTPS URL	必须为有效的 URL 且必须使用 `https`；不得包含片段（#）；必须包含主机名与顶级域名；允许带查询参数
`externalCode`	string	否	您的参考编号	长度须在 8 到 255 个字符之间
`observation`	string	否	关于该笔提现的内部备注	最多 255 个字符

提现的收款方

名称	类型	必填	说明	校验规则
`pixKey`	string	是	收款人的 PIX 密钥	必须是与所传 `pixKeyType` 相匹配的有效密钥
`pixKeyType`	string (enum) - `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP`	是	PIX 密钥类型	必须为有效的枚举值

请求示例

cURL
JavaScript

curl --request POST \
--url https://api.gateway.com.br/core/withdrawal/intent \
--header 'Authorization: Bearer your-jwt-token' \
--header 'Content-Type: application/json' \
--data '{
    "amount": 10000,
    "pixKey": "12345678910",
    "pixKeyType": "CPF",
    "holderDocument": "123.456.789-10",
    "webhookUrl": "https://sua-api.com/webhooks/withdrawal",
    "externalCode": "SAQUE-123",
    "observation": "Repasse semanal"
}'

const response = await fetch('https://api.gateway.com.br/core/withdrawal/intent', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-jwt-token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 10000,
    pixKey: '12345678910',
    pixKeyType: 'CPF',
    holderDocument: '123.456.789-10',
    webhookUrl: 'https://sua-api.com/webhooks/withdrawal',
    externalCode: 'SAQUE-123',
    observation: 'Repasse semanal',
  })
});
const data = await response.json();

成功响应

字段	类型	必填	说明
`intentId`	string (UUID)	是	意向的标识，用于确认该笔提现
`type`	string (enum) - `PIX_KEY`	是	所解析收款方的来源
`method`	string (enum) - `PIX`	是	提现方式
`amount`	number	是	提现金额（整数，以分为单位）
`receiverName`	string	否	收款人姓名，当 PSP 提供该信息时返回

字段	类型	必填	说明
`pixKey`	string	是	收款方的 PIX 密钥
`pixKeyType`	string (enum) - `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP`	是	收款方的 PIX 密钥类型

响应示例

{
  "intentId": "553e8400-e29b-41d4-a716-436251480000",
  "type": "PIX_KEY",
  "method": "PIX",
  "amount": 10000,
  "receiverName": "Fulano de Tal",
  "pixKey": "12345678910",
  "pixKeyType": "CPF"
}

可能的错误

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

状态码	说明	处理方式
422	该 PIX 密钥不属于所传入的证件号	请核对 `holderDocument` 与 `pixKey`

可用环境​

端点​

请求体​

提现的收款方​

请求示例​

成功响应​

响应示例​

可能的错误​