Skip to main content
Este guia mostra como criar QR Codes PIX para receber pagamentos de forma detalhada, com exemplos práticos e todas as opções disponíveis.

Endpoint

POST /api/v1/pix/in/qrcode

Cria um QR Code PIX para recebimento de pagamentos instantâneos. URL Completa:
  • Produção: https://api.vexybank.com/api/v1/pix/in/qrcode

Headers obrigatórios

Content-Type: application/json
Authorization: Bearer <seu_token_bearer>

Parâmetros do corpo

Campos Obrigatórios

Tipo: number
Descrição: Valor em centavos (ex: 10000 = R100,00)Mıˊnimo:1centavo(R 100,00) **Mínimo**: 1 centavo (R 0,01)
Máximo: 1.000.000.000 centavos (R$ 10.000.000,00)
{
  "amountInCents": 29990  // R$ 299,90
}
Tipo: object
Descrição: Dados do cliente pagador
Campos obrigatórios do customer:
  • name (string): Nome completo
  • email (string): Email válido
  • documentType (string): “cpf” ou “cnpj”
  • document (string): Número do documento (apenas números)
{
  "customer": {
    "name": "Cliente Exemplo Silva",
    "email": "[email protected]",
    "documentType": "cpf",
    "document": "11122233344"
  }
}

Campos opcionais

Tipo: string
Descrição: Descrição da transação
Limite: 140 caracteres
Padrão: Vazio
{
  "description": "Pagamento de serviços"
}
Tipo: string
Descrição: URL específica para webhooks desta transação
Formato: URL válida (https://)
{
  "postbackUrl": "https://exemplo.com.br/webhook/pix-in"
}
Tipo: string
Descrição: Telefone do cliente
Formato: Formato com DDD e número
{
  "customer": {
    "phone": "(11) 91234-5678"
  }
}
Tipo: object
Descrição: Endereço de cobrança do cliente
{
  "customer": {
    "billingAddress": {
      "street": "Rua Exemplo",
      "number": "100",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "00000000"
    }
  }
}
Tipo: array
Descrição: Lista de itens da compra
{
  "items": [
    {
      "title": "Produto Exemplo",
      "tangible": true,
      "quantity": 2,
      "amountInCents": 2500
    }
  ]
}

Exemplos práticos

Exemplo Básico - Cobrança Simples

curl --location 'https://api.vexybank.com/api/v1/pix/in/qrcode' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "amountInCents": 5000,
    "description": "Pagamento de serviços",
    "postbackUrl": "https://exemplo.com.br/webhook/pix-in",
    "customer": {
      "name": "Cliente Exemplo",
      "email": "[email protected]",
      "document": "11122233344",
      "documentType": "cpf",
      "phone": "(11) 91234-5678"
    }
  }'

Exemplo Completo - E-commerce

curl --location 'https://api.vexybank.com/api/v1/pix/in/qrcode' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "amountInCents": 25000,
    "description": "Compra na loja online - Pedido #EXEMPLO",
    "postbackUrl": "https://exemplo.com.br/webhook/pix-in",
    "customer": {
      "name": "Cliente Exemplo Silva",
      "email": "[email protected]",
      "document": "11122233344",
      "documentType": "cpf",
      "phone": "(11) 91234-5678"
    },
    "items": [
      {
        "title": "Produto Exemplo A",
        "tangible": true,
        "quantity": 2,
        "amountInCents": 10000
      },
      {
        "title": "Frete Padrão",
        "tangible": false,
        "quantity": 1,
        "amountInCents": 5000
      }
    ],
    "billingAddress": {
      "street": "Rua Exemplo, 100",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "00000-000"
    }
  }'

Exemplo B2B - CNPJ

curl --location 'https://api.vexybank.com/api/v1/pix/in/qrcode' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "amountInCents": 50000,
    "description": "Prestação de serviços - NF Exemplo",
    "postbackUrl": "https://exemplo.com.br/webhook/pix-in",
    "customer": {
      "name": "Empresa Exemplo Ltda",
      "email": "[email protected]",
      "document": "11222333000144",
      "documentType": "cnpj",
      "phone": "(11) 3000-0000"
    }
  }'

Resposta de sucesso (200)

