Generar cobro PIX (Cash-In)

POST /api/pix/cash-in

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

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

Genera un codigo QR dinamico para recibir pagos mediante PIX. El cobro se crea con estado PENDING y, cuando se paga, el estado cambia a CONFIRMED via webhook.

Autenticacion

Requiere un Bearer token en el header Authorization.

¿Probando en sandbox? Agregue el header X-Sandbox-Scenario para simular escenarios de error y retraso en los webhooks. Consulte la guía de Pruebas en Sandbox para la lista completa de escenarios.

Request Body

Campo	Tipo	Obligatorio	Descripcion
`transaction`	object	Si	Datos de la transaccion
`transaction.value`	number	Si	Monto en reales (hasta 2 decimales). Minimo: `0.01`
`transaction.description`	string	Si	Descripcion de la transaccion (max 140 caracteres)
`transaction.externalId`	string	Si	ID externo de la transaccion (identificador unico por cuenta)
`transaction.expirationTime`	number	No	Tiempo de expiracion en segundos (min 30s, max 7 dias). Por defecto: `86400` (24h). Algunos proveedores exigen minimos mayores — ver Limites por proveedor
`transaction.generateQrCode`	boolean	No	Si es `true`, retorna el codigo QR en Base64. Por defecto: `false`
`payer`	object	Si	Datos del pagador (informativos -- no se envian al PSP)
`payer.fullName`	string	Si	Nombre del pagador. Informativo -- puede usar un valor fijo (ej: razon social de la cuenta). Max: 100 caracteres
`payer.document`	string	Si	CPF (11 digitos) o CNPJ (14 digitos). Informativo -- puede usar el CNPJ del propio integrador
`additionalInfo`	object	No	Informacion adicional (clave-valor string:string, maximo 10 claves)
`splits`	array	No	Lista de destinatarios para split del pago (maximo 10). Cuando el PIX-IN es confirmado, el monto se divide automaticamente. La suma de los splits no puede exceder el monto de la transaccion
`splits[].pixKey`	string	Si	Clave PIX del destinatario del split (max 255 caracteres)
`splits[].pixKeyType`	string	Si	Tipo de clave: `EMAIL`, `PHONE`, `CPF`, `CNPJ`, `RANDOM`
`splits[].name`	string	Si	Nombre del destinatario (max 255 caracteres)
`splits[].document`	string	Si	CPF (11 digitos) o CNPJ (14 digitos), solo numeros
`splits[].type`	string	Si	Tipo del split: `FIXED` (monto fijo en reales) o `PERCENTAGE` (porcentaje sobre el monto bruto)
`splits[].value`	number	Si	Valor del split. `FIXED`: reales con hasta 2 decimales (ej: `10.50`). `PERCENTAGE`: porcentaje directo (ej: `10` = 10%). Minimo: `0.01`
`splits[].immediate`	boolean	No	Si es `true`, el split se ejecuta inmediatamente despues del PIX-IN. Por defecto: `false` (sigue la frecuencia de la cuenta)

Ejemplos de Request

Escenario minimo: genera un cobro sin codigo QR, sin datos adicionales.

{
  "transaction": {
    "value": 49.90,
    "description": "Assinatura mensal - Plano Básico",
    "externalId": "SUB-2024-001"
  },
  "payer": {
    "fullName": "Maria Silva",
    "document": "12345678901"
  }
}

Escenario mas comun: genera un codigo QR para mostrar al pagador, con metadatos del pedido y expiracion de 1 hora.

{
  "transaction": {
    "value": 189.90,
    "description": "Pedido #8842 - Loja Virtual",
    "externalId": "ORD-8842-20240115",
    "expirationTime": 3600,
    "generateQrCode": true
  },
  "payer": {
    "fullName": "Carlos Oliveira",
    "document": "98765432000188"
  },
  "additionalInfo": {
    "orderId": "8842",
    "storeName": "Tech Solutions",
    "customerEmail": "carlos@email.com"
  }
}

