Saque

Troque o DePix da sua carteira por Pix na sua chave, pela API, sem passar pelo painel.

você ──DePix──► carteira de saque da Pix2DePix ──Pix──► sua chave
      (endereço só deste saque)

É o caminho inverso da cobrança. Serve para quem recebe em DePix e precisa de real na conta: fechamento de caixa, pagamento de fornecedor, reposição de saldo — tudo disparado do seu sistema, com o mesmo par de chaves que cria as cobranças.

Como funciona

1. Você cria o saque em POST /v1/withdrawals, dizendo quanto quer e para qual chave Pix.
2. A resposta traz deposit.address e deposit.amountInCents: envie exatamente esse valor de DePix para esse endereço, na Liquid.
3. Quando o depósito confirma na rede, o saque vai para processing e o Pix é pago em seguida.
4. Você recebe withdrawal.paid com o endToEndId — o comprovante do Pix no Banco Central.

O endereço é só deste saque: é ele, e não o valor, que diz de qual saque é o DePix que chegou. Não reaproveite o endereço de um saque anterior, e não junte dois saques num envio só.

Quanto custa

A taxa é R$ 3,00 fixos abaixo de R$ 100,00 de Pix e percentual daí para cima. Não há parcela fixa por depósito aqui — aquela é do Pix de entrada, e não existe na saída. A taxa de rede do nosso repasse é por nossa conta.

Você escolhe de que lado informa o valor:

Exatamente um dos dois por requisição — mandar os dois é 400 invalid_request. A resposta sempre traz os três números abertos em amount, e deposit.amountInCents é o que você precisa enviar.

Limites, do lado do Pix: R$ 10,00 a R$ 6.000,00 por saque. Os valores vigentes vêm em limits no GET /v1/account.

Sua taxa (merchantFeeBps)

Quem saca pela sua integração pode pagar uma taxa sua, além da nossa. Informe merchantFeeBps em pontos-base (100 = 1%, até 1.000 = 10%). Ela incide sobre o mesmo número que a nossa e vai em DePix para o seu endereço padrão do painel, na mesma transação do repasse — ou tudo sai, ou nada sai.

O endereço é lido quando o saque nasce: trocar o padrão depois não muda o destino de saque em andamento. Sem endereço padrão, merchantFeeBps é recusado com 422 merchant_address_missing. O limite mínimo de R$ 10,00 vale para o Pix depois da sua taxa. O saque devolve amount.merchantFeeInCents e amount.merchantFeeBps.

Cotação: GET /v1/withdrawals/quote

Os mesmos valores, pela query string, sem criar nada. É o número para mostrar a quem saca antes de confirmar:

curl "https://apiv2.pix2depix.com/v1/withdrawals/quote?depixAmountInCents=100000&merchantFeeBps=100" \
  -H "Authorization: Bearer $P2D_KEY"

{
  "depixInCents": 100000,
  "payoutInCents": 96000,
  "feeInCents": 3000,
  "feeBps": 300,
  "merchantFeeInCents": 1000,
  "merchantFeeBps": 100
}

A chave Pix

pixKey vai junto com pixKeyType (cpf, cnpj, email, telefone, aleatoria) e com payeeTaxNumber, o documento do dono da chave — é a titularidade que o provedor confere.

• O Pix pode ir para outra pessoa: payeeTaxNumber é de quem recebe, não de quem saca.
• Quando a chave é um CPF/CNPJ, ela e payeeTaxNumber precisam ser o mesmo documento. Divergir significa que um dos dois está errado, e a recusa chega antes de o DePix sair da sua carteira.
• Normalizamos o formato (máscara, +55, maiúsculas em e-mail). Chave que não casa com o tipo é 400 invalid_request.

Confira a chave antes de enviar o DePix. Pix pago na chave errada vai para um estranho, e não há estorno.

1. Crie o saque

curl https://apiv2.pix2depix.com/v1/withdrawals \
  -H "Authorization: Bearer $P2D_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amountInCents": 100000,
    "pixKeyType": "aleatoria",
    "pixKey": "6a4f5c1e-8b2d-4a7f-9c3e-1d2b3a4c5d6e",
    "payeeTaxNumber": "529.982.247-25",
    "externalId": "saque-77"
  }'

