PIX Cash-In (Recebimento)

Visão Geral

O endpoint PIX Cash-In permite que você gere cobranças PIX dinâmicas para receber pagamentos. Cada cobrança gera um QR Code único e um código PIX (Pix Copia e Cola) que seus clientes podem usar para efetuar o pagamento.

Este endpoint requer um token Bearer válido. Verifique a documentação de autenticação para mais detalhes.

Características

Geração de QR Code dinâmico
Código PIX no formato EMV (Copia e Cola)
Configuração de prazo de expiração (5 minutos a 7 dias)
Identificação única por externalId
Informações adicionais personalizáveis
Validação automática de CPF/CNPJ

Endpoint

POST /api/pix/cash-in

Gera uma nova cobrança PIX.

Headers Obrigatórios

Authorization: Bearer {token}
Content-Type: application/json

Request Body

{
  "transaction": {
    "value": 150.00,
    "description": "Pagamento de pedido #12345",
    "expirationTime": 86400,
    "externalId": "ORDER-12345-20240119",
    "generateQrCode": true
  },
  "payer": {
    "fullName": "Carlos Oliveira",
    "document": "12345678901"
  },
  "additionalInfo": {
    "orderId": "12345",
    "storeName": "Tech Solutions",
    "productCategory": "Eletrônicos"
  }
}

Request

curl -X POST https://api.avista.global/api/pix/cash-in \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "transaction": {
      "value": 150.00,
      "description": "Pagamento de pedido #12345",
      "expirationTime": 86400,
      "externalId": "ORDER-12345-20240119",
      "generateQrCode": true
    },
    "payer": {
      "fullName": "Carlos Oliveira",
      "document": "12345678901"
    },
    "additionalInfo": {
      "orderId": "12345"
    }
  }'

Response (201 Created)

{
  "transactionId": "7845",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "ORDER-12345-20240119",
  "status": "PENDING",
  "pixCode": "00020126580014br.gov.bcb.pix0136550e8400-e29b-41d4-a716-4466554400005204000053039865802BR5916Tech Solutions Ltda6009SAO PAULO62070503***63041D3D",
  "generateTime": "2024-01-19T14:30:00.000Z",
  "expirationDate": "2024-01-20T14:30:00.000Z"
}

Parâmetros da Requisição

Transaction Object

transaction.value

number

required

Valor da transação em reais (BRL). Deve ter no máximo 2 casas decimais.Mínimo: 0.01Exemplo: 150.00

transaction.description

string

required

Descrição da transação que aparecerá no extrato do pagador.Máximo: 140 caracteresExemplo: "Pagamento de pedido #12345"

transaction.expirationTime

number

Tempo de expiração em segundos.Mínimo: 300 (5 minutos)Máximo: 604800 (7 dias)Padrão: 86400 (24 horas)

transaction.externalId

string

required

Identificador único externo da transação. Use para correlacionar com seu sistema.Máximo: 255 caracteresRecomendação: Use um formato que inclua data/hora para garantir unicidadeExemplo: "ORDER-12345-20240119-143000"

transaction.generateQrCode

boolean

Define se deve gerar o QR Code em Base64.Padrão: falseRecomendação: Use true para exibir QR Code ao usuário

Payer Object

payer.fullName

string

required

Nome completo do pagador.Exemplo: "Carlos Oliveira"

payer.document

string

required

CPF ou CNPJ do pagador (apenas números).CPF: 11 dígitosCNPJ: 14 dígitosExemplo: "12345678901" ou "12345678000199"

Additional Info Object

additionalInfo

object

Informações adicionais em formato chave-valor (string:string).Máximo: 10 chavesExemplo:

{
  "orderId": "12345",
  "customerId": "67890",
  "storeName": "Tech Solutions"
}

Estrutura da Resposta

transactionId

string

required

ID interno da transação gerada pela Avista.Exemplo: "7845"

correlationId

string

required

UUID para rastreamento e correlação da transação.Exemplo: "550e8400-e29b-41d4-a716-446655440000"

