Realizar pago PIX (Cash-Out)

POST /api/pix/cash-out

POST https://api.avista.global/api/pix/cash-out

Requiere un Bearer token en el header Authorization. Vea Generar Token para obtener uno.

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.

¿Probando en sandbox? Agregue el header X-Sandbox-Scenario para simular escenarios de error como saldo insuficiente, clave PIX inválida y documento divergente. Consulte la guía de Pruebas en Sandbox.

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"
  }
}

Ejemplos de Código

cURL

curl -X POST "https://api.avista.global/api/pix/cash-out" \
  -H "Authorization: Bearer $AVISTA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678901",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678901"
  }
}'

const axios = require('axios');

const response = await axios.post('https://api.avista.global/api/pix/cash-out',
  {
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678901",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678901"
  }
},
  {
    headers: {
      'Authorization': `Bearer ${process.env.AVISTA_TOKEN}`,
      'Content-Type': 'application/json',
    },
  }
);
console.log(response.data);

import os, requests

response = requests.post(
    'https://api.avista.global/api/pix/cash-out',
    headers={
        'Authorization': f'Bearer {os.environ["AVISTA_TOKEN"]}',
        'Content-Type': 'application/json',
    },
    json={
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678901",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678901"
  }
},
)
print(response.json())

$ch = curl_init('https://api.avista.global/api/pix/cash-out');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('AVISTA_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678901",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678901"
  }
}',
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

String body = """
    {
      "value": 150.00,
      "externalId": "PAG-2024-0001",
      "description": "Pagamento freelancer - Janeiro/2024",
      "details": {
        "key": "12345678901",
        "keyType": "DOCUMENT",
        "name": "Ana Costa",
        "document": "12345678901"
      }
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.avista.global/api/pix/cash-out"))
    .header("Authorization", "Bearer " + System.getenv("AVISTA_TOKEN"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

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. El campo message es un array con los mensajes de cada campo invalido.

{
  "statusCode": 400,
  "timestamp": "2026-04-10T15:30:34.560Z",
  "path": "/public/pix/cash-out",
  "method": "POST",
  "code": "HTTP_ERROR",
  "message": [
    "value must be at least 0.01",
    "details.keyType must be one of: EMAIL, PHONE, DOCUMENT, RANDOM"
  ],
  "userMessage": "Requisição inválida. Verifique os dados enviados.",
  "errorId": "a1b2c3d4e5f6789012345678abcdef01",
  "error": "Bad Request"
}

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": "2026-04-10T15:30:34.560Z",
  "path": "/public/pix/cash-out",
  "method": "POST",
  "code": "PIX_INSUFFICIENT_BALANCE",
  "message": "Saldo insuficiente para realizar esta operação.",
  "userMessage": "Requisição inválida. Verifique os dados enviados.",
  "errorId": "b2c3d4e5f6a7890123456789abcdef02",
  "errorCode": "PIX_INSUFFICIENT_BALANCE"
}

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. Retorna status 400 (no 409) con details conteniendo el ID de la transaccion existente.

{
  "statusCode": 400,
  "timestamp": "2026-04-10T15:30:34.560Z",
  "path": "/public/pix/cash-out",
  "method": "POST",
  "code": "PIX_DUPLICATE_EXTERNAL_ID",
  "message": "Esta transação já existe no sistema.",
  "userMessage": "Requisição inválida. Verifique os dados enviados.",
  "errorId": "c57c14ee10aabd82e40dae9b940706e0",
  "errorCode": "PIX_DUPLICATE_EXTERNAL_ID",
  "details": {
    "externalId": "external-teste-002",
    "existingTransactionId": 466208
  }
}

El externalId funciona como clave de idempotencia. Si envia la misma solicitud dos veces con el mismo externalId, la segunda llamada retornara error -- garantizando que el pago no se duplique. El campo details.existingTransactionId permite localizar la transaccion original.

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:

{
  "event": "CashOut",
  "status": "ERROR",
  "transactionType": "PIX",
  "movementType": "DEBIT",
  "transactionId": "466208",
  "externalId": "PAG-2024-0001",
  "endToEndId": "E17758345EYNKPHCJKMS",
  "pixKey": "12345678901",
  "feeAmount": 0.07,
  "originalAmount": 1,
  "finalAmount": 1.07,
  "processingDate": "2026-04-10T15:22:49.970Z",
  "errorCode": "TAX_ID_MISMATCH",
  "errorMessage": "O documento informado não corresponde ao titular da chave PIX",
  "counterpart": {
    "name": "João Silva",
    "document": "12345678901",
    "bank": {
      "bankISPB": "13140088",
      "bankName": "ACESSO SOLUÇÕES DE PAGAMENTO S.A.",
      "bankCode": "332",
      "accountBranch": null,
      "accountNumber": null
    }
  },
  "metadata": {}
}

Cuando status es CONFIRMED, los campos errorCode y errorMessage son null. Cuando status es ERROR, indican el motivo del rechazo.

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

Realizar pago PIX (Cash-Out)

En esta página