5a. Securing Embedded UIs Using HMAC (deprecated)

HMAC-based security has been deprecated and will be removed in a future release. To secure your web components, please refer to the Embedded UIs using merchant session.

Overview

The Embedded UIs / Web-Components allow you to ease integration of our widgets to be used by your customers. Because it's provided for you via our web-components and tied directly to our server, you never have to worry about the heavy lift of UI development while maintaining full control over its theming and other customizations.

Our Embedded UIs / Web-Components have a simple HTML/Javascript embed so it can be embedded onto any part of your web applications that requires user interaction with payment-related parts of your system. It authorizes users with a security hash generated with the logged-in user's email. This method of authorization allows web-components to work with any authentication provider.

This platform uses two methods for securing web-components. Depending on the web-component and the type of data used, the implementation will vary between one or the other.

HMAC-based client side

HMAC is a computed "signature" sent along with some data. The HMAC is used to verify (authenticate) that the data has not been altered or replaced. The process involves an exchange of a secret key, which is then used to hash a message. The secret key should never be shared or made publicly available. This method ensures that the request information in fact was originated from your servers.

Webhooks-based data pinning

In addition to the HMAC method described above, some of our web-components also require data-pinning. For some of the components you will be expected to provide a self-generated reference ID which our webhooks system will then use on the back-end to retrieve additional information. An example of this is our payment form web-component, where it's essential that the users don't temper with the pre-set amounts they need to be charged. This will allow you to pass a reference ID to our payments for web component and expect a web-hooks API to exist within your system that will provide the actual amount that should be enforced on a transaction.

Embedding

Embedding the Embedded UIs / Web-Components is a two-step process.

1. For the client side installation, just copy and paste the provided HTML snippet from your developer portal.

2. The next step is to secure the setup.

Authenticating Secure Setup

The customer portal must be behind some kind of user authentication in order to safely show customers their payment information. This platform authenticates users with an HMAC hash generated for the logged-in user. This allows us to work with any authentication system.

Your code for generating an HMAC for your app must be placed in the back-end of your application. Grab the snippet from the developer dashboard to add to your server. You may generate the HMAC with the Merchant ID.

The HMAC generated will be passed to the client-side snippet to a property called 'hash'.

Node.js

const crypto = require("crypto");
const merchant_id_hash = crypto.createHmac(
    "sha256",
    "YOUR_SECRET_KEY" // SECRET KEY (KEEP SAFE!)
).update(<merchant_id>).digest("hex") // PASS THIS TO FRONT-END

Rail Ruby

merchant_id_hash = OpenSSL::HMAC.hexdigest(
    'sha256', # HASH FUNCTION
    <YOUR_SECRET_KEY>, # SECRET KEY (KEEP SAFE!)
    <merchant_id>, # REPLACE WITH MERCHANT ID
) # PASS THIS TO FRONT-END

Django (Python)

import hmac
import hashlib

merchant_id_hash = hmac.new(
    'YOUR_SECRET_KEY', # SECRET KEY (KEEP SAFE!)
    <merchant_id>, # REPLACE WITH MERCHANT ID
    digestmod=hashlib.sha256 # HASH FUNCTION
).hexdigest() # PASS THIS TO FRONT-END

PHP

$merchant_id_hash = hash_hmac(
    'sha256', // HASH FUNCTION
    <merchant_id>, // REPLACE WITH MERCHANT ID
    'YOUR_SECRET_KEY' // SECRET KEY (KEEP SAFE!)
); // PASS THIS TO FRONT-END

Other

Generate an HMAC with SHA256 whenever a user logs into your app. Most web frameworks will have a method or library to help you do this. You'll need your app’s secret key and the Merchant ID.

Keep your secret key safe! Never commit it directly to a public repository, client-side code, or anywhere a third party can find it.