Links de pagamento

Um link de pagamento é uma URL reutilizável (avexus.app/pay/<slug>) que vende sem integração nenhuma: você cria o link no painel ou pela API, divulga, e cada pagador que abrir gera a própria cobrança a partir dele.

A diferença para o checkout é a reutilização: o checkout é uma cobrança única com URL própria; o link atende muitos pagadores até expirar ou esgotar o limite de usos.

Criar um link

POST /payment-links TODO(contrato)

Campo	Tipo	Obrigatório	Descrição
`title`	string	Sim	Título exibido na página (mínimo 3 caracteres). Também vira a base do `slug`.
`amount`	number	Sim	Valor em BRL, maior que zero
`description`	string	Não	Descrição exibida na página
`methods`	string[]	Não	Meios aceitos. Padrão e único processado hoje: `Pix`.
`expires_at`	string	Não	Data/hora em que o link para de aceitar pagamento
`max_uses`	number	Não	Quantas cobranças o link pode gerar antes de esgotar. Ausente = ilimitado.

curl --request POST \
  --url https://api.avexus.app/payment-links \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "title": "Mentoria Pro",
    "description": "Acesso trimestral à mentoria",
    "amount": 197.00,
    "methods": ["Pix"],
    "max_uses": 100
  }'

{
  "paymentLink": {
    "id": "b7c1e0a9-3f52-4d18-9c6b-2a0e5f7d4c31",
    "slug": "mentoria-pro-3a9f1c",
    "url": "https://avexus.app/pay/mentoria-pro-3a9f1c",
    "title": "Mentoria Pro",
    "amount": 197.0,
    "active": true
  }
}

Listar links

GET /payment-links TODO(contrato)

Devolve os links da sua loja, cada um com a url pronta e a contagem de cobranças pagas que ele gerou.

curl --request GET \
  --url https://api.avexus.app/payment-links \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>'

Ativar, desativar e editar

PATCH /payment-links/{id} TODO(contrato)

Desativar (active: false) derruba o link na hora: a página pública passa a responder Link de pagamento indisponível.

curl --request PATCH \
  --url https://api.avexus.app/payment-links/b7c1e0a9-3f52-4d18-9c6b-2a0e5f7d4c31 \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --data '{ "active": false }'

Rotas públicas do pagador

Não são autenticadas — quem chama é a página do pagador.

Método	Endpoint	Descrição
`GET`	`/pay/{slug}`	Dados públicos do link (título, descrição, valor, meios, nome do lojista)
`POST`	`/pay/{slug}/charges`	O pagador informa nome, e-mail e CPF; a Avexus gera a cobrança Pix
`GET`	`/charges/{id}/status`	Consulta pública do status daquela cobrança (para a página fazer polling)

Quando o link recusa

As três guardas são checadas tanto na leitura quanto na geração da cobrança:

Situação	Mensagem
Link inativo ou inexistente	`Link de pagamento indisponível`
Passou de `expires_at`	`Link de pagamento expirado`
`uses` alcançou `max_uses`	`Link de pagamento esgotado`
Conta do lojista não está ativa	`Vendedor indisponível para cobrança`
`method` diferente de Pix	`Cartão de crédito ainda não habilitado — use PIX`
CPF do pagador inválido	`CPF do pagador inválido`

Veja também

Checkout — cobrança única com URL própria.
Integração de checkout — quando usar cada um.
Cobranças — o que chega no seu extrato depois do pagamento.