externalId

string

required

ID externo fornecido na requisição (mesmo valor do input).Exemplo: "ORDER-12345-20240119"

status

string

required

Status atual da transação.Valores possíveis:

PENDING: Aguardando pagamento
CONFIRMED: Pagamento confirmado
ERROR: Erro no processamento

Exemplo: "PENDING"

pixCode

string

required

Código PIX no formato EMV (Pix Copia e Cola).Exemplo: "00020126580014br.gov.bcb.pix..."

generateTime

string

required

Data e hora de geração da cobrança (ISO 8601 UTC).Exemplo: "2024-01-19T14:30:00.000Z"

expirationDate

string

required

Data e hora de expiração da cobrança (ISO 8601 UTC).Exemplo: "2024-01-20T14:30:00.000Z"

Exemplos de Implementação

Node.js / TypeScript

import axios from 'axios';

interface CashInRequest {
  transaction: {
    value: number;
    description: string;
    expirationTime?: number;
    externalId: string;
    generateQrCode?: boolean;
  };
  payer: {
    fullName: string;
    document: string;
  };
  additionalInfo?: Record<string, string>;
}

interface CashInResponse {
  transactionId: string;
  correlationId: string;
  externalId: string;
  status: 'PENDING' | 'CONFIRMED' | 'ERROR';
  pixCode: string;
  generateTime: string;
  expirationDate: string;
}

async function createPixCharge(
  token: string,
  orderId: string,
  amount: number,
  customerName: string,
  customerDocument: string
): Promise<CashInResponse> {
  const payload: CashInRequest = {
    transaction: {
      value: amount,
      description: `Pagamento do pedido ${orderId}`,
      expirationTime: 3600, // 1 hora
      externalId: `ORDER-${orderId}-${Date.now()}`,
      generateQrCode: true
    },
    payer: {
      fullName: customerName,
      document: customerDocument
    },
    additionalInfo: {
      orderId: orderId,
      timestamp: new Date().toISOString()
    }
  };

  try {
    const response = await axios.post<CashInResponse>(
      'https://api.avista.global/api/pix/cash-in',
      payload,
      {
        headers: {
          'Authorization': `Bearer ${token}`,
          'Content-Type': 'application/json'
        }
      }
    );

    console.log('Cobrança PIX gerada com sucesso!');
    console.log(`ID da Transação: ${response.data.transactionId}`);
    console.log(`Código PIX: ${response.data.pixCode}`);
    console.log(`Expira em: ${new Date(response.data.expirationDate).toLocaleString('pt-BR')}`);

    return response.data;
  } catch (error) {
    if (axios.isAxiosError(error)) {
      console.error('Erro ao gerar cobrança:', error.response?.data);
      throw new Error(error.response?.data?.message || 'Erro ao gerar cobrança PIX');
    }
    throw error;
  }
}

// Uso
const token = 'seu_token_aqui';
createPixCharge(token, '12345', 150.00, 'Carlos Oliveira', '12345678901');

Python

import requests
from datetime import datetime, timedelta
from typing import Dict, Optional

