Criar Cobrança PIX

Parâmetros do Request

Resposta

A API retorna os dados da cobrança criada, incluindo o QR Code em texto e imagem Base64:

Campos da Resposta

• chargeId: ID único da cobrança no ActivePayments (use para consultas)
• externalId: ID da transação no gateway de pagamento
• amount: Valor bruto da cobrança (string com decimal — ex: "150.50")
• netAmount: Valor líquido após taxas (string)
• fee: Taxa cobrada pela transação (string)
• status: Status atual em uppercase (PENDING, RELEASE, CANCELLED, FAILED, REFUNDED, CHARGEDBACK, DISPUTED)
• pix.qrCode: Código PIX copia-e-cola (BR Code) — sempre presente
• pix.qrCodeBase64: Imagem do QR Code em Base64 (PNG). Pode vir como string vazia ("") dependendo do gateway — nesse caso, gere a imagem do seu lado a partir do pix.qrCode (qualquer lib geradora de QR Code aceita o texto BR Code)
• pix.expiresAt: Data/hora de expiração do QR Code (ISO 8601)
• externalReference: Eco do externalReference enviado na requisição

Códigos de Erro

Split de Pagamentos (Subcontas)

O campo opcional split divide o valor líquido da venda (após as taxas da plataforma) entre subcontas cadastradas e aprovadas no painel. O residual fica com a conta principal. Veja o guia completo em Split de Pagamentos.

{
  "amount": 150.50,
  "customerName": "João da Silva",
  "customerCpf": "12345678901",
  "externalReference": "ORDER-12345",
  "split": [
    { "subAccountId": "a1b2c3d4-...", "type": "PERCENT", "value": 30 },
    { "subAccountId": "e5f6g7h8-...", "type": "FIXED", "value": 10.00 }
  ],
  "splitFeePayer": "OWNER"
}

Regras do split

• subAccountId: ID da subconta — precisa pertencer à sua conta, estar aprovada (KYC) e ativa
• type: PERCENT (percentual — veja a base de cálculo abaixo) ou FIXED (valor em reais)
• value: percentual (0.01 a 100) ou valor fixo, conforme o tipo
• Máximo de 20 subcontas por cobrança, sem duplicatas
• A soma dos percentuais não pode exceder 100%, e o total do split não pode exceder o valor líquido
• Cobranças sem o campo split funcionam exatamente como antes — o campo é 100% opcional

Quem absorve a taxa (splitFeePayer)

Por padrão, o percentual incide sobre o valor líquido — na prática, a taxa da plataforma é rateada entre todos. Com splitFeePayer: "OWNER", o percentual incide sobre o valor bruto da venda e a taxa sai inteira do residual da conta principal. Exemplo com venda de R$ 15,00, taxa de R$ 0,75 e split de 85%:

• Itens FIXED não são afetados — são sempre o valor absoluto informado
• O teto continua sendo o valor líquido: no modo OWNER, a soma das partes + taxa não pode passar do valor da venda (com taxa de 5%, os percentuais somados ficam limitados a ~95%) — acima disso a criação retorna 400
• O campo vale por cobrança e vale também para assinaturas (Pix Automático), replicando em cada ciclo

Quando a cobrança tem split, a resposta (e o webhook charge.paid) inclui o array split com o valor calculado de cada parte:

"split": [
  {
    "subAccountId": "a1b2c3d4-...",
    "type": "PERCENT",
    "value": 30,
    "amount": 43.80
  }
]

Exibindo o QR Code

Você pode exibir o QR Code de duas formas:

• Texto Copia-e-Cola (recomendado): Exiba o qrCode (BR Code) para o cliente copiar e colar no app do banco, e gere a imagem do QR no seu frontend com qualquer biblioteca (ex: qrcode no Node, qrcode.react no React)
• Imagem Base64: Quando o gateway fornece a imagem, ela vem no campo qrCodeBase64 e pode ser usada direto no atributo src de uma <img>. Como esse campo pode vir vazio, sempre tenha um fallback gerando a imagem a partir do qrCode.

<!-- Fallback: usa Base64 quando disponível, senão gera com lib local -->
{data.pix.qrCodeBase64
  ? <img src={data.pix.qrCodeBase64} alt="QR Code PIX" />
  : <QRCode value={data.pix.qrCode} size={300} />}

<!-- Botão para copiar o código -->
<button onClick={() => navigator.clipboard.writeText(data.pix.qrCode)}>
  Copiar código PIX
</button>