Os dois termos vêm das contas digitais e dos gateways. Separar entrada e saída ajuda a tratar fluxos, taxas e riscos diferentes: receber depende de alguém pagar, e enviar depende de haver saldo.
Na API da xFlow
A documentação da xFlow chama a cobrança Pix de cash-in e o saque de Pix out:
| Cash-in | Cash-out (Pix out) | |
|---|---|---|
| Endpoint | POST /api/v1/charges |
POST /api/v1/transfers |
| Valor | amountCents, em centavos |
amount, em centavos |
| Como o dinheiro anda | O cliente paga o QR Code ou o copia e cola | Para uma chave Pix (pix_key e pix_key_type) ou um qr_code |
| Webhooks | transaction.pending, transaction.paid |
withdrawal.processing, withdrawal.completed, withdrawal.failed |
| Status | pending, paid, expired e outros |
requested, processing, completed, rejected |
| Modo de teste | Disponível, com pagamento simulado | Indisponível: 403 test_mode_unsupported |
Regras do cash-out que mudam o seu código:
- Taxa. No saque por chave, a taxa sai do próprio
amount. No saque por QR Code, o destinatário recebe o valor do QR e a taxa é debitada por cima. - Aprovação. Com o saque automático desligado na conta, o saque nasce com
pending_approval: true. - Saque por API desligado. Nesse caso, a resposta é
403 api_withdrawal_disabled. - Duplicidade. Envie
Idempotency-Key: num retry, a API devolve o mesmo saque em vez de debitar de novo. Veja idempotência.
O estorno é um terceiro movimento. Ele devolve ao pagador o valor de uma cobrança paga, tem regras próprias e está explicado em estorno Pix por API.
Exemplo
O cash-out sai do saldo disponível, que você consulta antes do saque:
bash
curl https://app.xflowpayments.com/api/v1/balance -u "pk_live_...:sk_live_..."
# { "available": 73992, "reserved": 0, "currency": "BRL" }Depois, o saque para uma chave aleatória:
bash
curl -X POST https://app.xflowpayments.com/api/v1/transfers \
-u "pk_live_...:sk_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: repasse-0042" \
-d '{ "amount": 500, "pix_key": "123e4567-e89b-12d3-a456-426655440000", "pix_key_type": "EVP" }'Os campos da resposta, a aprovação e os erros do saque estão em API de saque Pix.
Termos relacionados
- Chave aleatória (EVP): um dos destinos do cash-out.
- Webhook: como você sabe que a entrada ou a saída concluiu.
- End-to-end ID: o identificador do Pix que entrou.