Pular para o conteúdo principal

Chave Secreta e URL de Notificação

Este guia explica como consultar a Chave Secreta do merchant e configurar a URL utilizada pela Orkestral para enviar atualizações das transações.

A URL de notificação funciona como o webhook do cliente.

Antes de começar​

Para realizar a configuração, é necessário:

  • possuir uma conta ativa na Orkestral;
  • ter acesso à plataforma de gerenciamento;
  • estar vinculado ao merchant que será configurado;
  • possuir uma URL pública e acessível para receber as notificações.

Acessar as configurações de integração​

  1. Acesse a plataforma da Orkestral.
  2. No menu lateral, clique em Integração.
  3. Informe novamente a senha do seu usuário.
  4. Clique em Enviar.

Após a validação da senha, a plataforma apresenta a Chave Secreta e a configuração da URL de notificação.

Chave Secreta​

O que é a Chave Secreta?​

A Chave Secreta é uma credencial associada ao merchant. Ela é gerada automaticamente durante a criação do merchant e é compartilhada pelos usuários vinculados a ele. Portanto, não é criada uma chave diferente para cada usuário da plataforma.

A Orkestral utiliza essa chave para gerar o checksum enviado nas notificações de transação. O cliente pode utilizar a chave para validar a autenticidade das notificações recebidas, conforme o contrato de integração da API.

informação

A Chave Secreta exibida nessa página não substitui o token de acesso das chamadas à API. A autenticação das APIs da Orkestral utiliza OAuth e tokens JWT.

Consultar a Chave Secreta​

  1. Acesse o menu Integração.
  2. Informe novamente a senha do seu usuário.
  3. Localize a seção Chave Secreta.
  4. Utilize o botão de cópia para copiar o valor apresentado.
  5. Armazene a chave em um local seguro.

Proteger a Chave Secreta​

  • Não compartilhe a chave por email, mensagens ou canais públicos.
  • Não armazene a chave diretamente no código-fonte.
  • Não exponha a chave em aplicações frontend.
  • Não registre a chave em logs.
  • Utilize um gerenciador de segredos ou uma variável de ambiente protegida.
  • Restrinja o acesso aos serviços responsáveis pela validação das notificações.
aviso

A plataforma não disponibiliza a regeneração ou a rotação da chave pela interface. Em caso de exposição ou comprometimento, acione o time responsável pela Orkestral.

URL de Notificação​

O que é a URL de Notificação?​

A URL de notificação é o endereço utilizado pela Orkestral para informar ao cliente as atualizações das transações.

Por exemplo, uma notificação pode ser enviada quando uma transação for aprovada, negada, liquidada ou sofrer outra alteração relevante de status.

A Orkestral envia uma requisição HTTP POST, com conteúdo em formato JSON, para a URL selecionada.

Cadastrar a URL​

  1. Acesse o menu Integração.

  2. Informe novamente a senha do seu usuário, caso seja solicitado.

  3. Localize a seção URL.

  4. Informe o endereço completo do webhook, por exemplo:

    https://api.exemplo.com/webhooks/orkestral

  5. Clique no botão de confirmação para salvar.

  6. Verifique se a URL cadastrada foi atualizada corretamente.

Requisitos recomendados​

A URL deve:

  • ser pública e acessível pela internet;
  • utilizar HTTPS;
  • aceitar requisições HTTP POST;
  • aceitar conteúdo no formato application/json;
  • retornar um status HTTP de sucesso da família 2xx;
  • processar notificações de maneira idempotente;
  • validar o checksum recebido;
  • não depender de uma sessão autenticada no navegador;
  • possuir monitoramento para falhas e indisponibilidade.
observação

Embora HTTPS seja recomendado para proteger os dados transmitidos, a interface atual não realiza uma validação explícita do protocolo informado.

URL padrão e URL por transação​

A Orkestral permite definir a URL de notificação no merchant ou diretamente na transação.

URL cadastrada no merchant​

A URL cadastrada na página Integração funciona como o webhook padrão do merchant. Ela é utilizada quando uma transação não possui uma URL específica.

URL informada na transação​

Ao criar uma transação, o cliente também pode informar o campo webhook_url:

{
  "webhook_url": "https://api.exemplo.com/webhooks/transacao"
}

Quando esse campo estiver preenchido, a URL informada será utilizada para a transação correspondente.

Ordem de prioridade​

A Orkestral utiliza a seguinte ordem:

  1. webhook_url informado na criação da transação;
  2. URL cadastrada no merchant pela página Integração.

Se nenhuma das duas URLs estiver configurada, a Orkestral não terá um endereço válido para entregar a notificação ao cliente.

Conteúdo da notificação​

A notificação pode conter informações como:

  • identificador do merchant;
  • identificador da transação;
  • valor e moeda;
  • país da transação;
  • método de pagamento;
  • identificador do evento;
  • nome ou status do evento;
  • mensagem retornada pelo provedor de pagamento;
  • checksum de segurança.

Exemplo ilustrativo:

{
  "merchantId": "00000000-0000-0000-0000-000000000000",
  "transactionId": "11111111-1111-1111-1111-111111111111",
  "amount": 10000,
  "currency": "BRL",
  "country": "BR",
  "paymentMethod": "PIX",
  "eventId": 12345,
  "eventName": "APPROVED",
  "pspMessage": "Transaction approved",
  "checksum": "valor-do-checksum"
}

Os campos enviados podem variar conforme o tipo de transação, o método de pagamento e o evento processado.

Validar as notificações​

Ao receber uma notificação, o cliente deve:

  1. validar se a requisição possui o formato esperado;
  2. utilizar a Chave Secreta do merchant para validar o checksum;
  3. verificar se o evento já foi processado;
  4. registrar a atualização da transação de maneira idempotente;
  5. retornar um status HTTP 2xx quando a notificação for processada;
  6. retornar um status HTTP de erro quando a notificação não puder ser processada.

A validação do checksum ajuda a confirmar que a notificação foi gerada pela Orkestral e que os dados utilizados na assinatura são consistentes.

Boas práticas​

  • Utilize endpoints diferentes para os ambientes de homologação e produção.
  • Não utilize URLs locais, como localhost.
  • Mantenha o certificado HTTPS válido.
  • Responda rapidamente e processe tarefas demoradas de forma assíncrona.
  • Implemente idempotência utilizando os identificadores da transação e do evento.
  • Monitore erros HTTP, tempo de resposta e indisponibilidade.
  • Proteja a Chave Secreta utilizando um gerenciador de segredos.
  • Não confunda a Chave Secreta de validação das notificações com as credenciais de autenticação da API.