Realizar pago PIX (Cash-Out)

POST /api/pix/cash-out

Envia un pago PIX a una clave PIX de destino. La transaccion se crea con estado PENDING y el resultado final se notifica via webhook o puede consultarse via polling.

Autenticacion

Requiere un Bearer token en el header Authorization.

Request Body

Campo	Tipo	Obligatorio	Descripcion
`value`	number	Si	Monto en reales (hasta 2 decimales). Minimo: `0.01`
`externalId`	string	Si	Identificador externo unico por cuenta
`description`	string	No	Descripcion de la transaccion (max 140 caracteres)
`details`	object	Si	Informacion de la clave PIX de destino
`details.key`	string	Si	Clave PIX de destino (vea los formatos en la tabla a continuacion)
`details.keyType`	string	Si	Tipo de clave: `DOCUMENT`, `EMAIL`, `PHONE`, `RANDOM`. Obligatorio ya que la API no consulta DICT
`details.name`	string	Si	Nombre del destinatario (informativo, max 100 caracteres)
`details.document`	string	Si	CPF (11 digitos) o CNPJ (14 digitos) del titular. Obligatorio para todos los keyTypes

Formatos aceptados para `details.key`

`keyType`	Formato	Ejemplo
`DOCUMENT`	CPF: 11 digitos / CNPJ: 14 digitos (solo numeros)	`12345678901`, `12345678000195`
`EMAIL`	Direccion de email valida	`usuario@exemplo.com`
`PHONE`	DDD + numero (10-11 digitos, sin DDI +55)	`11999999999`
`RANDOM`	UUID (con o sin guiones)	`a1b2c3d4-e5f6-4890-abcd-ef1234567890`

El campo details.document es obligatorio para todos los tipos de clave, incluyendo EMAIL, PHONE y RANDOM. Se envia al banco liquidante para verificacion en la DICT. Si el documento no corresponde al titular de la clave PIX, el banco retornara el error TAX_ID_MISMATCH.

Ejemplos de Request

Pago por CPF -- el caso mas comun. El details.key y details.document son iguales (ambos son el CPF).

{
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678901",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678901"
  }
}

Pago por CNPJ -- comun en pagos B2B (proveedores, facturas).

{
  "value": 4500.00,
  "externalId": "NF-2024-0089",
  "description": "NF 0089/2024 - Serviços de hospedagem",
  "details": {
    "key": "11222333000144",
    "keyType": "DOCUMENT",
    "name": "Cloud Provider Ltda",
    "document": "11222333000144"
  }
}

Pago por clave email. Note que details.document debe ser el CPF/CNPJ del titular de la clave (no puede inferirse por el email).

{
  "value": 89.90,
  "externalId": "COMM-2024-0456",
  "description": "Comissão venda #456",
  "details": {
    "key": "vendedor@loja.com.br",
    "keyType": "EMAIL",
    "name": "Roberto Vendas",
    "document": "98765432100"
  }
}

Pago por clave telefono. El formato es DDD + numero (10 u 11 digitos), sin el DDI +55.

{
  "value": 25.00,
  "externalId": "REEMB-2024-0012",
  "description": "Reembolso uber colaborador",
  "details": {
    "key": "11987654321",
    "keyType": "PHONE",
    "name": "Pedro Almeida",
    "document": "11122233344"
  }
}

Pago por clave aleatoria (EVP/UUID). Generada por el BACEN, no contiene informacion personal.

{
  "value": 1250.00,
  "externalId": "RENT-2024-JAN",
  "description": "Aluguel janeiro/2024",
  "details": {
    "key": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
    "keyType": "RANDOM",
    "name": "Imobiliária Central",
    "document": "55666777000199"
  }
}

Response (201 Created)

Campo	Tipo	Descripcion
`transactionId`	string	Identificador interno de la transaccion generada (UUID)
`externalId`	string	Identificador externo informado en la solicitud
`status`	string	Estado inicial: `PENDING`. Confirmacion via webhook: `CONFIRMED` o `ERROR`
`generateTime`	string	Fecha/hora de generacion de la transaccion (ISO 8601 UTC)

