Skip to main content
Emita cobranças Pix diretamente para uma carteira da sua conta, receba o copia e cola e o QR code, e acompanhe a situacao pela API. Nao e necessario configurar webhook: a consulta sincroniza o estado com a provedora.
Requer escopo payments:create para criar e payments:read para consultar.

Requisitos

Antes de criar uma cobranca, confirme que:
  • A conta esta ativa e habilitada financeiramente.
  • O servidor esta com PAYMENTS_ENABLED=true.
  • A carteira informada pertence a propria conta.
  • O valor esta dentro do limite por pagamento da conta (consulte /v1/account/fees-limits).
  • A provedora esta configurada.
Novos cadastros sao ativados para recebimento apos confirmacao de e-mail. KYC e obrigatorio apenas para saques.

Criar cobranca

Envie POST /v1/payments com Idempotency-Key obrigatorio no header. O corpo exige amountCents, walletId e description.
integer
required
Valor em centavos de BRL. Minimo 1. Exemplo: 1000 para R$ 10,00.
string
required
UUID da carteira da conta.
string
required
Descricao da cobranca (1 a 300 caracteres).
string
Referencia do pedido no seu sistema (ate 100 caracteres).
string
required
UUID da cobranca criada.
integer
required
Valor em centavos.
string
required
Situacao inicial: pending.
string
Copia e cola do Pix. Pode ser nulo.
string
QR code em SVG. Nulo quando indisponivel.
string
Data/hora de expiracao no formato ISO 8601.

Status de uma cobranca

Uma cobranca pode estar em uma das seguintes situacoes:

Expiracao

Novas cobrancas tem prazo maximo de 1 hora desde a intencao persistida. O prazo pode ser menor se a provedora indicar outro valor. Apos expirar, o copia e cola deixa de ser retornado. Confirmacoes tardias da provedora ainda podem ser conciliadas uma vez.

Consultar cobranca

Use GET /v1/payments/{id} para sincronizar a situacao com a provedora. A rota consulta a provedora diretamente, mesmo sem webhook configurado.
curl

Consultar Pix (copia e cola)

Use GET /v1/payments/{id}/pix para obter o copia e cola original e sincronizar a situacao.
curl
pending, processing e unknown nao confirmam entrega de dinheiro. Somente paid confirma o recebimento.

Tarifas

As tarifas de recebimento dependem da operacao da conta:
  • White (Wyze): fixa de 40 centavos.
  • Black (Kyvo): 399 pontos-base (3,99%) mais 70 centavos.
Consulte /v1/account/fees-limits para os valores exatos da sua conta.

Idempotencia

Sempre envie Idempotency-Key ao criar. Se houver falha de comunicacao, repita a requisicao com a mesma chave, mesmo corpo e mesma credencial. Nao crie outra chave para tentar resolver um resultado incerto. Conflitos retornam HTTP 409.

Erros comuns