Links de Pagamentos

Os Links de Pagamento permitem criar URLs de checkout compartilháveis que aceitam pagamento via cartão de crédito/débito, Pix e Boleto — sem exigir cadastro do pagador.

Casos de uso

Enviar link de cobrança por email ou WhatsApp
Incorporar o checkout direto no seu site (via SDK)
Cobranças recorrentes de valor fixo (sem expiração)
Ingressos para eventos pontuais (com maxUses e expiresAt)
Repartir receita com parceiros (split)

Recursos principais

Recurso	Descrição
Múltiplos métodos	Habilite cartão, Pix e/ou Boleto no mesmo link
Valor fixo ou aberto	Defina o valor na criação ou deixe o pagador decidir
Parcelamento	Configure as opções de parcelas permitidas (1x a 12x)
Repasse de taxa	Repassa a taxa da transação ao pagador (gross-up automático)
Split de pagamento	Distribua o valor recebido entre múltiplos merchants
Limites de uso	Defina máximo de pagamentos (`maxUses`) e/ou expiração (`expiresAt`)
Notificações por email	Receba email a cada pagamento confirmado
Métricas	Acompanhe visualizações, tentativas, pagamentos confirmados e total recebido
SDK de embed	Integre o checkout em qualquer site

Fluxo completo

1. Autenticar          POST /v1/oauth/token
2. Criar link          POST /v1/acquiring/links → retorna slug + checkoutUrl
3. Compartilhar URL    Envie o checkoutUrl ao pagador (email, WhatsApp, embed)
4. Pagador paga        Abre a URL → escolhe método → finaliza o pagamento
5. Confirmação         A Autra processa e confirma o pagamento automaticamente
6. Consultar detalhes  GET /v1/acquiring/links/{linkId} → pagamentos e métricas

Status do link

Status	Descrição
`ACTIVE`	Link aceita pagamentos
`INACTIVE`	Link pausado (pode ser reativado)
`EXPIRED`	`expiresAt` foi atingida — não aceita mais pagamentos
`EXHAUSTED`	`maxUses` foi atingido — não aceita mais pagamentos

Confirmação de pagamento

Pagamentos são confirmados de forma assíncrona. Há quatro formas de saber quando um pagamento foi confirmado:

1. Callback do SDK (recomendado para checkout embed)

Ao usar o Checkout Embed SDK, o callback onSuccess dispara imediatamente quando o pagamento é confirmado:

AutraCheckout.open({
  slug: 'lnk_a1b2c3d4',
  onSuccess: function(data) {
    // Pagamento confirmado — atualize sua UI
    console.log(data.status, data.amount, data.method);
  }
});

2. Polling via API (recomendado para server-to-server)

Consulte os detalhes do link para obter todos os pagamentos confirmados:

GET /v1/acquiring/links/{linkId}

A resposta inclui um array payments com status, valor, método e dados do pagador de cada pagamento. Detalhes completos do array na seção Array payments abaixo.

3. Notificação por email

Quando notifyEmail é true, o email informado em actor recebe uma notificação a cada pagamento confirmado, com os dados do pagador e link da nota.

4. Webhook outbound (recomendado para server-to-server em tempo real)

Cadastre uma URL no domínio acquiring para receber, em tempo real, os eventos de transação assinados com HMAC-SHA256:

PUT /v1/banking/webhooks/acquiring

Eventos do domínio acquiring: acquiring.financial_transaction (cartão/Pix autorizado), acquiring.payout (Pix liquidado), acquiring.payment_slip_notification (boleto pago). Cada entrega traz o header X-Autra-Signature: sha256=<hex> — valide antes de processar.

O webhook entrega eventos no nível de transação (não por link). Para reconciliação por link, o GET /v1/acquiring/links/{linkId} continua sendo a fonte da verdade. Detalhes de cadastro, payload, validação HMAC e retry na página Outbound Webhooks da referência.

Array `payments` — guia detalhado

O GET /v1/acquiring/links/{linkId} retorna o campo payments. Antes do primeiro pagamento, vem null. A partir da primeira tentativa, vira um array de pagamentos consolidando os três métodos (cartão, boleto, Pix) — cada item identifica o método pelo campo transactionMethod.

⚠️ A query não filtra por status — toda tentativa registrada aparece no array, incluindo recusadas. Use isso para auditoria e suporte; para considerar um link como "pago", filtre pelos status finais positivos.

Status possíveis por método

Cartão (`transactionMethod: "CARD"`)

Status	Significado	Final?
`ACCEPTED`	Pagamento aprovado e concluído (venda direta)	✅ pago
`CAPTURED`	Pré-autorização capturada — valor liquidado	✅ pago
`PREAUTH`	Pré-autorizado, aguardando captura ou expiração	⏳ intermediário
`VOIDED`	Estornado dentro do D0 (cancelamento)	⛔ cancelado
`AUTH_REJECTED`	Recusado pelo emissor (saldo, fraude, regra do banco)	❌ recusado
`CHALLENGE_REJECTED`	Recusado no 3DS challenge	❌ recusado
`SETUP_REJECTED`	Recusado antes do auth (validação prévia)	❌ recusado
`FAILED`	Erro técnico (timeout, falha de integração)	❌ erro