{
  "id": "6a92586d486e6a4f3d305214",
  "externalId": "saque-77",
  "status": "awaiting_deposit",
  "environment": "live",
  "amount": {
    "depixInCents": 103000,
    "feeInCents": 3000,
    "payoutInCents": 100000,
    "feeBps": 300
  },
  "deposit": {
    "address": "lq1qq…só-deste-saque",
    "amountInCents": 103000
  },
  "pix": {
    "key": "6a4f5c1e-8b2d-4a7f-9c3e-1d2b3a4c5d6e",
    "keyType": "aleatoria",
    "taxNumber": "•••.982.247-••"
  },
  "createdAt": "2026-09-20T13:58:02.000Z",
  "updatedAt": "2026-09-20T13:58:02.000Z"
}

Idempotência funciona como na cobrança: o mesmo externalId com o mesmo corpo devolve o saque original (200), e com corpo diferente é 409 external_id_conflict. Use a Idempotency-Key quando não tiver um id próprio — um retry de rede não pode virar dois saques.

O externalId é único por conta e ambiente, e o espaço é o mesmo das cobranças: se pedido-8891 já é uma cobrança sua, ele não serve para um saque. Use um prefixo (saque-…) e os dois convivem.

Não existe rota de cancelamento. Enquanto o DePix não chega, um saque parado não custa nada; depois que chega, cancelar seria mentir sobre dinheiro que já está conosco.

2. Envie o DePix

Mande deposit.amountInCents para deposit.address, na Liquid. Uma transferência por saque.

Enviar a menos deixa o saque parado em awaiting_deposit — quem confere o valor é a rede, não a boa vontade. Enviar a mais não aumenta o Pix: o combinado é o valor do saque.

3. Acompanhe pelos eventos

O corpo de withdrawal.paid:

{
  "id": "6a93c1f0b245fe8443a36011",
  "type": "withdrawal.paid",
  "createdAt": "2026-09-20T14:03:11.000Z",
  "environment": "live",
  "data": {
    "withdrawal": {
      "id": "6a92586d486e6a4f3d305214",
      "externalId": "saque-77",
      "status": "paid",
      "pix": {
        "key": "6a4f5c1e-8b2d-4a7f-9c3e-1d2b3a4c5d6e",
        "keyType": "aleatoria",
        "taxNumber": "•••.982.247-••",
        "endToEndId": "E00000000202609201403abcdef0123",
        "paidAt": "2026-09-20T14:03:09.000Z"
      }
    }
  }
}

Repare que o evento de saque traz data.withdrawal, e não data.charge. Assinatura, deduplicação por id e retentativas são os mesmos de qualquer evento — está tudo em Webhooks. Se o seu endpoint ainda não trata withdrawal.*, responda 2xx e ignore: evento desconhecido não é erro.

O GET /v1/withdrawals/{id} responde o mesmo estado a qualquer momento, e o GET /v1/withdrawals lista com os mesmos filtros da cobrança.

Status do saque

Teste no sandbox

Com uma chave p2d_test_ nada sai da sua carteira: o endereço de depósito é um texto que nenhuma carteira aceita, e quem move o saque é você.

# 1. crie o saque com a chave de teste (mesmo corpo da produção)
# 2. simule o DePix recebido
curl https://apiv2.pix2depix.com/v1/test/withdrawals/$ID/advance \
  -H "Authorization: Bearer $P2D_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "processing" }'

# 3. simule o Pix pago
curl https://apiv2.pix2depix.com/v1/test/withdrawals/$ID/advance \
  -H "Authorization: Bearer $P2D_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paid" }'

Os dois webhooks chegam ao seu endpoint de teste, com o mesmo formato da produção. Voltar atrás é 409 invalid_transition.

O exemplo completo, executável, está em exemplos/saque.mjs.

Erros específicos

Os demais são os mesmos da cobrança — veja Erros.