def create_pix_charge(
    token: str,
    order_id: str,
    amount: float,
    customer_name: str,
    customer_document: str,
    expiration_hours: int = 1,
    additional_info: Optional[Dict[str, str]] = None
) -> Dict:
    """
    Gera uma cobrança PIX

    Args:
        token: Token Bearer válido
        order_id: ID do pedido
        amount: Valor em reais
        customer_name: Nome do cliente
        customer_document: CPF ou CNPJ (apenas números)
        expiration_hours: Horas até expiração (padrão: 1)
        additional_info: Informações adicionais

    Returns:
        Dados da cobrança gerada
    """
    url = 'https://api.avista.global/api/pix/cash-in'

    payload = {
        'transaction': {
            'value': round(amount, 2),
            'description': f'Pagamento do pedido {order_id}',
            'expirationTime': expiration_hours * 3600,
            'externalId': f'ORDER-{order_id}-{int(datetime.now().timestamp())}',
            'generateQrCode': True
        },
        'payer': {
            'fullName': customer_name,
            'document': customer_document
        },
        'additionalInfo': additional_info or {}
    }

    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    }

    try:
        response = requests.post(url, json=payload, headers=headers)
        response.raise_for_status()

        data = response.json()

        print('Cobrança PIX gerada com sucesso!')
        print(f"ID da Transação: {data['transactionId']}")
        print(f"Código PIX: {data['pixCode']}")
        print(f"Status: {data['status']}")

        expiration = datetime.fromisoformat(data['expirationDate'].replace('Z', '+00:00'))
        print(f"Expira em: {expiration.strftime('%d/%m/%Y %H:%M:%S')}")

        return data

    except requests.exceptions.RequestException as e:
        print(f'Erro ao gerar cobrança: {e}')
        if hasattr(e.response, 'json'):
            print(f'Detalhes: {e.response.json()}')
        raise

# Uso
token = 'seu_token_aqui'
charge = create_pix_charge(
    token=token,
    order_id='12345',
    amount=150.00,
    customer_name='Carlos Oliveira',
    customer_document='12345678901',
    expiration_hours=24,
    additional_info={
        'storeName': 'Tech Solutions',
        'productCategory': 'Eletrônicos'
    }
)

PHP

<?php

function createPixCharge(
    string $token,
    string $orderId,
    float $amount,
    string $customerName,
    string $customerDocument,
    int $expirationHours = 1
): array {
    $url = 'https://api.avista.global/api/pix/cash-in';

    $payload = [
        'transaction' => [
            'value' => round($amount, 2),
            'description' => "Pagamento do pedido $orderId",
            'expirationTime' => $expirationHours * 3600,
            'externalId' => "ORDER-$orderId-" . time(),
            'generateQrCode' => true
        ],
        'payer' => [
            'fullName' => $customerName,
            'document' => $customerDocument
        ],
        'additionalInfo' => [
            'orderId' => $orderId
        ]
    ];

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $token,
        'Content-Type: application/json'
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 201) {
        throw new Exception("Erro ao gerar cobrança: HTTP $httpCode - $response");
    }

    $data = json_decode($response, true);

    echo "Cobrança PIX gerada com sucesso!" . PHP_EOL;
    echo "ID da Transação: {$data['transactionId']}" . PHP_EOL;
    echo "Código PIX: {$data['pixCode']}" . PHP_EOL;
    echo "Status: {$data['status']}" . PHP_EOL;

    return $data;
}

// Uso
$token = 'seu_token_aqui';
$charge = createPixCharge(
    $token,
    '12345',
    150.00,
    'Carlos Oliveira',
    '12345678901',
    24
);

Casos de Uso

1. E-commerce - Checkout com PIX

// Integração em checkout de e-commerce
class PixCheckout {
  constructor(token) {
    this.token = token;
  }

  async generatePayment(order) {
    const charge = await createPixCharge(
      this.token,
      order.id,
      order.total,
      order.customer.name,
      order.customer.document
    );

    // Exibir QR Code na página
    this.displayQrCode(charge.pixCode);

    // Iniciar polling para verificar pagamento
    this.startPaymentPolling(charge.transactionId);

    return charge;
  }

  displayQrCode(pixCode) {
    // Gerar QR Code visual usando biblioteca (ex: qrcode.js)
    QRCode.toCanvas(document.getElementById('qr-canvas'), pixCode, {
      width: 300,
      margin: 2
    });

    // Mostrar também o código Pix Copia e Cola
    document.getElementById('pix-code').textContent = pixCode;
  }

  startPaymentPolling(transactionId) {
    // Verificar status a cada 3 segundos
    const interval = setInterval(async () => {
      const status = await this.checkPaymentStatus(transactionId);

      if (status === 'CONFIRMED') {
        clearInterval(interval);
        this.onPaymentConfirmed();
      }
    }, 3000);

    // Parar após 10 minutos
    setTimeout(() => clearInterval(interval), 10 * 60 * 1000);
  }

