Generating HMAC Signatures

ℹ️

To improve the security of your standalone widget integration, Paybis requires an HMAC (Hash-based Message Authentication Code) signature to be included in the widget URL. This signature verifies the authenticity of the request and prevents unauthorized modifications.

❗️

Important: Signature verification must be enabled for your product by integration manager to utilize Standalone integration.

Steps to Generate the Signature

1. Obtain HMAC Key: Your Paybis account manager will provide you with a unique HMAC key.

   1. Your Paybis integration manager will share this key with you through a secure channel (e.g., 1Password storage).

2. Construct the URL: Create the URL for the payment widget, preferably on your backend server, for increased security.

3. Prepare the Message: Extract the query string from the URL, including the question mark (e.g., ?partnerId=UUID&partnerUserId=UUID&transactionFlow=buyCrypto).

4. Generate the Signature: Use the following code examples to generate the HMAC signature:

   PHP and JavaScript Examples:

   PHPJavaScript

   $message = '';   // query string
   $key = '';       // hmac key
      
   $signature = base64_encode(hash_hmac('sha256', $message, base64_decode($key), true));
      
   var_dump('Generated signature: ' . $signature);
   var_dump('Encoded signature: ' . urlencode($signature));
   

   const crypto = require("crypto");
      
   const message = ''; // query string
   const key = '';     // hmac key
      
   const decodedKey = Uint8Array.from(atob(key), c => c.charCodeAt(0));
      
   crypto.subtle.importKey(
      "raw",
      decodedKey,
      { name: "HMAC", hash: { name: "SHA-256" } },
      false,
      ["sign"]
   ).then((cryptoKey) => {
      const encoder = new TextEncoder();
      const data = encoder.encode(message);
      
      const signature = crypto.subtle.sign("HMAC", cryptoKey, data).then((signature) => {
          const base64Signature = btoa(String.fromCharCode(...new Uint8Array(signature)));
          const encodedSignature = encodeURIComponent(base64Signature);
      
          console.log('Generated signature: ' + base64Signature);
          console.log('Encoded signature: ' + encodedSignature);
      });
   });
   

5. Append Signature to URL: The generated signature must be appended to the standalone widget integration link as a URL-encoded query parameter named signature

ℹ️

For a complete list of available parameters, please refer to the Web Direct URL Standalone Integration documentation

Example:

https://widget.paybis.com/?partnerId=UUID&partnerUserId=12345&transactionFlow=buyCrypto&signature=YOUR_ENCODED_SIGNATURE

Endpoint Behavior Based on Product Settings

Important Notes

• Ensure the signature is generated on your backend for security reasons.
• The signature parameter should be URL-encoded.
• Paybis will verify the signature when the widget is initialized.

ℹ️

By following these steps, you can enhance the security of your standalone widget integration and protect your users from potential threats.