Guía Firma de Seguridad

Este campo garantiza la integridad de las peticiones realizadas a nuestros servicios. Además le permite a los comercios controlar el límite de solicitudes hechas a las APIs transaccionales por un usuario específico.

Para utilizar estos servicios es necesario incluir la Firma de Seguridad:

  • API api/v2/transaction/other o hosted/payment/other
  • SDK doSale o API api/v2/transaction/sale
  • SDK doAuth o API api/v2/transaction/auth
  • SDK doCapture o API api/v2/transaction/capture
  • SDK getStatus o API api/v2/transaction/status

Campos Necesarios

Según el servicio que se está implementando, se debe generar la firma con algunos de los campos enviados en la petición:

  • app_key: el identificador de tu comercio, puedes extraerlo aquí
  • order_id: el número de órden de la transacción que quieres firmar
  • app_url: la plataforma de tu comercio, puedes extraerla aquí
  • secret_key: la llave secreta de tu comercio, puedes extraerla aquí

Para casos más avanzados, también puedes necesitar incluir otros campos en la firma:

  • transaction_approved_amount: para transacciones de captura de fondos, este es el monto total a capturar
  • payment_uuid: para transacciones de captura de fondos o estatus de un cobro, este es el identificador del pago
Servicio Campos Necesarios
API api/v2/transaction/other
API hosted/payment/other
API api/v2/transaction/sale
API api/v2/transaction/auth
SDK doSale
SDK doAuth		 app_key, order_id, app_url
API api/v2/transaction/capture
SDK doCapture		 app_key, transaction_approved_amount, payment_uuid, app_url
API api/v2/transaction/status
SDK getStatus		 app_key, payment_uuid, app_url

Creación de Firma

Una vez identificado el servicio y los campos necesarios para firmar tu petición, debes concatenar en una cadena todos los campos con el símbolo |. Esta cadena luego debe ser procesada a través de HMAC con el algoritmo SHA3-512, utilizando el secret key para firmarlo.

Ya que la creación de la firma implica hacer uso del secret key, procura hacerlo en un ambiente controlado como un servidor o API interna, y no dentro del dispositivo del usuario. Si sospechas que tu secret key se ha expuesto, puedes ver como crear uno nuevo aquí.

Por ejemplo, al crear una firma para una transacción al servicio de Venta Directa con número de órden ORDER-8888 y datos de un comercio ficticio, el resultado debe ser 688084a6...e852ee2a:

<?php // Credenciales de sandbox, cambia los datos por los de tu comercio $app_key = "1234567890"; $order_id = "ORDER-8888"; $app_url = "https://pixelpay.dev"; $secret_key = "@s4ndb0x-abcd-1234-n1l4-p1x3l"; echo hash_hmac( "sha3-512", implode("|", [$app_key, $order_id, $app_url]), $secret_key ); import { createHmac } from "crypto"; // Credenciales de sandbox, cambia los datos por los de tu comercio const app_key = "1234567890"; const order_id = "ORDER-8888"; const app_url = "https://pixelpay.dev"; const secret_key = "@s4ndb0x-abcd-1234-n1l4-p1x3l"; const signature = createHmac("sha3-512", secret_key) .update([app_key, order_id, app_url].join("|")) .digest("hex"); console.log(signature);

Envío de Firma

Cuando ya hemos creado la firma, esta se debe de enviar en la petición en el encabezado x-client-signature. Si utilizas los servicios del SDK, puedes ver aquí como agregar este encabezado a tus peticiones.