Saltar al contenido principal

Clave secreta y URL de notificación

Esta guía explica cómo consultar la Clave secreta del comercio y configurar la URL utilizada por Orkestral para enviar actualizaciones de las transacciones.

La URL de notificación funciona como el webhook del cliente.

Antes de comenzar​

Para realizar la configuración, es necesario:

  • tener una cuenta activa en Orkestral;
  • tener acceso a la plataforma de gestión;
  • estar vinculado al comercio que se configurará;
  • disponer de una URL pública y accesible para recibir las notificaciones.

Acceder a la configuración de integración​

  1. Accede a la plataforma de Orkestral.
  2. En el menú lateral, haz clic en Integración.
  3. Introduce nuevamente la contraseña de tu usuario.
  4. Haz clic en Enviar.

Después de validar la contraseña, la plataforma muestra la Clave secreta y la configuración de la URL de notificación.

Clave secreta​

¿Qué es la Clave secreta?​

La Clave secreta es una credencial asociada al comercio. Se genera automáticamente cuando se crea el comercio y es compartida por los usuarios vinculados a él. Por lo tanto, no se crea una clave diferente para cada usuario de la plataforma.

Orkestral utiliza esta clave para generar el checksum incluido en las notificaciones de las transacciones. El cliente puede utilizarla para validar la autenticidad de las notificaciones recibidas, de acuerdo con el contrato de integración de la API.

info

La Clave secreta mostrada en esta página no sustituye al token de acceso utilizado en las llamadas a la API. La autenticación de las APIs de Orkestral utiliza OAuth y tokens JWT.

Consultar la Clave secreta​

  1. Accede al menú Integración.
  2. Introduce nuevamente la contraseña de tu usuario.
  3. Localiza la sección Clave secreta.
  4. Utiliza el botón de copia para copiar el valor mostrado.
  5. Guarda la clave en un lugar seguro.

Proteger la Clave secreta​

  • No compartas la clave por correo electrónico, mensajes o canales públicos.
  • No almacenes la clave directamente en el código fuente.
  • No expongas la clave en aplicaciones frontend.
  • No registres la clave en logs.
  • Utiliza un gestor de secretos o una variable de entorno protegida.
  • Restringe el acceso a los servicios responsables de validar las notificaciones.
aviso

La plataforma no permite regenerar o rotar la clave desde la interfaz. Si la clave se expone o se ve comprometida, contacta al equipo responsable de Orkestral.

URL de notificación​

¿Qué es la URL de notificación?​

La URL de notificación es la dirección utilizada por Orkestral para informar al cliente sobre las actualizaciones de las transacciones.

Por ejemplo, se puede enviar una notificación cuando una transacción sea aprobada, rechazada, liquidada o tenga otro cambio de estado relevante.

Orkestral envía una solicitud HTTP POST, con contenido en formato JSON, a la URL seleccionada.

Registrar la URL​

  1. Accede al menú Integración.

  2. Introduce nuevamente la contraseña de tu usuario, si se solicita.

  3. Localiza la sección URL.

  4. Introduce la dirección completa del webhook, por ejemplo:

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

  5. Haz clic en el botón de confirmación para guardar.

  6. Comprueba que la URL registrada se haya actualizado correctamente.

Requisitos recomendados​

La URL debe:

  • ser pública y accesible desde internet;
  • utilizar HTTPS;
  • aceptar solicitudes HTTP POST;
  • aceptar contenido application/json;
  • devolver un estado HTTP de éxito de la familia 2xx;
  • procesar las notificaciones de forma idempotente;
  • validar el checksum recibido;
  • no depender de una sesión autenticada en el navegador;
  • contar con monitorización de errores e indisponibilidad.
nota

Aunque se recomienda HTTPS para proteger los datos transmitidos, la interfaz actual no valida explícitamente el protocolo informado.

URL predeterminada y URL por transacción​

Orkestral permite definir la URL de notificación en el comercio o directamente en la transacción.

URL registrada en el comercio​

La URL registrada en la página Integración funciona como el webhook predeterminado del comercio. Se utiliza cuando una transacción no tiene una URL específica.

URL informada en la transacción​

Al crear una transacción, el cliente también puede informar el campo webhook_url:

{
  "webhook_url": "https://api.ejemplo.com/webhooks/transaccion"
}

Cuando se informa este campo, su URL se utiliza para la transacción correspondiente.

Orden de prioridad​

Orkestral utiliza el siguiente orden:

  1. el webhook_url informado al crear la transacción;
  2. la URL registrada en el comercio mediante la página Integración.

Si ninguna de las dos URLs está configurada, Orkestral no tendrá una dirección válida para entregar la notificación al cliente.

Contenido de la notificación​

La notificación puede contener información como:

  • identificador del comercio;
  • identificador de la transacción;
  • importe y moneda;
  • país de la transacción;
  • método de pago;
  • identificador del evento;
  • nombre o estado del evento;
  • mensaje devuelto por el proveedor de servicios de pago;
  • checksum de seguridad.

Ejemplo 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-del-checksum"
}

Los campos enviados pueden variar según el tipo de transacción, el método de pago y el evento procesado.

Validar las notificaciones​

Al recibir una notificación, el cliente debe:

  1. validar que la solicitud tenga el formato esperado;
  2. utilizar la Clave secreta del comercio para validar el checksum;
  3. comprobar si el evento ya fue procesado;
  4. registrar la actualización de la transacción de forma idempotente;
  5. devolver un estado HTTP 2xx cuando se procese la notificación;
  6. devolver un estado HTTP de error cuando la notificación no pueda procesarse.

La validación del checksum ayuda a confirmar que Orkestral generó la notificación y que los datos utilizados en la firma son consistentes.

Buenas prácticas​

  • Utiliza endpoints diferentes para los entornos de pruebas y producción.
  • No utilices URLs locales, como localhost.
  • Mantén válido el certificado HTTPS.
  • Responde rápidamente y procesa las tareas de larga duración de forma asíncrona.
  • Implementa idempotencia utilizando los identificadores de la transacción y del evento.
  • Monitoriza errores HTTP, tiempo de respuesta e indisponibilidad.
  • Protege la Clave secreta con un gestor de secretos.
  • No confundas la Clave secreta para validar notificaciones con las credenciales de autenticación de la API.