  onPaymentConfirmed() {
    // Redirecionar para página de sucesso
    window.location.href = '/payment/success';
  }
}

2. PDV (Ponto de Venda)

class PixPDV:
    """Sistema de PDV com cobrança PIX"""

    def __init__(self, token: str):
        self.token = token

    def process_sale(self, items: list, customer: dict) -> dict:
        """Processar venda e gerar cobrança PIX"""

        # Calcular total
        total = sum(item['price'] * item['quantity'] for item in items)

        # Gerar descrição
        description = self.generate_sale_description(items)

        # Criar cobrança PIX (expira em 15 minutos)
        charge = create_pix_charge(
            token=self.token,
            order_id=self.generate_sale_id(),
            amount=total,
            customer_name=customer['name'],
            customer_document=customer['document'],
            expiration_hours=0.25,  # 15 minutos
            additional_info={
                'items_count': str(len(items)),
                'cashier_id': self.get_cashier_id()
            }
        )

        # Imprimir comprovante com QR Code
        self.print_receipt(charge, items, total)

        return charge

    def generate_sale_description(self, items: list) -> str:
        """Gerar descrição resumida da venda"""
        if len(items) == 1:
            return f"{items[0]['name']}"
        else:
            return f"{len(items)} itens - {items[0]['name']} e mais"

    def print_receipt(self, charge: dict, items: list, total: float):
        """Imprimir comprovante com QR Code"""
        # Implementar impressão térmica ou gerar PDF
        print("\n" + "="*50)
        print("COMPROVANTE DE COBRANÇA PIX")
        print("="*50)
        for item in items:
            print(f"{item['name']}: R$ {item['price']:.2f}")
        print("-"*50)
        print(f"TOTAL: R$ {total:.2f}")
        print(f"\nID da Transação: {charge['transactionId']}")
        print(f"Código PIX:\n{charge['pixCode']}")
        print("="*50 + "\n")

3. SaaS - Cobrança de Assinatura

class SubscriptionBilling {
  constructor(private token: string) {}

  async chargeMonthlySubscription(
    subscriptionId: string,
    userId: string,
    planValue: number
  ) {
    // Buscar dados do usuário
    const user = await this.getUserData(userId);

    // Gerar cobrança com expiração de 3 dias
    const charge = await createPixCharge(
      this.token,
      `SUB-${subscriptionId}-${new Date().getMonth() + 1}`,
      planValue,
      user.name,
      user.document
    );

    // Enviar email com link de pagamento
    await this.sendPaymentEmail(user.email, charge);

    // Agendar lembrete 1 dia antes de expirar
    await this.scheduleReminder(user, charge, 24);

    return charge;
  }

  async sendPaymentEmail(email: string, charge: CashInResponse) {
    // Implementar envio de email
    const paymentLink = `https://app.exemplo.com/payment/${charge.transactionId}`;

    await sendEmail({
      to: email,
      subject: 'Fatura disponível - Pague com PIX',
      html: `
        <h2>Sua fatura está disponível</h2>
        <p>Valor: R$ ${charge.value}</p>
        <p>Vencimento: ${new Date(charge.expirationDate).toLocaleDateString('pt-BR')}</p>
        <p><a href="${paymentLink}">Clique aqui para pagar com PIX</a></p>
      `
    });
  }
}

Monitoramento de Pagamentos

Para ser notificado quando um pagamento for confirmado, você pode:

Webhooks (Recomendado)
Polling

Configure webhooks para receber notificações automáticas quando o status mudar.

// Endpoint webhook em seu servidor
app.post('/webhooks/pix', (req, res) => {
  const { transactionId, status, externalId } = req.body;

  if (status === 'CONFIRMED') {
    // Processar pagamento confirmado
    processPaymentConfirmation(externalId);
  }

  res.sendStatus(200);
});

Consulte periodicamente o status da transação.

