How it works

Basically a list of parameters and a secret is used to calculate a hash. This hash is then sent along with the “payment request”. On the RaiseNow Platform, the same list of parameters (from the request) and the same secret are used to calculate the same hash. If the hash provided in the request and the hash calculated are equal the transaction is accepted. If not this indicates an attack and no transaction is processed.

In the return request, it works the other way around. RaiseNow uses a list of parameters and the secret to get the hash and sends it along to the return url. The merchant then can calculate the hash itself and verify that it equals the hash provided by RaiseNow.

For this to work a merchant must decide a number of things (fields/parameters to use, secret, hash algorithm) and let RaiseNow Support configure the merchants account accordingly.

Define Fields 

First a merchant needs to decide which fields should be included in the HMAC signature. Per default these are only: amount, currency, test_mode (in initial request) and epp_transaction_id, [hmac,] amount, currency, test_mode, epayment_status (in the return request). To prevent against replay attacks it is recommended to add a “time” field (e.g. stored_transaction_time).

For this tutorial let’s assume we chose the following fields for the initial request:

• amount

• currency

• test_mode

• stored_transaction_time (unix timestamp)

• stored_product* (every field starting with stored_product)

• stored_customer* (every field starting with stored_customer)

For the return request:

• epp_transaction_id

• amount

• currency

• test_mode

• epayment_status

• stored_transaction_time (unix timestamp)

• stored_product* (every field starting with stored_product)

• stored_customer* (every field starting with stored_customer)

• hmac (This is only used if the hmac signature in the initial request was valid)

Note that we include stored_product and stored_customer in the response hmac as well. Depending on the architecture of the checkout process and the online shop, this might or might not be necessary. A merchant is recommended to use webhooks (which provide signatures as well) to validate a transaction before sending goods out.

Choose a Hash Algorithm 

Second the merchant needs to choose a secret (a “long” string). This secret should be protected at all times. The security of the hmac signatures relies upon the fact that the secret is indeed secret and only known to the two parties (merchant, raisenow) involved. Once an attacker knows the secret, she would be able to modify the request and recalculate the hmac signature and the attack would not be detectable anymore.

For this tutorial we choose “secretyoumustbe” as our secret.

Define Contexts 

HMAC signatures can be used in 3 different context:

• transaction (for normal one-shot transactions)

• subscription (for recurring transactions)

• resubscription (for changing recurring subscriptions)

In a typical shop only the transaction context is required. So for this tutorial we only need “transaction” context.

Let RaiseNow support setup the Configuration 

RaiseNow needs to setup the system with the merchants chosen settings. (At the moment merchants are not allowed to setup hmac signature feature themselves). Please contact support@raisenow.com.

Once everything is setup we are ready to implement and test.