Integre pagamentos AvalonPay com clareza.

Visão geral

A API AvalonPay usa JSON sobre HTTPS. Cada operação financeira exige autenticação. Use um identificador externo estável ao repetir a mesma cobrança para que a API reconheça o retry.

Autenticação

Gere credenciais no painel de API da sua conta. Mantenha o segredo somente no seu servidor. Faça login para receber um JWT e envie-o como Bearer token nas chamadas financeiras.

curl -X POST https://api.avalonpay.com.br/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"client_id":"av_live_...","client_secret":"SEU_SEGREDO"}'

{
  "token": "JWT_DA_SESSAO"
}

Envie o JWT como Authorization: Bearer JWT_DA_SESSAO. O token expira e as credenciais podem ser revogadas pelo painel.

PIX

Cria cobrança Pix pendente. A geração de QR Code não credita saldo; a confirmação do provedor é necessária.

{
  "amount": "25.90",
  "external_id": "pedido-2026-001",
  "clientCallbackUrl": "https://sua-loja.example/callback",
  "payer": {"name":"Cliente Exemplo","email":"cliente@example.com","document":"52998224725"}
}

Boleto para depósito

Gera um boleto Mercado Pago para depósito na conta AvalonPay pela Orders API. Nome, e-mail, CPF/CNPJ e endereço completo no Brasil são obrigatórios. O mesmo external_id com o mesmo valor é idempotente; outro valor para a mesma referência retorna conflito.

{
  "amount": "100.00",
  "external_id": "deposito-2026-001",
  "description": "Depósito da conta",
  "payer": {
    "name": "Cliente Exemplo",
    "email": "cliente@example.com",
    "document": "52998224725",
    "address": {
      "street_name": "Rua Exemplo",
      "street_number": "100",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "zip_code": "01001000"
    }
  }
}

A resposta inclui a linha digitável, código de barras, link e status. Mostre os dados ao pagador, mas não credite seu cliente quando a resposta inicial for pendente.

{
  "message": "Boleto created successfully.",
  "paymentResponse": {
    "transactionId": "mpb_...",
    "external_id": "deposito-2026-001",
    "status": "PENDING",
    "amount": "100.00",
    "payment_method": "boleto",
    "boleto": {
      "ticket_url": "https://...",
      "barcode_content": "...",
      "digitable_line": "...",
      "expiration_date": null
    }
  }
}

Consulta o estado diretamente no Mercado Pago. Quando o provider confirma a liquidação, o saldo é lançado uma única vez. O processo Node/PM2 também consulta boletos pendentes em lotes a cada cinco minutos.

Cartão e checkout

Links de pagamento e checkout de produto aceitam Pix, cartão e boleto. Para cartão, o pagador é redirecionado à página segura hospedada do Mercado Pago; o AvalonPay não recebe PAN nem CVV.

O checkout hospedado retorna checkoutUrl e preferenceId. Abra o endereço seguro retornado pelo servidor; não construa URLs Mercado Pago no navegador.

Webhooks

Configure a URL de notificação disponibilizada pelo AvalonPay no painel Mercado Pago e associe o segredo MERCADOPAGO_WEBHOOK_SECRET ao processo Node/PM2. Os eventos Orders são validados pela assinatura oficial e confirmados consultando a API do Mercado Pago.

Sem o segredo, a rota rejeita eventos Orders. A reconciliação Node/PM2 e o endpoint de status consultam o provedor diretamente como alternativa.

Erros comuns

Segurança

• Use HTTPS e nunca coloque segredo ou access token no navegador.
• Não envie PAN nem CVV à API AvalonPay.
• Não interprete redirect do checkout ou resposta inicial de boleto como pagamento confirmado.
• Guarde a mesma referência externa para repetir uma tentativa de forma idempotente.
• Respostas 429 incluem Retry-After; respeite esse intervalo antes de repetir.
• Configure o webhook Orders e use assinatura validada antes de confiar em notificações.

Dúvidas de credenciais: abra um chamado autenticado no painel AvalonPay.