Cobro de alto valor (B2B) con expiracion larga (7 dias) y CNPJ como pagador.

{
  "transaction": {
    "value": 15750.00,
    "description": "NF 2024/0042 - Consultoria em TI",
    "externalId": "NF-2024-0042",
    "expirationTime": 604800,
    "generateQrCode": true
  },
  "payer": {
    "fullName": "Empresa ABC Ltda",
    "document": "11222333000144"
  },
  "additionalInfo": {
    "nfNumber": "2024/0042",
    "contractId": "CTR-789"
  }
}

Marketplace: pago de R$ 200 dividido entre vendedor (70%), plataforma (20%) y repartidor (R$ 10 fijo). Los splits se ejecutaran segun la frecuencia configurada en la cuenta.

{
  "transaction": {
    "value": 200.00,
    "description": "Pedido #12345 - Marketplace",
    "externalId": "MKT-12345",
    "generateQrCode": true
  },
  "payer": {
    "fullName": "João Pereira",
    "document": "12345678901"
  },
  "splits": [
    {
      "pixKey": "vendedor@email.com",
      "pixKeyType": "EMAIL",
      "name": "Loja do João",
      "document": "98765432000188",
      "type": "PERCENTAGE",
      "value": 70
    },
    {
      "pixKey": "11222333000144",
      "pixKeyType": "CNPJ",
      "name": "Marketplace Ltda",
      "document": "11222333000144",
      "type": "PERCENTAGE",
      "value": 20
    },
    {
      "pixKey": "11999887766",
      "pixKeyType": "PHONE",
      "name": "Entregador Silva",
      "document": "98765432100",
      "type": "FIXED",
      "value": 10.00
    }
  ]
}

Resultado despues de la confirmacion del pago:

Destinatario	Tipo	Calculo	Monto
Loja do Joao	70%	R$ 200 x 70%	R$ 140,00
Marketplace Ltda	20%	R$ 200 x 20%	R$ 40,00
Entregador Silva	Fijo	--	R$ 10,00
Saldo remanente	--	R$ 200 - R$ 190	R$ 10,00

Split unico con ejecucion inmediata: tan pronto como se confirme el pago, la transferencia al prestador se realiza automaticamente (sin esperar la frecuencia de la cuenta).

{
  "transaction": {
    "value": 350.00,
    "description": "Serviço de consultoria - Projeto Alpha",
    "externalId": "SVC-ALPHA-001",
    "generateQrCode": true
  },
  "payer": {
    "fullName": "Empresa XYZ S.A.",
    "document": "55666777000199"
  },
  "splits": [
    {
      "pixKey": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
      "pixKeyType": "RANDOM",
      "name": "Consultor Freelancer",
      "document": "12345678901",
      "type": "PERCENTAGE",
      "value": 80,
      "immediate": true
    }
  ]
}

Consulte la guia de Split de Pagos para detalles completos sobre tipos, calculos, frecuencias y ejemplos avanzados.

Ejemplos de Código

cURL

curl -X POST "https://api.avista.global/api/pix/cash-in" \
  -H "Authorization: Bearer $AVISTA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "transaction": {
    "value": 49.90,
    "description": "Assinatura mensal - Plano Básico",
    "externalId": "SUB-2024-001"
  },
  "payer": {
    "fullName": "Maria Silva",
    "document": "12345678901"
  }
}'

const axios = require('axios');

