Primeira cobrança

Do sk_test_ ao QR na tela, com o webhook de confirmação já ligado.

Ao final desta página você terá uma cobrança PIX criada, um QR pronto para exibir, e o evento de confirmação chegando no seu servidor.

Antes de começar

• Uma chave sk_test_, criada em Desenvolvedores no painel. O valor em claro aparece uma única vez — copie na hora.
• Um endpoint público para receber o webhook. Em desenvolvimento, um túnel (ngrok, expose) serve.

Os valores aqui são inteiros em centavos: R$ 100,00 se envia como 10000. Decimais são recusados com 422, e o porquê está em Valores em centavos.

1. Crie a cobrança

   Envie o valor em centavos e uma Idempotency-Key sua. reference é o seu número de pedido — é por ele que você reencontra a cobrança depois.

   cURL

   curl -X POST https://api.usevext.com/v1/charges \
     -H "Authorization: Bearer sk_test_..." \
     -H "Idempotency-Key: pedido-1042" \
     -H "Content-Type: application/json" \
     -d '{
       "amount": 10000,
       "description": "Curso de Vue 3",
       "reference": "pedido-1042",
       "customer": {
         "name": "João Comprador",
         "email": "[e-mail]",
         "document": "11144477735",
         "document_type": "CPF"
       }
     }'
   

   A resposta vem 201:

   {
     "object": "charge",
     "id": "ch_01k1y6r6m6q2x0p3d9v4t7c8n2",
     "status": "pending",
     "payment_method": "pix",
     "amount": 10000,
     "currency": "BRL",
     "platform_fee": 798,
     "net_amount": 9202,
     "refunded_amount": 0,
     "reference": "pedido-1042",
     "pix": {
       "qr_code": "00020101021226840014br.gov.bcb.pix2562qrcodepix.example.com/v2/abcd1234",
       "expires_at": "2026-08-04T15:00:00+00:00",
       "end_2_end_id": null
     },
     "created_at": "2026-08-04T14:00:00+00:00",
     "paid_at": null
   }
   

   Guarde o id junto do seu pedido.

2. Mostre o QR ao comprador

   pix.qr_code é o payload copia-e-cola. A imagem do QR não vem na resposta: você a gera a partir do payload, com qualquer biblioteca de QR code.

   Mostre as duas formas — a imagem, para quem aponta a câmera, e o texto com um botão de copiar, para quem cola no aplicativo do banco. Exiba o vencimento a partir de pix.expires_at.

   A cobrança nasce pending e vale 1 hora por padrão. Ajuste com expires_in, em segundos, entre 60 e 604.800.

3. Receba o charge.paid

   Cadastre o seu endpoint em Desenvolvedores. Quando o PIX for confirmado, enviamos:

   {
     "id": "evt_01k1y6r7z2m4n6p8q0r2s4t6u8",
     "type": "charge.paid",
     "created_at": "2026-08-04T14:03:12+00:00",
     "data": {
       "charge": {
         "id": "ch_01k1y6r6m6q2x0p3d9v4t7c8n2",
         "status": "paid",
         "amount": 10000,
         "reference": "pedido-1042",
         "paid_at": "2026-08-04T14:03:11+00:00"
       }
     }
   }
   

   Antes de liberar o produto, confirme que o evento veio mesmo de nós. São poucas linhas de código, prontas nas quatro linguagens em Verificar a assinatura. Sem essa checagem, quem descobrir a URL do seu endpoint consegue simular um pagamento.

   Depois de conferir: grave o evento, responda 200, e processe em fila. Só aí libere o produto.

4. Confirme

   Consulte a cobrança e veja status: "paid":

   curl https://api.usevext.com/v1/charges/ch_01k1y6r6m6q2x0p3d9v4t7c8n2 \
     -H "Authorization: Bearer sk_test_..."
   

Se algo deu errado

O que você viu	Provavelmente
401 missing_api_key	O header Authorization não foi enviado
403 insufficient_scope	A chave não tem charges:write
422 validation_failed em amount	Você mandou um decimal. Envie centavos inteiros
422 seller_not_approved	O cadastro do vendedor ainda não está aprovado. O caminho é o painel

O catálogo completo está em Erros.

Próximos passos

Checkout completo

O fluxo de produção, com rede de segurança para quando o webhook falha.

Idempotência

Por que a Idempotency-Key importa mais do que parece.

Webhooks

Os três eventos, assinatura e retentativas.

Referência da API

Todos os campos, com playground.

---

Ficou algo de fora? Escreva para [e-mail]. Se o assunto for uma chamada específica, informe o horário dela; se for uma entrega de webhook, informe o X-Vext-Delivery — é por ele que localizamos a tentativa, a resposta do seu servidor e o horário.