跳转到主要内容
POST
创建 PIX 提现
异步处理。 创建提现时返回的是非终态状态(pending 或 processing)——最终结果始终通过 webhook 送达(withdrawal.completed 或 withdrawal.failed)。请以 webhook 为准;不要把创建接口的响应当作最终结果。校验错误(余额不足、超出限额、数据无效)会在调用本身直接返回错误。

发送队列

提现被受理后,会进入向支付机构发送的队列。大多数情况下会立即发送;在交易高峰期可能需要几秒到几分钟,等待期间提现保持 processing 状态。
  • 按到达顺序。 提现按创建顺序依次发送。
  • 不存在的密钥代价高昂。 每笔提现都会在 DICT 中查询目标 PIX 密钥,而巴西中央银行对这类查询设有限额——查询一个不存在的密钥所消耗的额度远高于一次成功的查询。当某个账户因密钥不存在或无效而累积多次拒绝时,其后续提现在队列中的优先级会降低,等待时间更长。请在发送前校验密钥,不要用提现来测试密钥是否存在。
  • 密钥查询被暂停。 如果机构提示查询限额已用尽,尚未发送的提现将在队列中等待,直到恢复为止。已经发送的提现可能以 withdrawal_failed 返回,金额退回余额。
  • 最长期限。 6 小时内仍无法发送的提现将失败(withdrawal_failed),预留金额退回余额。
无论哪种情况,最终结果都通过 webhook 送达。

授权

Authorization
string
header
必填

通过 POST /auth(client_id + client_secret)获取的访问令牌。有效期 300 秒。

请求头

Idempotency-Key
string

由客户端生成的唯一键(8-255 个字符),使请求具备幂等性。使用相同键重试时返回缓存的响应(TTL 24 小时)。相同键但请求体不同时返回 422。

Required string length: 8 - 255
X-Sub-Account
string

执行操作的子账户的 reference。省略时,操作在主账户上执行;保留值 principal 同样解析为主账户,等同于省略该请求头。除 POST /auth 和 /sub-accounts 自身的端点(始终在主账户上操作)外,所有端点均接受该请求头。

可能的错误:404 SUB_ACCOUNT_NOT_FOUND、403 SUB_ACCOUNT_FORBIDDEN、403 SUB_ACCOUNT_SUSPENDED。

要求凭证已启用子账户访问(设置 → 集成 → API 凭证)。该项默认关闭,任何权限都无法替代,FULL_ACCESS 也不例外:未启用时响应为 403 SUB_ACCOUNT_FORBIDDEN。

Pattern: ^[a-z0-9][a-z0-9_-]{1,31}$
示例:

"loja-centro"

请求体

application/json

创建 PIX 提现所需的数据。amount(从余额中扣除的总额)或 netAmount(收款人应收到的净额)只能提供其中一个。

pixKey
string
必填

收款人的 PIX 密钥。

示例:

"12345678901"

pixKeyType
enum<string>
必填

PIX 密钥类型。

可用选项:
cpf,
cnpj,
email,
phone,
random
示例:

"cpf"

holderName
string
必填

PIX 账户持有人姓名。

示例:

"João da Silva"

holderDocument
string
必填

持有人的 CPF 或 CNPJ。

示例:

"12345678901"

holderDocumentType
enum<string>
必填

持有人证件类型。

可用选项:
cpf,
cnpj
示例:

"cpf"

projectId
string<uuid>

提现所属的项目 ID。如未提供且账户只有一个项目,提现将继承该项目;如有多个项目,提现将不关联任何项目——与创建 PIX 收款时的行为一致。

示例:

"3c90c3cc-0d44-4b50-8888-8dd25736052a"

amount
number

从余额中扣除的总额(BRL)。收款人收到 amount - feeAmount。最低 R$ 1,00。提供 amount 或 netAmount——不可同时提供。

必填范围: x >= 1
示例:

150.75

netAmount
number

收款人应收到的净额(BRL)。API 会计算所需的总额(gross = netAmount + feeAmount)并从余额中扣除该总额。最低 R$ 1,00。提供 amount 或 netAmount——不可同时提供。

必填范围: x >= 1
示例:

150

externalReference
string

您的外部参考 ID(可选)。会在响应以及 webhook withdrawal_completed 和 withdrawal_failed 中返回,便于与您的内部系统对账。

Maximum string length: 255
示例:

"saque-empresa-001"

响应

提现创建成功

已创建的提现数据。

id
string<uuid>
必填

提现 ID

示例:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

amount
number
必填

提现金额(BRL)

示例:

150.75

feeAmount
number
必填

手续费金额(BRL)

示例:

2.5

netAmount
number
必填

净额(BRL)

示例:

148.25

status
enum<string>
必填

提现状态

可用选项:
pending,
processing,
completed,
failed
示例:

"completed"

snapshotHolderName
string
必填

提现时的持有人姓名

示例:

"João da Silva"

snapshotHolderDocument
string
必填

提现时的持有人证件号

示例:

"12345678901"

createdAt
string<date-time>
必填

创建时间

示例:

"2026-02-10T14:30:00.000Z"

projectId
string<uuid> | null

提现所属的项目 ID(创建时未提供且账户有 2 个及以上项目时为 null)

示例:

"3c90c3cc-0d44-4b50-8888-8dd25736052a"

snapshotPixKey
string | null

提现时使用的 PIX 密钥

示例:

"12345678901"

snapshotPixKeyType
enum<string> | null

提现时使用的 PIX 密钥类型

可用选项:
cpf,
cnpj,
email,
phone,
random
示例:

"cpf"

failureReason
string | null

失败原因(当 status = failed 时)

示例:

null

pspReference
string | null

PSP(支付服务提供商)参考号

示例:

null

processedAt
string<date-time> | null

处理时间

示例:

"2026-02-10T14:30:01.000Z"

externalReference
string | null

创建提现时发送的外部参考(可选)

示例:

"saque-empresa-001"