const response = await axios.post('https://api.avista.global/api/pix/cash-in',
  {
  "transaction": {
    "value": 49.90,
    "description": "Assinatura mensal - Plano Básico",
    "externalId": "SUB-2024-001"
  },
  "payer": {
    "fullName": "Maria Silva",
    "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-in',
    headers={
        'Authorization': f'Bearer {os.environ["AVISTA_TOKEN"]}',
        'Content-Type': 'application/json',
    },
    json={
  "transaction": {
    "value": 49.90,
    "description": "Assinatura mensal - Plano Básico",
    "externalId": "SUB-2024-001"
  },
  "payer": {
    "fullName": "Maria Silva",
    "document": "12345678901"
  }
},
)
print(response.json())

$ch = curl_init('https://api.avista.global/api/pix/cash-in');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('AVISTA_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{
  "transaction": {
    "value": 49.90,
    "description": "Assinatura mensal - Plano Básico",
    "externalId": "SUB-2024-001"
  },
  "payer": {
    "fullName": "Maria Silva",
    "document": "12345678901"
  }
}',
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

String body = """
    {
      "transaction": {
        "value": 49.90,
        "description": "Assinatura mensal - Plano Básico",
        "externalId": "SUB-2024-001"
      },
      "payer": {
        "fullName": "Maria Silva",
        "document": "12345678901"
      }
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.avista.global/api/pix/cash-in"))
    .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 unico de la transaccion generada
`correlationId`	string	ID de correlacion de la transaccion (UUID)
`externalId`	string	ID externo de la transaccion (mismo valor del input)
`status`	string	Estado de la transaccion: `PENDING` (esperando pago)
`pixCode`	string	Codigo Pix en formato estandar EMV (copiar y pegar)
`generateTime`	string	Fecha y hora de generacion del Pix (ISO 8601)
`expirationDate`	string	Fecha y hora de expiracion del Pix (ISO 8601)
`qrCodeImage`	string	Codigo QR en Base64 (solo cuando `generateQrCode=true`)

{
  "transactionId": "7845",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "ORD-8842-20240115",
  "status": "PENDING",
  "pixCode": "00020126580014br.gov.bcb.pix0136550e8400-e29b-41d4-a716-4466554400005204000053039865802BR5916Tech Solutions Ltda6009SAO PAULO62070503***63041D3D",
  "generateTime": "2024-01-15T10:30:00.000Z",
  "expirationDate": "2024-01-15T11:30:00.000Z",
  "qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5fY51..."
}

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:27:36.608Z",
  "path": "/public/pix/cash-in",
  "method": "POST",
  "code": "HTTP_ERROR",
  "message": [
    "transaction.value must be at least 0.01",
    "transaction.value must have a maximum of 2 decimal places",
    "transaction.description should not be empty",
    "transaction.description must be a string"
  ],
  "userMessage": "Requisição inválida. Verifique os dados enviados.",
  "errorId": "31b5dc36b86c598e51a2a5389a37060d",
  "error": "Bad Request"
}

Causas comunes:

transaction.value menor que 0.01 o con mas de 2 decimales
transaction.description o transaction.externalId vacios
expirationTime menor que 30 (segundos) o mayor que 604800 (7 dias)
expirationTime menor que el minimo del proveedor de la cuenta (errorCode PROVIDER_EXPIRATION_BELOW_MINIMUM) — ver Limites por proveedor
Suma de los splits excede el monto de la transaccion

Token ausente, expirado o invalido.

{
  "statusCode": 401,
  "timestamp": "2026-04-10T15:30:00.000Z",
  "path": "/public/pix/cash-in",
  "method": "POST",
  "code": "HTTP_ERROR",
  "message": "Unauthorized",
  "userMessage": "Token de autenticação inválido ou expirado.",
  "errorId": "a9f3e2b1c4d5678e90123456abcdef01",
  "error": "Unauthorized"
}

Fallo al comunicarse con el proveedor PIX. Intente nuevamente.

{
  "statusCode": 500,
  "timestamp": "2026-04-10T15:30:00.000Z",
  "path": "/public/pix/cash-in",
  "method": "POST",
  "code": "HTTP_ERROR",
  "message": "Internal Server Error",
  "userMessage": "Erro ao gerar cobrança PIX. Tente novamente em alguns instantes.",
  "errorId": "c7d8e9f0a1b2345678901234abcdef56",
  "error": "Internal Server Error"
}