Integração de checkout

Existem três formas de cobrar na Avexus. Elas terminam no mesmo lugar — uma cobrança Pix, um webhook de confirmação e o dinheiro no seu saldo —, mas mudam quanta tela você precisa construir.

Caminho	Você constrói	Bom para
API direta	Toda a tela de pagamento	Loja própria, app, fluxo com regras suas
Checkout hospedado	Nada — só redireciona	Cobrança única com URL para mandar por WhatsApp/e-mail
Link de pagamento	Nada — só divulga	Vender o mesmo item para várias pessoas

Caminho 1 — API direta

Você cria a cobrança no seu servidor e desenha o QR code na sua interface.

1. Crie a cobrança com POST /api/transactions, mandando amount, requester e o seu external_ref.

2. Renderize o qr_code — ele é o Pix copia-e-cola (BR Code). Mostre o QR e um botão “copiar código”.

3. Espere o webhook transaction com status: "CONFIRMED" e libere o pedido. Não confie em redirecionamento do navegador para confirmar pagamento — quem confirma é o webhook.

POST /api/transactions

curl --request POST \
  --url https://api.avexus.app/api/transactions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "amount": 197.00,
    "external_ref": "pedido_1042",
    "requester": {
      "name": "Maria Souza",
      "email": "maria@example.com",
      "document": "12468239008"
    },
    "payment_method": "Pix",
    "expires_in": 3600,
    "description": "Mentoria Pro"
  }'

O pagador não vê a sua chave

Nunca coloque o x-token (sk_…) no front-end para criar a cobrança direto do navegador. A chamada sai do seu servidor; a página do pagador só recebe o qr_code já pronto.

Caminho 2 — Checkout hospedado

A Avexus hospeda a página. Você cria o checkout, recebe a URL e manda o pagador para lá.

1. Crie o checkout com valor e descrição.

2. Mande a URL ao pagador (avexus.app/pay/c/<id>).

3. O pagador informa os dados e gera o Pix na própria página — o QR code só é criado nesse momento.

4. Você recebe o webhook de confirmação, exatamente como no caminho 1.

TODO(contrato)

As rotas do checkout ainda dependem da frente F0 — Contrato: elas não existem na base Go e o exemplo abaixo segue o formato do legado. Veja Checkout.

POST /checkouts (contrato provisório)

curl --request POST \
  --url https://api.avexus.app/checkouts \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "amount": 197.00,
    "description": "Mentoria Pro",
    "external_ref": "pedido_1042",
    "expires_in_hours": 24
  }'

Caminho 3 — Link de pagamento

Um link só, reutilizável, para muitos pagadores. Cada um que abrir gera a própria cobrança.

Use quando o item é o mesmo para todo mundo (um curso, uma mensalidade, um ingresso) e você não quer criar uma cobrança por venda. Limite por expires_at (data) e/ou max_uses (quantidade).

Veja Links de pagamento.

O que vale para os três

A confirmação vem do webhook

Registre o endpoint antes de começar a cobrar e libere o pedido só quando o evento transaction chegar com CONFIRMED. Consulta por polling (GET /api/transactions?external_ref=…) serve como rede de segurança, não como mecanismo principal.

Concilie pelos dois lados

Mande sempre o seu external_ref na criação e guarde o magic_id da resposta. Assim a conciliação funciona a partir de qualquer um dos dois sistemas.

Teste no sandbox primeiro

Use https://sandbox-api.avexus.app e os valores mágicos do guia do sandbox para exercitar confirmação, falha, expiração e disputa antes de ir para produção.

Trate expiração

Cobrança Pix tem prazo (expires_in, entre 60 e 86 400 segundos). Depois disso o status vira EXPIRED e o QR code não paga mais — a sua tela precisa oferecer “gerar novo código”.

Veja também

CobrançasA referência completa de POST e GET /api/transactions.

Receber webhooksPayloads, headers e verificação da assinatura.

CheckoutCobrança única com URL hospedada pela Avexus.

Links de pagamentoLink reutilizável para vender sem integração.