Conceitos fundamentais

Conta

A conta é o guarda-chuva de tudo: chaves, saldo, cobranças e webhooks pertencem a ela. Cada empresa cadastrada tem a sua.

Cobrança (PIX recebido)

Uma cobrança é um pedido de pagamento. Ela nasce pending, vira paid quando o pagamento cai e pode expirar. A confirmação chega por webhook.

Transferência (PIX enviado)

Uma transferência tira dinheiro do seu saldo e envia para uma chave PIX ou para um código copia e cola. Também muda de estado de forma assíncrona.

Saldo disponível e pendente

O disponível é o que você pode movimentar agora. O pendente é o que já foi recebido mas ainda não liberou. Só o disponível cobre uma transferência.

Ambientes

Sandbox e produção são separados em dados e saldo, mas escolhidos pela chave: a mesma URL atende os dois. A chave de teste opera numa conta de sandbox isolada, com provedor simulado. Ver Ambientes.

Envelope

Toda resposta tem a mesma forma: data, error e request_id. Trate o error como fonte da verdade, não o texto da mensagem — o code é estável, a mensagem pode mudar.

Idempotência

Repetir a mesma requisição não pode gerar duas cobranças. É o que a chave de idempotência resolve. Ver Idempotência.