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.
Request body
Sección titulada «Request body»{ "pixKeyType": "CPF", "pixKeyValue": "123.456.789-00", "amount": 5000, "description": "Pago a proveedor", "reference": "PAGO-20261005-0001"}| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
pixKeyType | string | ✅ | CPF, CNPJ, EMAIL, PHONE, EVP (no distingue mayúsculas) |
pixKeyValue | string | ✅ | Valor de la llave Pix |
amount | number | ✅ | Centavos, entero > 0, máximo 100.000.000 (R$ 1.000.000), además de los límites de tu tarifa |
description | string | ❌ | Descripción del pago |
reference | string | ❌ | Tu referencia interna; vuelve en los webhooks como reference |
Response 201 Created
Sección titulada «Response 201 Created»{ "txId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e", "status": "PROCESSING", "amount": 5000, "feeCharged": 200, "totalDebit": 5200, "currency": "BRL", "estimatedCompletion": "seconds"}| Campo | Descripción |
|---|---|
txId | ID del pago — un UUID (con guiones), a diferencia del cobro |
status | Estado inicial (PROCESSING) |
feeCharged | Comisión en centavos |
totalDebit | Total retenido de tu saldo (amount + feeCharged) |
estimatedCompletion | Tiempo estimado de liquidación |
El resultado final llega por webhook (payout.completed o payout.failed). Para consultar el estado: Estado del pago.
Response 202 Accepted
Sección titulada «Response 202 Accepted»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."}Errores
Sección titulada «Errores»| Código | Causa |
|---|---|
400 | Campos faltantes o inválidos, pixKeyType fuera del enum, monto ≤ 0, no entero o > R$ 1.000.000, o falta X-Idempotency-Key |
402 | Saldo insuficiente — error.details incluye availableBalance y requiredAmount |
409 | Tarifa de Brasil no configurada (FEE_NOT_CONFIGURED) o petición idempotente en curso |
422 | Monto 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.