Ir al contenido

Pago a llave Pix

POST /v1/br/payout/pix/key

Envía dinero a una llave Pix. Al crear el pago se retiene amount + feeCharged de tu saldo disponible; al completarse se debita, y si falla se libera.

{
"pixKeyType": "CPF",
"pixKeyValue": "123.456.789-00",
"amount": 5000,
"description": "Pago a proveedor",
"reference": "PAGO-20261005-0001"
}
CampoTipoRequeridoDescripción
pixKeyTypestring✅CPF, CNPJ, EMAIL, PHONE, EVP (no distingue mayúsculas)
pixKeyValuestring✅Valor de la llave Pix
amountnumber✅Centavos, entero > 0, máximo 100.000.000 (R$ 1.000.000), además de los límites de tu tarifa
descriptionstring❌Descripción del pago
referencestring❌Tu referencia interna; vuelve en los webhooks como reference
{
"txId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
"status": "PROCESSING",
"amount": 5000,
"feeCharged": 200,
"totalDebit": 5200,
"currency": "BRL",
"estimatedCompletion": "seconds"
}
CampoDescripción
txIdID del pago — un UUID (con guiones), a diferencia del cobro
statusEstado inicial (PROCESSING)
feeChargedComisión en centavos
totalDebitTotal retenido de tu saldo (amount + feeCharged)
estimatedCompletionTiempo estimado de liquidación

El resultado final llega por webhook (payout.completed o payout.failed). Para consultar el estado: Estado del pago.

La red Pix no confirmó a tiempo si recibió la orden. No es un error: el pago pudo haber salido (Pix es instantáneo y no se puede cancelar), así que queda PENDING con el saldo retenido hasta que la red confirme el desenlace.

{
"txId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
"status": "PENDING",
"amount": 5000,
"feeCharged": 200,
"totalDebit": 5200,
"currency": "BRL",
"message": "Provider did not confirm in time; final status will be notified by webhook. Do not create a new payout."
}
CódigoCausa
400Campos faltantes o inválidos, pixKeyType fuera del enum, monto ≤ 0, no entero o > R$ 1.000.000, o falta X-Idempotency-Key
402Saldo insuficiente — error.details incluye availableBalance y requiredAmount
409Tarifa de Brasil no configurada (FEE_NOT_CONFIGURED) o petición idempotente en curso
422Monto fuera de los límites de tu tarifa, o la red rechazó la operación (p. ej. llave inexistente)

Si la red no responde a tiempo no recibes un error sino 202 Accepted con status: PENDING.

Lista completa en Errores.