Skip to main content

​
Resumen

Cree transferencias PIX salientes desde cuentas BRL con POST /api/v1/br/transactions/outbound. Requiere saldo neto suficiente. La transacción inicia en processing si es aceptada, o cancelled si no puede crearse.

​
Campos obligatorios

  • accountId, amount
  • name — nombre del beneficiario
  • keyType — document, email, evp, phone o cnpj
  • keyPix — clave PIX de destino según keyType (obligatoria; no puede omitirse)

​
Campos opcionales

  • document — CPF o CNPJ del beneficiario (11 o 14 dígitos). Se reenvía al proveedor PIX cuando se envía. Puede usar valores con formato (por ejemplo 123.456.789-01); HG.Cash normaliza a dígitos antes de llamar al proveedor.

​
Cash-in vs cash-out

El cash-in PIX exige document del pagador. Los payouts salientes exigen keyType + keyPix porque la API del proveedor de retiro por clave usa pixKey (obligatorio) y document (opcional). El document opcional en cash-out identifica al titular de la clave cuando lo envía — no reemplaza a keyPix. Cuando keyType es document o cnpj, envíe keyPix como clave de destino. HG.Cash elimina la puntuación antes de reenviar claves CPF/CNPJ al proveedor.

​
Actualizaciones de estado

Los webhooks de estado usan el cuerpo de movimiento de cuenta (topic TRANSACTION, eventType status_change). Un identificador end-to-end de PIX guardado se envía como endToEndId y se omite cuando está vacío. Ver Identificador end-to-end PIX.

​
Ejemplos

Clave email:
Clave CPF (keyType: document). Puede enviar CPF con o sin máscara en keyPix; HG.Cash reenvía solo dígitos:

​
Ciclo del payout

Un payout aceptado inicia en processing. Pasa a done cuando se liquida la transferencia PIX, o a cancelled cuando el proveedor la rechaza o falla. Resultados del proveedor como FAILED y REJECTED de Zetta/Bankizi se normalizan a cancelled. HG.Cash no expone un estado failed separado en los payouts de Brasil. Use polling (GET /api/v1/br/transactions/{id}/status) o su webhook para reaccionar a los cambios.

​
Estado de la cuenta

La cuenta origen debe estar Operativa. Las solicitudes contra cuentas Bloqueada o Cerrada devuelven 403 con code: ACCOUNT_NOT_OPERATIVE.