API Reference

Criar cashout (saque/transferência PIX)

post
https://api.voidxpay.com/v1/cashout

Cria um saque (transferência PIX) para o destino informado. O valor é debitado do saldo da conta imediatamente (incluindo taxas).

Suporta dois modos mutuamente exclusivos no campo pix:

  • Chave PIX: informe pixKeyType + pixKey
  • PIX Copia e Cola: informe pixCopyPaste com o código BR Code (mín. 50 caracteres)

O status inicial é pending. Acompanhe a evolução via webhooks: cashout.processing → cashout.completed.

Em caso de falha (cashout.failed, cashout.rejected, cashout.cancelled), o saldo é devolvido automaticamente.

Idempotência

Use o campo idempotencyKey para evitar cobranças duplicadas. Se uma requisição com a mesma chave já existir, retorna 409 Conflict com o ID da transação existente.

Body Params
integer
required
≥ 1

Valor do saque em centavos. Mínimo 1 centavo.

pix
object
required

Dados do destino PIX. Aceita dois formatos mutuamente exclusivos:

  • Chave PIX: pixKeyType + pixKey
  • Copia e Cola: pixCopyPaste

Se ambos forem enviados, a API retorna erro 400.

beneficiary
object

Dados do destinatário da transferência. Aplica-se apenas ao modo chave PIX. No modo copia e cola, o beneficiário já está embutido no código PIX e este campo é ignorado. Quando não informado no modo chave PIX, o sistema usa o nome do usuário como fallback para name.

string
length ≤ 500

Descrição do saque (máximo 500 caracteres).

string

Chave de idempotência para evitar cobranças duplicadas. Se não informada, uma UUID é gerada automaticamente.

uri

URL para receber webhooks específicos desta transação (deve usar http ou https).

metadata
object

Objeto com dados extras (chave-valor livre). Não aceita arrays ou null.

Responses

Updated 20 days ago

Language
Credentials
Basic
base64
:
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 20 days ago