{
  "success": true,
  "message": "Transação criada com sucesso",
  "data": {
    "id": "trx_1a2b3c4d5e6f7g8h9i0j",
    "pix": {
      "emv": "00020126...SEU_CODIGO_EMV_AQUI...6304ABCD",
      "qrCode": "[BASE64_ENCODED_QRCODE_IMAGE]"
    },
    "status": "pending",
    "fees": 0
  }
}

Campos da Resposta

CampoDescrição
idID único da transação
pix.emvCódigo PIX para copiar e colar
pix.qrCodeImagem do QR Code em Base64
statusStatus atual (pending - aguardando pagamento)
feesTaxa cobrada em centavos

Exibindo o QR Code

Exibir Imagem

<div class="pix-payment">
  <h3>Pague com PIX</h3>
  <img src="[BASE64_ENCODED_QRCODE_IMAGE]" 
       alt="QR Code PIX" 
       style="width: 300px; height: 300px;">
  
  <p>Escaneie o QR Code com seu app bancário</p>
</div>

Código para Copiar

<div class="pix-code">
  <p>Ou copie e cole o código PIX:</p>
  <div class="code-container">
    <input type="text" 
           id="pix-code" 
           value="00020126...SEU_CODIGO_EMV_AQUI...6304ABCD" 
           readonly>
    <button onclick="copiarCodigo()">Copiar</button>
  </div>
</div>

<script>
function copiarCodigo() {
  const codigo = document.getElementById('pix-code');
  codigo.select();
  document.execCommand('copy');
  alert('Código PIX copiado!');
}
</script>

Implementações por linguagem

JavaScript/Node.js

class PixPayment {
  constructor(apiKey, apiSecret, baseUrl) {
    this.auth = new VexyBankAuth(apiKey, apiSecret, baseUrl)
  }

  async createQRCode(paymentData) {
    try {
      const response = await this.auth.makeAuthenticatedRequest(
        'POST', 
        '/api/v1/pix/in/qrcode', 
        paymentData
      )
      
      return response.data.data
    } catch (error) {
      throw new Error(`Erro ao criar QR Code: ${error.message}`)
    }
  }

  async createSimplePayment(amount, customerData, description = '') {
    const paymentData = {
      amountInCents: amount,
      description,
      customer: customerData
    }

    return await this.createQRCode(paymentData)
  }
}

// Uso
const pixPayment = new PixPayment(API_KEY, API_SECRET, BASE_URL)

const transaction = await pixPayment.createSimplePayment(
  5000, // R$ 50,00
  {
    name: "Cliente Exemplo",
    email: "[email protected]",
    documentType: "cpf",
    document: "11122233344"
  },
  "Pagamento de produto"
)

console.log('QR Code criado:', transaction.id)

Python

import requests
import json

class PixPayment:
    def __init__(self, auth_instance):
        self.auth = auth_instance

    def create_qr_code(self, payment_data):
        response = self.auth.make_authenticated_request(
            'POST', 
            '/api/v1/pix/in/qrcode', 
            payment_data
        )
        
        if response.status_code == 200:
            return response.json()['data']
        else:
            raise Exception(f"Erro ao criar QR Code: {response.text}")

    def create_simple_payment(self, amount, customer_data, description=''):
        payment_data = {
            'amountInCents': amount,
            'description': description,
            'customer': customer_data
        }
        
        return self.create_qr_code(payment_data)

# Uso
pix_payment = PixPayment(auth_instance)

transaction = pix_payment.create_simple_payment(
    5000,  # R$ 50,00
    {
        'name': 'Cliente Exemplo',
        'email': '[email protected]',
        'documentType': 'cpf',
        'document': '11122233344'
    },
    'Pagamento de produto'
)

print(f'QR Code criado: {transaction["id"]}')

PHP

<?php

class PixPayment {
    private $auth;

    public function __construct($authInstance) {
        $this->auth = $authInstance;
    }

    public function createQRCode($paymentData) {
        $response = $this->auth->makeAuthenticatedRequest(
            'POST', 
            '/api/v1/pix/in/qrcode', 
            $paymentData
        );
        
        $data = json_decode($response, true);
        
        if ($data['success']) {
            return $data['data'];
        } else {
            throw new Exception("Erro ao criar QR Code: " . $response);
        }
    }

