Skip to main content
Implementado no Fire e verificado contra o sandbox da DSI. Falta definir o host público final; até então a URL é combinada por ambiente.
Quando um pagamento criado pelo PayBridge muda de status — é aprovado, cancelado ou reembolsado — a DSI faz um POST neste endpoint do Fire. É o caminho primário para fechar a cobrança: sem essa notificação, a cobrança fica esperando o cliente.

​
Endpoint

​
string
obrigatório
País da conexão DSI em ISO alpha-2 (EC, CL, CO, AR, VE, BR). Define qual conexão e qual segredo são usados para validar a assinatura. Aceita minúsculas.
O Fire envia essa URL em cada solicitação de pagamento, dentro de settings.callbacks.status, então não há nada para configurar por fora: cada pagamento já viaja com o callback do seu país.

​
Autenticação: assinatura HMAC

Este endpoint não usa API key nem bearer. A autenticidade vem da assinatura.
​
string
obrigatório
HMAC-SHA256 em hexadecimal do corpo cru da requisição, calculado com o segredo da conexão do país. Um administrador do Fire carrega esse segredo ao configurar a conexão DSI do país — peça-o a ele se precisar verificar a assinatura.
Cálculo da assinatura
  • Assina-se o body cru, não um JSON reconstruído: reordenar chaves ou mudar espaços invalida a assinatura.
  • A comparação é feita em tempo constante.
  • Assinatura ausente ou inválida → 400, e nada é processado.
Se a conexão do país ainda não tem segredo carregado, o Fire aceita a notificação sem validar a assinatura e registra um aviso. Carregue o segredo na conexão antes de ir para produção.

​
Payload

​
string
obrigatório
Referência que o Fire enviou ao criar o pagamento. É a chave de correlação: identifica a tentativa (attempt) exata à qual a notificação pertence.
​
string
obrigatório
Id da transação na DSI. O Fire usa como id de evento para deduplicar.
​
string
obrigatório
Status alcançado: approved, cancelled, waitingPayment, refundPayment ou refundFailed.
​
integer
obrigatório
Valor pago em centavos (inteiro). 1990 = 19,90.
​
string
Mensagem do provedor (motivo da recusa, detalhe do reembolso).
​
string
obrigatório
Filial do pagamento (o branchOffice que o Fire enviou na criação).

​
O que o Fire faz com cada status

paidPrice é guardado como referência do provedor; o valor que o Fire credita é o da tentativa.

​
Resposta

O Fire responde 200 assim que valida a assinatura e enfileira a notificação. A transição de status é aplicada por um worker segundos depois.
200
Um 200 significa recebida, não aplicada. Para saber o resultado final, consulte a cobrança com GET /api/v1/external/paybridge/intents/{intentId}.

​
Idempotência e repetições

Deduplicação

O Fire deduplica pela trinca externalReference + transactionId + status. Reenviar a mesma notificação devolve 200 com duplicate: true e não processa de novo.

Sem retrocesso

Uma tentativa já em status terminal não volta atrás por uma notificação atrasada. A única exceção são os reembolsos, que se aplicam sobre um pagamento aprovado.

Referência desconhecida

Se o externalReference não corresponde a nenhuma tentativa, o Fire responde 200 e descarta, para a DSI não repetir para sempre.

Repetições seguras

O processamento é idempotente: dá para repetir após um 5xx sem risco de aplicar o mesmo status duas vezes.

​
Relacionado

Cobrar a partir de um canal

Como se cria a cobrança que esta notificação fecha.

Métodos suportados por país

Quais métodos cobram hoje pela DSI em cada país.