📣 Webhooks RoyalBanking

Os Webhooks permitem que seu sistema receba notificações automáticas sempre que houver atualização de status em transações de Pix (cash in) ou saques (cash out). A seguir, você encontrará detalhes dos formatos de payload para cada cenário e como nossa plataforma reage caso não receba a confirmação adequada.

🔔 Webhook: Pix Pago (Cash In)

Quando um depósito via Pix (cash in) for confirmado como pago, nossa API irá disparar um webhook para o callbackUrl informado na requisição de cash in.

Exemplo de Payload (JSON)

{
  "idtransaction": "81bb141a-1746-49a8-bb4a-c3b8aa0d2259",
  "status": "paid"
}

Campos:

Campo	Tipo	Descrição
idtransaction	string	ID único da transação gerada no cash in.
status	string	“paid” indica que o Pix foi pago com sucesso.

🔔 Webhook: Saque Pago (Cash Out)

Quando um saque via Pix for processado com sucesso no painel RoyalBanking, será enviado um webhook para a URL cadastrada no painel.

Exemplo de Payload (JSON)

{
  "idTransaction": "exemplo34243243",
  "status": "SaquePago"
}

Campos:

Campo	Tipo	Descrição
idTransaction	string	ID da transação de saque (cash out).
status	string	“SaquePago” indica que o saque foi concluído com sucesso.

⚠️ Webhook: Saque Falhou (Cash Out)

Se um saque via Pix não puder ser concluído (saldo insuficiente, conta inválida, etc.), o painel RoyalBanking enviará um webhook informando a falha.

Exemplo de Payload (JSON)

{
  "idTransaction": "exemplo34243243",
  "status": "SaqueFalhou"
}

Campos:

Campo	Tipo	Descrição
idTransaction	string	ID da transação de saque (cash out) que falhou.
status	string	“SaqueFalhou” indica que houve erro ou rejeição no saque.

⚙️ Tratamento de Webhooks

Para garantir que seu sistema registre todos os eventos, siga estas diretrizes:

• 🔹 Ao receber um webhook, retorne imediatamente HTTP 200 com o conteúdo gerado por json_encode(200) (ou seja, apenas o número 200 no corpo).
• 🔹 Se a RoyalBanking não receber esse retorno exato (o corpo contendo 200), o webhook será reenviado até 3 vezes em intervalos crescentes.
• 🔹 Armazene o idtransaction ou idTransaction para atualizar o status da transação no seu banco de dados.

📌 Resumo de Estados

Evento	Status no Payload	Descrição
Cash In Pago	paid	Depósito via Pix confirmado e pago.
Cash Out Pago	SaquePago	Saque Pix concluído com sucesso.
Cash Out Falhou	SaqueFalhou	Saque Pix não pôde ser concluído.

Implemente seu endpoint de Webhook para processar cada payload e responder com 200 (por meio de json_encode(200)) rapidamente. Caso contrário, nossa plataforma tentará reenviar o webhook mais 3 vezes, garantindo que seu sistema seja notificado até que receba a confirmação correta. 🚀