Vexa Pay

Aprenda como gerar QR Codes PIX para recebimento de pagamentos através da API do Vexa Pay.

Visão Geral

O endpoint de Cash In permite gerar QR Codes PIX dinâmicos para recebimento de pagamentos. Quando um pagador escaneia o QR Code ou utiliza o código PIX copiado, o pagamento é processado automaticamente e creditado na sua conta.

Endpoint: /api/v1/cash-in

Metado: POST

Base URL (Produção): https://api.vexapagamentos.com.br/api/v1

Autenticação

Antes de fazer requisições, você precisa obter um token de acesso OAuth 2.0. Consulte a documentação de autenticação para mais detalhes.

Headers necessários:

Authorization: Bearer <seu-access-token>
Content-Type: application/json

Requisição

/api/v1/cash-in

Gera um QR Code PIX para recebimento de pagamento.

Body (JSON)

Campos obrigatórios:

nome - Nome completo do pagador
cpf - CPF do pagador (apenas números, 11 dígitos)
valor - Valor do pagamento (número decimal)

Campos opcionais:

descricao - Descrição do pagamento

{
  "nome": "João Silva",
  "cpf": "12345678900",
  "valor": 100.50,
  "descricao": "Pagamento de serviço"
}

Exemplo de Requisição (cURL)

curl -X POST https://api.vexapagamentos.com.br/api/v1/cash-in \
  -H "Authorization: Bearer seu-access-token-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "João Silva",
    "cpf": "12345678900",
    "valor": 100.50,
    "descricao": "Pagamento de serviço"
  }'

Resposta

Resposta de Sucesso (200)

{
  "qrCode": "00020126580014br.gov.bcb.pix...",
  "paymentCode": "E18236120202401151730s",
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 100.50,
  "expiresAt": "2024-01-15T18:00:00.000Z"
}

Campos da resposta:

qrCode: String completa do QR Code PIX (EMV) para exibição
paymentCode: Código único do pagamento para rastreamento
transactionId: ID único da transação
amount: Valor do pagamento
expiresAt: Data e hora de expiração do QR Code (ISO 8601)

Importante: O QR Code gerado possui um tempo de expiração. Após a expiração, será necessário gerar um novo QR Code para receber o pagamento.

Validações e Regras

•CPF: Deve conter exatamente 11 dígitos numéricos e ser válido
•Valor: Deve ser maior que zero e seguir o formato decimal (ex: 100.50)
•Nome: Deve conter pelo menos 3 caracteres
•Descrição: Máximo de 140 caracteres (quando informada)

Possíveis Erros

Status 400 - Bad Request

Erros de validação ou formato incorreto:

{
    "message": [
        "cpf must be a valid CPF",
        "valor must be a number conforming to the specified constraints"
    ],
    "error": "Bad Request",
    "statusCode": 400
}

Status 401 - Unauthorized

Erros de autenticação:

{
    "message": "Unauthorized",
    "statusCode": 401
}

Status 500 - Internal Server Error

Erro no processamento do servidor:

{
    "message": "Internal server error",
    "error": "Internal Server Error",
    "statusCode": 500
}

Exemplo de Integração

Exemplo completo em JavaScript/Node.js para gerar um QR Code PIX:

const axios = require('axios');

const BASE_URL = 'https://api.vexapagamentos.com.br/api/v1';

async function generatePixQRCode(accessToken, paymentData) {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/cash-in`,
      {
        nome: paymentData.nome,
        cpf: paymentData.cpf,
        valor: paymentData.valor,
        descricao: paymentData.descricao || ''
      },
      {
        headers: {
          'Authorization': `Bearer ${accessToken}`,
          'Content-Type': 'application/json'
        }
      }
    );

    return {
      success: true,
      data: response.data
    };
  } catch (error: any) {
    return {
      success: false,
      error: error.message || 'Erro desconhecido'
    };
  }
}

// Exemplo de uso
(async () => {
  const accessToken = 'seu-access-token-aqui';
  
  const result = await generatePixQRCode(accessToken, {
    nome: 'João Silva',
    cpf: '12345678900',
    valor: 100.50,
    descricao: 'Pagamento de serviço'
  });

  if (result.success) {
    // QR Code disponível em result.data.qrCode
    // Código do pagamento em result.data.paymentCode
    // Expira em result.data.expiresAt
  } else {
    console.error('Erro ao gerar QR Code:', result.error);
  }
})();

Boas Práticas

✓Valide o CPF antes de enviar a requisição para evitar erros
✓Armazene o paymentCode para rastrear o status do pagamento
✓Implemente verificação do pagamento via webhook cashin.paid (ou polling no extrato)
✓Trate adequadamente a expiração do QR Code e gere um novo quando necessário
✓Use o qrCode para gerar a imagem do QR Code usando bibliotecas apropriadas
✓Implemente tratamento de erros robusto para diferentes cenários