Webhooks

Os webhooks entregam notificações em tempo real ao seu servidor quando um pagamento atinge um status específico. Em vez de fazer polling na API por atualizações, seu sistema recebe uma requisição POST com os detalhes do pagamento.

Eventos Suportados

Evento	Gatilho	Ação Típica
`AUTHORIZED`	Pagamento autorizado com sucesso (fundos reservados)	Confirmar que o método de pagamento é válido
`CAPTURED`	Pagamento capturado e fundos liquidados	Concluir o pedido, liberar as mercadorias
`CHALLENGE`	Challenge 3DS iniciado; aguardando verificação do portador do cartão	Aguardar o desfecho (`AUTHORIZED` ou `DECLINED`)
`DECLINED`	Pagamento rejeitado pelo emissor ou por regras de fraude	Solicitar ao usuário outro método
`VOIDED`	Autorização cancelada antes da captura	Atualizar o pedido como cancelado
`REFUNDED`	Fundos devolvidos ao portador do cartão (total ou parcial)	Confirmar o reembolso no seu sistema

Configuração de Webhooks

Os endpoints de webhook são configurados durante o onboarding do lojista. Entre em contato com a equipe Inyo para:

Fornecer sua(s) URL(s) de webhook
Selecionar quais eventos você deseja receber
Configurar a autenticação (Basic auth ou Bearer token)

API de registro de webhooks: Os webhooks também podem ser gerenciados programaticamente por meio dos endpoints de notificação. Veja a especificação OpenAPI para os endpoints POST, GET e DELETE /notification.

Payload do Webhook

Todos os eventos de webhook entregam a mesma estrutura JSON — o objeto completo do pagamento no momento do evento:

{
  "paymentId": "469670e2-31e3-4700-b9f2-abee99418dc4",
  "parentPaymentId": "469670e2-31e3-4700-b9f2-abee99418dc4",
  "externalPaymentId": "order-12345",
  "redirectAcsUrl": "",
  "amount": 95.00,
  "created": "2025-01-21 16:31:02",
  "approved": true,
  "message": "Payment Approved",
  "acquirerMessage": "IN_PROCESS_AUTHORISED",
  "automaticReversed": false,
  "status": "AUTHORIZED",
  "captured": false,
  "voided": false,
  "authCode": "469670e2-31e3-4700-b9f2-abee99418dc4",
  "issuerName": "BANK OF AMERICA",
  "issuerCountry": "UNITED STATES",
  "cvcResult": "NOT_SENT",
  "avsResult": "NOT_SENT",
  "aavAddressResult": "NOT_CHECKED",
  "aavPostcodeResult": "NOT_CHECKED",
  "aavCardholderNameResult": "N/A",
  "aavTelephoneResult": "NOT_CHECKED"
}

Campos do Payload

Veja Autorizando um Pagamento com Cartão para a descrição completa de todos os campos da resposta. O payload do webhook é idêntico ao objeto de resposta do pagamento.

Tratando Webhooks

Boas Práticas

Retorne 200 rapidamente — Confirme o recebimento antes de fazer processamento pesado. Enfileire o evento para processamento assíncrono.
Verifique a origem — Valide que as requisições de webhook vêm da faixa de IPs da Inyo ou verifique as credenciais de autenticação.
Trate duplicatas — Os webhooks podem ser entregues mais de uma vez. Use paymentId + status como chave de idempotência.
Verifique status, não apenas approved — O campo status (AUTHORIZED, CAPTURED, DECLINED, etc.) é o estado autoritativo do pagamento.
Não dependa exclusivamente de webhooks — Sempre confirme o status do pagamento via endpoint GET de pagamento antes de concluir pedidos. Webhooks são notificações, não a fonte da verdade.

Exemplo de Handler (Node.js)

app.post('/webhooks/inyo', (req, res) => {
  // Confirme o recebimento imediatamente
  res.status(200).send('OK');

  const payment = req.body;
  const { externalPaymentId, status, paymentId } = payment;

  switch (status) {
    case 'AUTHORIZED':
      // Pagamento autorizado — pronto para capturar
      markOrderAsAuthorized(externalPaymentId, paymentId);
      break;
    case 'CAPTURED':
      // Fundos liquidados — conclua o pedido
      fulfillOrder(externalPaymentId);
      break;
    case 'DECLINED':
      // Pagamento falhou — notifique o cliente
      notifyDecline(externalPaymentId, payment.message);
      break;
    case 'VOIDED':
      // Autorização cancelada
      cancelOrder(externalPaymentId);
      break;
    case 'REFUNDED':
      // Fundos devolvidos
      processRefund(externalPaymentId, payment.amount);
      break;
  }
});

Política de Retentativas

Se o seu endpoint retornar uma resposta não-2xx ou expirar por timeout, a Inyo tentará a entrega novamente com backoff exponencial. Garanta que o seu handler seja idempotente para tratar retentativas com segurança.