async function monitorPayment(transactionId, maxAttempts = 200) {
  for (let i = 0; i < maxAttempts; i++) {
    const status = await checkTransactionStatus(transactionId);

    if (status === 'CONFIRMED') {
      return true;
    }

    // Aguardar 3 segundos antes de tentar novamente
    await new Promise(resolve => setTimeout(resolve, 3000));
  }

  return false; // Timeout
}

Códigos de Resposta

Código	Descrição	Significado
`201`	Cobrança Criada	Cobrança PIX gerada com sucesso
`400`	Dados Inválidos	Verifique os campos obrigatórios e formatos
`401`	Token Inválido	Token não fornecido, expirado ou inválido

Consulte a Referência da API para detalhes completos dos campos de resposta.

Boas Práticas

Use externalId único e rastreável

Inclua informações que facilitem a identificação: ORDER-{orderId}-{timestamp} ou INV-{invoiceId}-{date}

Configure expiração apropriada

E-commerce: 15-30 minutos
Boletos/Faturas: 3-7 dias
PDV: 5-15 minutos

Valide CPF/CNPJ antes de enviar

Implemente validação local para evitar erros 400.

function isValidCPF(cpf: string): boolean {
  cpf = cpf.replace(/\D/g, '');
  if (cpf.length !== 11) return false;
  // Adicionar lógica de validação de CPF
  return true;
}

Trate valores com precisão

Use bibliotecas de precisão decimal para evitar erros de arredondamento.

import Decimal from 'decimal.js';

const total = new Decimal(price).times(quantity).toNumber();

Observações Importantes

Cobranças expiradas não podem ser reativadas. Gere uma nova cobrança se necessário.

Valor mínimo: R$ 0,01
Expiração mínima: 5 minutos (300 segundos)
Expiração máxima: 7 dias (604800 segundos)

Próximos Passos

Estornar Pagamento

Aprenda a estornar pagamentos recebidos

Realizar Pagamento

Envie pagamentos PIX

Introdução

Guias de Integração

Webhooks

Visão Geral

Características

Endpoint

POST /api/pix/cash-in

Headers Obrigatórios

Request Body

Request

Response (201 Created)

Parâmetros da Requisição

Transaction Object

Payer Object

Additional Info Object

Estrutura da Resposta

Exemplos de Implementação

Node.js / TypeScript

Python

PHP

Casos de Uso

1. E-commerce - Checkout com PIX

2. PDV (Ponto de Venda)

3. SaaS - Cobrança de Assinatura

Monitoramento de Pagamentos

Códigos de Resposta

Boas Práticas

Observações Importantes

Próximos Passos

Estornar Pagamento

Realizar Pagamento

Introdução

Guias de Integração

Webhooks

​Visão Geral

​Características

​Endpoint

​POST /api/pix/cash-in

​Headers Obrigatórios

​Request Body

​Request

​Response (201 Created)

​Parâmetros da Requisição

​Transaction Object

​Payer Object

​Additional Info Object

​Estrutura da Resposta

​Exemplos de Implementação

​Node.js / TypeScript

​Python

​PHP

​Casos de Uso

​1. E-commerce - Checkout com PIX

​2. PDV (Ponto de Venda)

​3. SaaS - Cobrança de Assinatura

​Monitoramento de Pagamentos

​Códigos de Resposta

​Boas Práticas

​Observações Importantes

​Próximos Passos

Estornar Pagamento

Realizar Pagamento

Visão Geral

Características

Endpoint

POST /api/pix/cash-in

Headers Obrigatórios

Request Body

Request

Response (201 Created)

Parâmetros da Requisição

Transaction Object

Payer Object

Additional Info Object

Estrutura da Resposta

Exemplos de Implementação

Node.js / TypeScript

Python

PHP

Casos de Uso

1. E-commerce - Checkout com PIX

2. PDV (Ponto de Venda)

3. SaaS - Cobrança de Assinatura

Monitoramento de Pagamentos

Códigos de Resposta

Boas Práticas

Observações Importantes

Próximos Passos