Boleto (`transactionMethod: "BOLETO"`)

Status	Significado	Final?
`PENDING`	Boleto emitido, aguardando pagamento	⏳ intermediário
`PAID`	Pago (compensação bancária do boleto)	✅ pago
`PAID_PIX`	Pago via QR Code Pix do boleto (BoléPix)	✅ pago
`EXPIRED`	Vencido sem pagamento	⛔ expirado
`CANCELED`	Cancelado pelo emissor	⛔ cancelado
`FAILED`	Erro na emissão	❌ erro

BoléPix: quando o boleto é pago lendo o QR Code Pix impresso nele, o status final é PAID_PIX (e não PAID). Trate PAID_PIX como pago — veja a lista abaixo.

Pix (`transactionMethod: "PIX"`)

Status	Significado	Final?
`PENDING`	QR gerado, aguardando pagamento	⏳ intermediário
`AUTHORIZED`	Pagamento confirmado pelo banco do pagador (valor garantido)	✅ pago
`SETTLED`	Liquidado — dinheiro disponível na conta	✅ pago
`EXPIRED`	QR não foi pago no prazo	⛔ expirado

Status considerados "pago"

Para conciliação, trate como pagos os seguintes status (mesmo critério usado internamente para calcular paidCount e totalPaid):

ACCEPTED, CAPTURED, PAID, PAID_PIX, AUTHORIZED, SETTLED

const pago = payments?.some(p =>
  ["ACCEPTED", "CAPTURED", "PAID", "PAID_PIX", "AUTHORIZED", "SETTLED"].includes(p.status)
);

Quando o array tem mais de um item

Como tentativas recusadas também são gravadas, é normal o array trazer múltiplos elementos:

Cenário	O que aparece no array
Tentativa recusada + nova bem-sucedida	Cliente erra o cartão (`AUTH_REJECTED`) e tenta de novo aprovando (`ACCEPTED`) → 2 itens
Métodos diferentes na mesma compra	Tenta cartão (recusa) e troca para Pix (`AUTHORIZED`) → 2 itens, um por `transactionMethod`
Link com `maxUses > 1`	Cada pagador gera 1 entrada — pode haver vários `ACCEPTED`/`AUTHORIZED` no mesmo link
Várias tentativas até travar	3 recusas + 1 aprovação → 4 itens; só o último com status final positivo

Quando o array NÃO duplica

Atualizações de estado na mesma transação alteram a linha existente, não criam outra:

Cartão pré-autorizado: a linha muda PREAUTH → CAPTURED (mesmo id).
Boleto pago: a linha muda PENDING → PAID (ou PENDING → PAID_PIX no BoléPix).
Pix confirmado: a linha muda PENDING → AUTHORIZED → SETTLED.

Como o status é atualizado

A Autra atualiza o status de cada pagamento automaticamente, conforme a confirmação de cada método:

Método	Transição
Cartão	resposta imediata → `ACCEPTED` ou `AUTH_REJECTED` ou `CHALLENGE_REJECTED`
Pix	`PENDING` → `AUTHORIZED` (confirmado) → `SETTLED` (liquidado); ou `PENDING` → `EXPIRED`
Boleto	`PENDING` → `PAID` (ou `PAID_PIX` no BoléPix); ou `PENDING` → `EXPIRED`/`CANCELED`

Nota: para acompanhar o status do seu lado, use o callback do SDK (checkout embed), polling via API ou webhook outbound no domínio acquiring (ver a seção Confirmação de pagamento → Webhook outbound acima e a página Outbound Webhooks na referência).

Checkout Embed SDK

Para embedar o checkout direto no seu site em vez de redirecionar para a página da Autra, use o Checkout Embed SDK.

Ver documentação completa: Funcionalidades → Checkout Embed SDK.

Endpoints relacionados

POST /v1/acquiring/links — Criar link de pagamento
GET /v1/acquiring/links — Listar links
GET /v1/acquiring/links/{linkId} — Detalhes do link + pagamentos + eventos
PATCH /v1/acquiring/links/{linkId} — Atualizar link
PATCH /v1/acquiring/links/{linkId}/status — Ativar ou desativar
GET /v1/acquiring/merchants — Listar merchants (para configuração de split)
POST /v1/acquiring/fees/simulate — Simular taxas do merchant

Pontos de atenção

Não considere pago apenas pela resposta da API — a resposta síncrona indica apenas que a requisição foi aceita.
Processe eventos de forma idempotente — evite processamento duplicado se você consumir eventos do seu lado.
Use expiresAt e maxUses — protege contra uso indevido (link compartilhado fora do contexto previsto).
Repasse de taxa (passFee): o valor cobrado do pagador é ajustado automaticamente (gross-up) para que você receba o líquido desejado. A simulação vem em feeSimulation na resposta de criação.
Split sempre exige que o merchant dono do link esteja na lista de splits quando configurado.
Métricas (viewCount, attemptCount, paidCount, totalPaid) são agregadas a partir dos três métodos (cartão, Pix, boleto) e atualizadas em tempo quase real.