> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usevext.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introdução

> Cobranças PIX com split, estornos e saldo do vendedor. O que a API faz, o que ela recusa e por quê.

A Vext é um gateway de pagamentos PIX com split entre o vendedor e a plataforma. Você cria a
cobrança, mostra o QR ao comprador, e nós avisamos quando o dinheiro entra.

<CardGroup cols={2}>
  <Card title="Primeira cobrança" icon="rocket" href="/quickstart">
    Do `sk_test_` ao QR na tela, com o webhook já ligado.
  </Card>

  <Card title="Referência da API" icon="terminal" href="/api-reference/introducao">
    As cinco operações, com playground.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/webhooks/visao-geral">
    Os nove eventos e como conferir a assinatura.
  </Card>

  <Card title="Receitas" icon="route" href="/receitas/checkout-pix">
    Fluxos completos, do checkout à conciliação.
  </Card>
</CardGroup>

## Quatro convenções que valem para tudo

São quatro decisões de design que se repetem em toda a API. Conhecendo elas, o resto da
documentação fica previsível — e você evita os quatro tropeços mais comuns de quem começa.

<AccordionGroup>
  <Accordion title="Dinheiro é sempre centavos inteiros" icon="coins">
    R\$ 100,00 se envia como `10000`. Uma convenção só, em todos os campos, então nunca há dúvida
    sobre o formato. Decimais são recusados com `422` porque `19.99 * 100` dá `1998.9999999999998` em
    ponto flutuante — e o centavo perdido aí só apareceria na conciliação do mês.

    [Valores em centavos →](/essenciais/valores-em-centavos)
  </Accordion>

  <Accordion title="A chave secreta fica no servidor" icon="key-round">
    O valor em claro aparece **uma única vez**, na criação: guardamos apenas um hash SHA-256, de modo
    que nem um vazamento do nosso banco permite cobrar em seu nome. Em troca, a chave é sua para
    guardar — e o lugar dela é o servidor, nunca o navegador do comprador.

    [Autenticação →](/essenciais/autenticacao)
  </Accordion>

  <Accordion title="Idempotency-Key em todo POST" icon="repeat">
    Com ela, uma conexão que cai entre a requisição e a resposta deixa de ser um problema: você repete
    com a mesma chave e recebe a cobrança que já existe, em vez de criar uma segunda.

    [Idempotência →](/essenciais/idempotencia)
  </Accordion>

  <Accordion title="Erros têm código estável" icon="triangle-alert">
    Todo erro traz um `code` que não muda, então dá para escrever a sua lógica em cima dele com
    segurança. A `message` fica livre para ser reescrita e melhorada sem quebrar a sua integração.

    [Erros →](/essenciais/erros)
  </Accordion>
</AccordionGroup>

## O que existe na v1

**Cinco operações**, todas sob `/v1`:

| Operação                                                 | Endpoint                         |
| -------------------------------------------------------- | -------------------------------- |
| [Criar cobrança](/api-reference/cobrancas/criar)         | `POST /v1/charges`               |
| [Listar cobranças](/api-reference/cobrancas/listar)      | `GET /v1/charges`                |
| [Consultar cobrança](/api-reference/cobrancas/consultar) | `GET /v1/charges/{code}`         |
| [Estornar cobrança](/api-reference/cobrancas/estornar)   | `POST /v1/charges/{code}/refund` |
| [Consultar saldo](/api-reference/saldo/consultar)        | `GET /v1/balance`                |

**Nove eventos**, que nós enviamos para o seu sistema:

| Evento                                                             | Quando dispara                                    |
| ------------------------------------------------------------------ | ------------------------------------------------- |
| [`charge.paid`](/api-reference/webhooks/charge-paid)               | O pagamento é confirmado, no PIX ou no cartão     |
| [`charge.failed`](/api-reference/webhooks/charge-failed)           | A operadora do cartão recusa o pagamento          |
| [`charge.in_analysis`](/api-reference/webhooks/charge-in-analysis) | A análise de fraude segura um pagamento no cartão |
| [`charge.refunded`](/api-reference/webhooks/charge-refunded)       | Um estorno é concluído                            |
| [`charge.chargedback`](/api-reference/webhooks/charge-chargedback) | O portador contesta a compra na operadora         |
| [`med.opened`](/api-reference/webhooks/med-opened)                 | O comprador abre uma contestação de Pix           |
| [`med.approved`](/api-reference/webhooks/med-approved)             | A contestação é deferida — a venda é devolvida    |
| [`med.rejected`](/api-reference/webhooks/med-rejected)             | A contestação é indeferida — a venda segue de pé  |
| [`withdrawal.paid`](/api-reference/webhooks/withdrawal-paid)       | O saque cai na conta do vendedor                  |

## Quatro coisas que vale saber de antemão

Para você não procurar o que não existe:

* **A imagem do QR você gera.** Devolvemos o payload copia-e-cola em `pix.qr_code`, e qualquer
  biblioteca de QR o transforma em imagem em milissegundos. Assim as respostas ficam leves e você
  controla tamanho, cor e formato.
* **A API cria PIX; o cartão chega pelos mesmos eventos.** `POST /v1/charges` só cria cobrança PIX,
  então toda cobrança que nasce daqui vem `payment_method: pix`. As vendas de cartão feitas pelo
  checkout ou por link de pagamento são suas também, e aparecem em `GET /v1/charges` e nos webhooks
  com `payment_method: credit_card`.
* **O saque é pedido pelo painel.** A API não tem endpoint para isso, mas avisa quando o dinheiro
  cai, pelo evento `withdrawal.paid`.
* **Cada chave enxerga só a própria conta.** A lista devolve apenas as cobranças do vendedor dono da
  chave, e uma cobrança de outra conta responde o mesmo `404` de uma que não existe.

## URL base

Toda chamada vai para:

```
https://api.usevext.com
```

Todo endpoint desta versão vive sob `/v1`. A URL completa de uma criação de cobrança é
`https://api.usevext.com/v1/charges`.

***

Ficou algo de fora? Chame no [WhatsApp](https://wa.me/5511936185272). 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.