{
  "transactionId": "8b3b85ac-394c-4144-9bcb-c5d12de3fa56",
  "externalId": "PAG-2024-0001",
  "status": "PENDING",
  "generateTime": "2024-01-15T10:30:00.000Z"
}

Errores

Retornado cuando el body no cumple con las validaciones.

{
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "path": "/api/pix/cash-out",
  "method": "POST",
  "code": "PUB_VALIDATION_ERROR",
  "message": "Validation failed",
  "userMessage": "Dados da requisição inválidos",
  "details": {
    "errors": [
      "value must not be less than 0.01",
      "details.keyType must be one of: EMAIL, PHONE, DOCUMENT, RANDOM"
    ]
  }
}

Causas comunes:

value menor que 0.01 o con mas de 2 decimales
details.keyType con valor invalido
details.key no corresponde al formato del keyType
details.document vacio o formato incorrecto

El saldo disponible es menor que el monto de la transaccion + comision.

{
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "path": "/api/pix/cash-out",
  "method": "POST",
  "code": "PIX_INSUFFICIENT_BALANCE",
  "message": "Insufficient balance",
  "userMessage": "Saldo insuficiente para realizar esta operação"
}

Otros errores de negocio en la misma categoria:

Codigo	Descripcion
`PIX_INSUFFICIENT_BALANCE`	Saldo insuficiente (monto + comision)
`PIX_TRANSACTION_LIMIT_EXCEEDED`	El monto excede el limite por transaccion
`PIX_DAILY_LIMIT_EXCEEDED`	El acumulado del dia excede el limite diario
`PIX_NIGHT_LIMIT_EXCEEDED`	Operacion nocturna excede el limite reducido (20h-6h)
`PIX_INVALID_AMOUNT`	Monto menor que 0.01 o con mas de 2 decimales
`PIX_INVALID_PIX_KEY`	Formato de la clave no corresponde al `keyType` informado

El externalId ya fue utilizado para esta cuenta. Use un nuevo identificador.

{
  "statusCode": 409,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "path": "/api/pix/cash-out",
  "method": "POST",
  "code": "PIX_DUPLICATE_EXTERNAL_ID",
  "message": "External ID already exists",
  "userMessage": "Esta transação já existe no sistema"
}

El externalId funciona como clave de idempotencia. Si envia la misma solicitud dos veces con el mismo externalId, la segunda llamada retornara 409 -- garantizando que el pago no se duplique.

Cuando el banco liquidante rechaza la operacion despues de la creacion de la transaccion, el estado cambia a ERROR y los campos errorCode/errorMessage se envian en el webhook de Cash-Out:

`errorCode`	Descripcion	?Reintentable?
`TAX_ID_MISMATCH`	El `details.document` no corresponde al titular de la clave PIX	No -- corrija el CPF/CNPJ
`INVALID_TAX_ID`	CPF/CNPJ algoritmicamente invalido	No -- corrija el documento
`BLOCKED_ACCOUNT`	Cuenta de destino bloqueada judicialmente	No
`ACCOUNT_CLOSED`	Cuenta de destino cerrada	No
`ORDER_REJECTED`	Banco de destino rechazo la operacion	No
`PAYMENT_EXPIRED`	Transaccion expiro antes de ser procesada	Si -- reenvie
`SETTLEMENT_TIMEOUT`	Banco de destino no respondio a tiempo	Si -- reenvie

Ejemplo de payload del webhook con error:

{
  "type": "CASH_OUT",
  "data": {
    "transactionId": "8b3b85ac-394c-4144-9bcb-c5d12de3fa56",
    "externalId": "PAG-2024-0001",
    "status": "ERROR",
    "errorCode": "TAX_ID_MISMATCH",
    "errorMessage": "O documento informado não corresponde ao titular da chave PIX"
  }
}

Consulte la guia de integracion PIX Cash-Out para ejemplos de codigo, validacion local de claves y buenas practicas.