CinetPay X-TOKEN HMAC


Context

In the process of verifying payments, CinetPay implements a notification mechanism that consists in contacting the partner on a Webhook, in order to send him the information of a payment whose status has changed. For security purposes, an HMAC token has been implemented in the header of this notification to allow verification on the partner's side.

The purpose of this turorial is to describe the process for verifying the HMAC token.

Before proceeding to go, you need to retrieve your Secret Key in your merchant account:

  • Go to www.cinetpay.com/login and log in with your access details
  • Then click on the "Integrations" menu
  • You will find your Secret Key there

Scenario

scenario-hmac

The server executes a POST request on your notification url containing :

  • Headers:

    • x-token : An HMAC token to allow verification on the partner's side.
  • Form values:

    • cpm_trans_id: the transaction_id variable that you sent at initialization
    • cpm_site_id: the site_id variable you sent at initialization
    • cpm_trans_date: the date and time of the transaction
    • cpm_amount: the amount
    • cpm_currency: the currency
    • signature : A token. It is different from the generated token
    • payment_method : the payment method
    • cel_phone_num: the number used to make the payment
    • cpm_phone_prefixe: the country prefix
    • cpm_language: the language in which the payment was made
    • cpm_version: the version used (V4)
    • cpm_payment_config: the type of payment (Single)
    • cpm_page_action : the type of action (Payment)
    • cpm_custom : the metadata you sent at initialization
    • cpm_designation : the designation you sent at initialization

Step to create the token

Step 1

The token is constituted by concatenation of the information received in the body of the request. Thus, you must formulate a character string by respecting the diagram below presented:

cpm_site_id + cpm_trans_id + cpm_trans_date + cpm_amount + cpm_currency + signature + 
payment_method + cel_phone_num + cpm_phone_prefixe + cpm_language + cpm_version 
+ cpm_payment_config + cpm_page_action + cpm_custom  + cpm_designation  


Example with php

$data = $cpm_site_id . $cpm_trans_id . $cpm_trans_date . $cpm_amount . $cpm_currency . 
$signature . $payment_method . $cel_phone_num . $cpm_phone_prefixe . 
$cpm_language . $cpm_version . $cpm_payment_config . $cpm_page_action . $cpm_custom . $cpm_designation; 

Step 2

Create the token following the HMAC technique by applying the SHA256 algorithm with the secret key (which will be communicated to you).


Example with php

$token = hash_hmac(‘SHA256’, $data, $secretKey);

Step 3

The step consists in checking that the token received in the header corresponds to that which you will have generated.


Example with php

if(hash_equals($received_token, $generated_token)) 
{
      // Valid Token
}