    public function createSimplePayment($amount, $customerData, $description = '') {
        $paymentData = [
            'amountInCents' => $amount,
            'description' => $description,
            'customer' => $customerData
        ];
        
        return $this->createQRCode($paymentData);
    }
}

// Uso
$pixPayment = new PixPayment($authInstance);

$transaction = $pixPayment->createSimplePayment(
    5000, // R$ 50,00
    [
        'name' => 'Cliente Exemplo',
        'email' => '[email protected]',
        'documentType' => 'cpf',
        'document' => '11122233344'
    ],
    'Pagamento de produto'
);

echo "QR Code criado: " . $transaction['id'] . "\n";
?>

❌ Tratamento de Erros

Possíveis Erros

CódigoErroCausa ComumSolução
400Dados inválidosCPF/CNPJ inválido, email malformadoValidar dados antes de enviar
401Token inválidoToken expirado ou inválidoRenovar token de autenticação
422Regra de negócioValor muito baixo/altoVerificar limites permitidos
429Rate limitMuitas requisiçõesImplementar retry com delay

Exemplo de Tratamento

async function criarQRCodeComTratamento(dadosPagamento) {
  try {
    return await pixPayment.createQRCode(dadosPagamento)
  } catch (error) {
    if (error.status === 400) {
      // Validar e corrigir dados
      console.error('Dados inválidos:', error.response.data.error)
      throw new Error('Verifique os dados do cliente')
    } else if (error.status === 401) {
      // Renovar token
      await auth.renewToken()
      return await pixPayment.createQRCode(dadosPagamento)
    } else if (error.status === 429) {
      // Rate limit - aguardar
      await new Promise(resolve => setTimeout(resolve, 1000))
      return await pixPayment.createQRCode(dadosPagamento)
    } else {
      throw error
    }
  }
}

Validações recomendadas

Validação de CPF

function validarCPF(cpf) {
  cpf = cpf.replace(/[^\d]/g, '')
  
  if (cpf.length !== 11) return false
  
  // Verificar se todos os dígitos são iguais
  if (/^(\d)\1{10}$/.test(cpf)) return false
  
  // Algoritmo de validação do CPF
  let soma = 0
  for (let i = 0; i < 9; i++) {
    soma += parseInt(cpf.charAt(i)) * (10 - i)
  }
  
  let resto = 11 - (soma % 11)
  if (resto === 10 || resto === 11) resto = 0
  if (resto !== parseInt(cpf.charAt(9))) return false
  
  soma = 0
  for (let i = 0; i < 10; i++) {
    soma += parseInt(cpf.charAt(i)) * (11 - i)
  }
  
  resto = 11 - (soma % 11)
  if (resto === 10 || resto === 11) resto = 0
  if (resto !== parseInt(cpf.charAt(10))) return false
  
  return true
}

Validação de CNPJ

function validarCNPJ(cnpj) {
  cnpj = cnpj.replace(/[^\d]/g, '')
  
  if (cnpj.length !== 14) return false
  
  // Verificar se todos os dígitos são iguais
  if (/^(\d)\1{13}$/.test(cnpj)) return false
  
  // Algoritmo de validação do CNPJ
  let tamanho = cnpj.length - 2
  let numeros = cnpj.substring(0, tamanho)
  let digitos = cnpj.substring(tamanho)
  let soma = 0
  let pos = tamanho - 7
  
  for (let i = tamanho; i >= 1; i--) {
    soma += numeros.charAt(tamanho - i) * pos--
    if (pos < 2) pos = 9
  }
  
  let resultado = soma % 11 < 2 ? 0 : 11 - soma % 11
  if (resultado !== parseInt(digitos.charAt(0))) return false
  
  tamanho = tamanho + 1
  numeros = cnpj.substring(0, tamanho)
  soma = 0
  pos = tamanho - 7
  
  for (let i = tamanho; i >= 1; i--) {
    soma += numeros.charAt(tamanho - i) * pos--
    if (pos < 2) pos = 9
  }
  
  resultado = soma % 11 < 2 ? 0 : 11 - soma % 11
  if (resultado !== parseInt(digitos.charAt(1))) return false
  
  return true
}

Próximos passos