Criar Cobrança PIX

O PIX é um método de pagamento instantâneo que permite receber pagamentos em segundos.

Endpoint

POST /v1/charges

Parâmetros

Exemplo de Requisição

curl -X POST https://api.apexpy.com.br/v1/charges \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "BRL",
    "payment_method": "pix",
    "customer": {
      "name": "João Silva",
      "email": "[email protected]",
      "document": "12345678909",
      "phone": "47999999999",
      "address": {
        "street": "Rua das Flores",
        "number": "123",
        "complement": "Apto 45",
        "neighborhood": "Centro",
        "city": "São Paulo",
        "state": "SP",
        "zipcode": "01234567",
        "country": "BR"
      }
    },
    "items": [
      {
        "name": "Produto Exemplo",
        "quantity": 1,
        "unit_price": 10000  // Em centavos. Deve ser > 0. Se todos os itens tiverem unit_price = 0, o sistema distribui o valor total automaticamente.
      }
    ],
    "metadata": {
      "order_id": "12345",
      "source": "api"
    },
    "store_id": 1,
    "product_id": 5,
    "pix": {
      "expires_in": 1800,
      "description": "Pagamento de exemplo"
    },
    "callback_url": "https://seusite.com.br/webhook/order-12345"
  }'

Exemplo de Resposta

{
  "success": true,
  "data": {
    "id": "ci_123",
    "status": "pending",
    "amount": 10000,
    "currency": "BRL",
    "payment_method": "pix",
    "pix": {
      "txid": "E12345678202511281234567890123456",
      "emv": "00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-4266554400005204000053039865802BR5913FULANO DE TAL6008BRASILIA62070503***63041D3D",
      "qr_code_image_url": "https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=00020126580014br.gov.bcb.pix...",
      "expires_at": "2025-11-28T21:00:00Z"
    },
    "created_at": "2025-11-28T20:30:00Z"
  }
}

Campos da Resposta PIX

Como Usar o Código PIX

Você tem duas opções para exibir o QR Code ao cliente:

Opção 1: Usar a URL da Imagem (se disponível)

Se o campo qr_code_image_url estiver presente na resposta, você pode exibir diretamente:

<img src="{qr_code_image_url}" alt="QR Code PIX" />

Opção 2: Gerar QR Code Localmente (Recomendado)

Use o campo emv para gerar o QR Code no seu frontend usando uma biblioteca JavaScript:

// Exemplo com qrcode.js
import QRCode from 'qrcode';

const qrCodeDataUrl = await QRCode.toDataURL(charge.pix.emv);
// Exibir a imagem gerada

Vantagens de gerar localmente:

• Não depende de serviços externos
• Maior controle sobre o tamanho e estilo do QR Code
• Funciona mesmo se a adquirente não fornecer a URL da imagem

Opção 3: Copiar e Colar

O campo emv contém o código completo que pode ser copiado e colado diretamente no app do banco. Sempre forneça esta opção ao cliente.

Status da Cobrança

• pending - Aguardando pagamento
• paid - Pago
• expired - Expirado
• failed - Falhou

Consultar Status

GET /v1/charges/{id}

Endereço (Opcional)

Para pagamentos PIX, o endereço é opcional. Se não fornecido, o gateway utiliza um sistema de fallback inteligente para atender requisitos de adquirentes que exigem este campo.

Estrutura do Endereço

{
  "customer": {
    "address": {
      "street": "Rua das Flores",      // Obrigatório se address fornecido
      "number": "123",                  // Opcional
      "complement": "Apto 45",          // Opcional
      "neighborhood": "Centro",         // Opcional
      "city": "São Paulo",              // Obrigatório se address fornecido
      "state": "SP",                    // Obrigatório se address fornecido (2 caracteres)
      "zipcode": "01234567",            // Obrigatório se address fornecido (8 dígitos)
      "country": "BR"                   // Opcional (padrão: "BR")
    }
  }
}

Sistema de Fallback

Quando o endereço não é fornecido, o gateway aplica a seguinte prioridade:

1. Shipping fornecido: Usa o endereço de entrega (shipping.address)
2. Endereço do cliente: Usa customer.address
3. Dados básicos do cliente: Tenta extrair city, state, zipcode do objeto customer
4. Valores padrão: Utiliza endereço genérico mínimo (São Paulo, SP)

Nota: O sistema garante compatibilidade com todas as adquirentes, mesmo quando o endereço não é fornecido explicitamente.

Split de Pagamento

Você pode dividir o recebimento entre múltiplos sellers usando o campo split na requisição. A taxa de Cash In é calculada uma vez e cobrada do seller principal, enquanto os sellers no split recebem o valor líquido proporcional.

Saiba mais sobre Split de Pagamento →