CinetPay X-TOKEN HMAC

• Context
• Scenario
• Step to create the token

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

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_site_id: the site_id variable you sent at initialization
  • cpm_trans_id: the transaction_id variable that 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
  • cpm_error_message : the status of the transaction. If there is an error, you have the reason for the failure

Step to create the token

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 + cpm_error_message 

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 . $cpm_error_message; 

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);

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
}