Enviar Pix
Envia um Pix para qualquer chave, debitando da carteira o valor mais a taxa. O resultado final chega pelos webhooks payout.completed ou payout.failed.
POST
/payoutsEnvia um Pix (cash-out) para uma chave.
Headers
| Campo | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer <TOKEN> |
Idempotency-Keycondicional | string | Alternativa à reference para a idempotência.Obrigatório quando não houver reference no corpo. |
Content-Typeobrigatório | string | application/json |
Corpo da requisição
| Campo | Tipo | Descrição |
|---|---|---|
amountobrigatório | number | Valor em reais. Mínimo 1.00. A taxa (fee) é debitada junto. |
referencecondicional | string | Identificador do seu sistema; garante que o mesmo saque não sai duas vezes. Veja Idempotência.Obrigatório quando não houver o header Idempotency-Key. |
pixobrigatório | object | Chave Pix de destino. |
pix.typeobrigatório | string | cpf, cnpj, email, phone ou random. |
pix.keyobrigatório | string | A chave, até 255 caracteres, no formato do tipo. |
recipientopcional | object | Dados do titular da chave. |
recipient.tax_idcondicional | string | CPF ou CNPJ do titular da chave, até 20 caracteres.Obrigatório quando a sua conta exige, exceto se pix.type for cpf ou cnpj (a própria chave é usada). |
metadataopcional | object | Dados livres do seu sistema; voltam na resposta e nos webhooks. |
verify_keyopcional | boolean | Só com a validação de chave ativa. Padrão true: valida o titular antes de pagar (resposta 202). Envie false para confirmar o envio depois de conferir. |
curl -X POST "https://api.sancopay.com/api/v1/payouts" \ -H "Authorization: Bearer <TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "amount": 250, "reference": "SAQUE-0001", "pix": { "type": "email", "key": "[email protected]" }, "recipient": { "tax_id": "98765432100" }, "metadata": { "invoice": "NF-778" } }'Saque aceito e enviado. Acompanhe pelo webhook payout.*.
{ "id": 912, "tracking_id": "9b7f3c2e-41d8-4a6e-b0c5-2f1e8d7a6c90", "reference": "SAQUE-0001", "status": "processing", "amount": 250, "fee": 1, "total": 251, "pix": { "type": "email", "key": "[email protected]", "masked_key": "jo***@exemplo.com" }, "recipient": { "name": "JOAO PEREIRA", "tax_id": "***.654.321-**", "bank": "Banco Exemplo S.A." }, "end_to_end_id": null, "pre_approval_id": null, "metadata": { "invoice": "NF-778" }, "failure_reason": null, "created_at": "2026-11-09T15:04:05.000000Z", "updated_at": "2026-11-09T15:04:05.000000Z"}Tipos de chave
cpf- CPF do titular, 11 dígitos (com ou sem máscara).
cnpj- CNPJ do titular, 14 dígitos (com ou sem máscara).
email- E-mail cadastrado como chave.
phone- Celular com DDI e DDD:
+5511999998888. random- Chave aleatória (EVP), no formato uuid.
Status do saque
pending- Recebido, ainda não enviado ao processador.
processing- Enviado; aguardando a confirmação do Pix.
completed- Pix entregue ao destinatário.
end_to_end_idpreenchido. failed- Não foi concluído; o valor e a taxa voltam ao saldo. Motivo em
failure_reason. refunded- Devolvido pelo banco do destinatário; o valor volta ao saldo.