Skip to main content

PIX IN – Criar Transação

Esta API permite criar transações PIX para vendas de produtos físicos ou digitais. O sistema gera automaticamente um QR Code PIX e gerencia todo o ciclo de vida da transação.

⚠️ Importante: Valores em Centavos

Todos os valores monetários (amount, unitPrice) devem ser enviados em centavos como números inteiros.

Exemplos:

  • R$ 10,00 = 1000
  • R$ 99,99 = 9999
  • R$ 100,50 = 10050

❌ NÃO use: 99.99, 10.00, valores negativos ✅ USE: 9999, 1000 (sempre inteiros)

Dados Obrigatórios​

  • amount: Valor total da transação em centavos (ex: R$ 100,00 = 10000)
  • paymentMethod: "PIX"

Dados Opcionais​

  • webhookUrl: URL HTTPS para notificações
  • externalCode: Seu código de referência
  • idempotencyKey: Chave para evitar duplicatas
  • metadata: Dados adicionais em formato JSON

isInfoProduct

  • true: para produtos digitais (default)
  • false: para produtos físicos que necessitam de entrega

Cliente (customer)

  • ip: IP do cliente (opcional)
  • name: Nome completo
  • email: E-mail válido
  • document: CPF ou CNPJ
  • mobilePhone: Celular de contato (opcional)
  • landline: Telefone Físico de contato (opcional)

Vendedor (seller)

  • name: Nome completo
  • document: CPF ou CNPJ

Endereço (address) - Obrigatório para produtos físicos

  • zipCode: CEP (formato brasileiro)
  • street: Nome da rua
  • number: Número (string)
  • complement: Complemento/Descrição (opcional)
  • neighborhood: Bairro
  • city: Cidade
  • state: Estado
  • country: País

Itens do Pedido (items) - Os nomes dos produtos devem ser unicos

  • title: Nome do produto
  • description: Descrição (opcional)
  • unitPrice: Preço unitário em centavos (ex: R$ 99,99 = 9999)
  • quantity: Quantidade

Configuração PIX (pix)

  • expirationSeconds: Tempo de expiração em segundos (60 a 86400, default: 1800)

Como Testar​

Autenticação

  1. Abra o Swagger e clique em "Authorize"
  2. Insira suas credenciais:
    • Authorization: Seu bearer token

Executar Teste

  1. Selecione o endpoint POST /transaction
  2. Clique em "Try it out"
  3. Ajuste o corpo da requisição conforme necessário
  4. Clique em "Execute"

Verificar Resposta

  • Verifique o status e corpo da resposta
  • Em caso de sucesso, você receberá o QR Code PIX

✅ Exemplo de Resposta Bem-Sucedida​

{
  "id": "553e8400-e29b-41d4-a716-436251480000",
  "externalCode": "PEDIDO-123",
  "amount": 1000,
  "status": "PIX_QRCODE_GENERATED",
  "pix": {
    "uri": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000",
    "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "expirationDate": "2025-10-31T14:18:03.090Z"
  }
}

❌ Possíveis Erros​

  • 401 Unauthorized: Credenciais inválidas
  • 403 Forbidden: Sem permissão/autorização
  • 422 Unprocessable Entity: Dados inválidos ou faltando e validações
  • 429 Too Many Requests: Muitas requisições
  • 500 Internal Server Error: Erro no processamento (Contate o Suporte)

📚 Recursos Relacionados​

  1. Visão Geral - Introdução à API
  2. Webhooks - Notificações automáticas
  3. Consultar Transação - Verificar status de uma transação