Gerar cobrança PIX (Cash-In)

POST /api/pix/cash-in

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

Requer um Bearer token no header Authorization. Veja Gerar Token para obter um.

Gera um QR Code dinâmico para recebimento via PIX. A cobrança é criada com status PENDING e, quando paga, o status muda para CONFIRMED via webhook.

Autenticação

Requer token Bearer no header Authorization.

Testando em sandbox? Adicione o header X-Sandbox-Scenario para simular cenários de erro e delay nos webhooks. Veja o guia de Teste em Sandbox para a lista completa de cenários.

Request Body

Campo	Tipo	Obrigatório	Descrição
`transaction`	object	Sim	Dados da transação
`transaction.value`	number	Sim	Valor em reais (até 2 casas decimais). Mínimo: `0.01`
`transaction.description`	string	Sim	Descrição da transação (máx 140 chars)
`transaction.externalId`	string	Sim	ID externo da transação (identificador único por conta)
`transaction.expirationTime`	number	Não	Tempo de expiração em segundos (min 30s, max 7 dias). Default: `86400` (24h). Alguns provedores exigem mínimos maiores — ver Limites por provedor
`transaction.generateQrCode`	boolean	Não	Se `true`, retorna o QR Code em Base64. Default: `false`
`payer`	object	Sim	Dados do pagador (informativos — não enviados ao PSP)
`payer.fullName`	string	Sim	Nome do pagador. Informativo — pode usar valor fixo (ex: razão social da conta). Máx: 100 chars
`payer.document`	string	Sim	CPF (11 dígitos) ou CNPJ (14 dígitos). Informativo — pode usar o CNPJ do próprio integrador
`additionalInfo`	object	Não	Informações adicionais (chave-valor string:string, máximo 10 chaves)
`splits`	array	Não	Lista de destinatários para split do pagamento (máximo 10). Quando o PIX-IN é confirmado, o valor é dividido automaticamente. A soma dos splits não pode exceder o valor da transação
`splits[].pixKey`	string	Sim	Chave PIX do destinatário do split (máx 255 chars)
`splits[].pixKeyType`	string	Sim	Tipo da chave: `EMAIL`, `PHONE`, `CPF`, `CNPJ`, `RANDOM`
`splits[].name`	string	Sim	Nome do destinatário (máx 255 chars)
`splits[].document`	string	Sim	CPF (11 dígitos) ou CNPJ (14 dígitos), apenas números
`splits[].type`	string	Sim	Tipo do split: `FIXED` (valor fixo em reais) ou `PERCENTAGE` (percentual sobre valor bruto)
`splits[].value`	number	Sim	Valor do split. `FIXED`: reais com até 2 casas (ex: `10.50`). `PERCENTAGE`: percentual direto (ex: `10` = 10%). Mínimo: `0.01`
`splits[].immediate`	boolean	Não	Se `true`, split executado imediatamente após o PIX-IN. Default: `false` (segue frequência da conta)

Exemplos de Request

Cenário mínimo: gera uma cobrança sem QR Code, sem dados adicionais.

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

Cenário mais comum: gera QR Code para exibir ao pagador, com metadados do pedido e expiração 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"
  }
}

Cobrança de alto valor (B2B) com expiração longa (7 dias) e 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: pagamento de R$ 200 dividido entre vendedor (70%), plataforma (20%) e entregador (R$ 10 fixo). Os splits serão executados conforme a frequência configurada na conta.

{
  "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 após pagamento confirmado:

Destinatário	Tipo	Cálculo	Valor
Loja do João	70%	R$ 200 × 70%	R$ 140,00
Marketplace Ltda	20%	R$ 200 × 20%	R$ 40,00
Entregador Silva	Fixo	—	R$ 10,00
Saldo remanescente	—	R$ 200 - R$ 190	R$ 10,00

Split único com execução imediata: assim que o pagamento for confirmado, o repasse para o prestador é feito automaticamente (sem aguardar a frequência da conta).

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

Veja o guia de Split de Pagamentos para detalhes completos sobre tipos, cálculos, frequências e exemplos avançados.

Exemplos 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	Descrição
`transactionId`	string	Identificador único da transação gerada
`correlationId`	string	ID de correlação da transação (UUID)
`externalId`	string	ID externo da transação (mesmo valor do input)
`status`	string	Status da transação: `PENDING` (aguardando pagamento)
`pixCode`	string	Código Pix no formato padrão EMV (copia e cola)
`generateTime`	string	Data e hora de geração do Pix (ISO 8601)
`expirationDate`	string	Data e hora de expiração do Pix (ISO 8601)
`qrCodeImage`	string	QR Code em Base64 (apenas quando `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..."
}

Erros

Retornado quando o body não atende as validações. O campo message é um array com as mensagens de cada campo inválido.

{
  "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 comuns:

transaction.value menor que 0.01 ou com mais de 2 casas decimais
transaction.description ou transaction.externalId vazios
expirationTime menor que 30 (segundos) ou maior que 604800 (7 dias)
expirationTime menor que o mínimo do provedor da conta (errorCode PROVIDER_EXPIRATION_BELOW_MINIMUM) — ver Limites por provedor
Soma dos splits excede o valor da transação

Token ausente, expirado ou inválido.

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

Falha ao comunicar com o provedor PIX. Tente novamente.

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