DocumentationAPI Reference
Documentation

Signature Calculation

Suggest Edits

payabl. uses signature as a security mechanism to prevent malicious payment requests. Every request should include a calculated signature from your server to payabl.
Signature is a sha1sum of all the parameters values sorted by parameter name and your secret. This ensures the origin of the request is really coming from your server and has not been tampered with.

Important to remember

  1. Parameters MUST NOT be URL encoded before signature calculation.
  2. The calculation of the signature value must be done dynamically for every single request which your send from your system to the payment gateway.
  3. If the signature is not calculated properly per request, the gateway will respond with error code -999 or -6000
  4. Please remember that the gateway does not accept requests with empty or malformed signatures. Empty or malformed signatures will be declined.

Signature for requests

For each request you need to send signature, please follow these steps to build a signature string in your code:

  • Sort parameters by parameter name in alphabetical order.
  • Append your secret to the end of the concatenated string.
  • Calculate a SHA-1 hex value of the string. This hash value must be in lowercase letters.
  • The “secret“ is known only by you and the the payment gateway. It must be exchanged by email or by phone.

The below you can see request example without signature. The request has all the parameters inside in random order. First of all, make sure that parameters not URL encoded.

merchantid=gateway_test&amount=1.23&currency=EUR&orderid=1234-123456789-4321&language=de&
gender=&lastname=Mustermann&street=Hanauer+Landstrasse&zip=60322&city=Frankfurt&country=DEU
&firstname=Max&company=Powerpay21&email=tech.support%40powerpay21.com&customerip=127.1.1.1
&payment_method=1&ccn=4242424242424242&cvc_code=123&cardholder_name=Max+Mustermann&exp_month=01&exp_year=2015

You need to sort parameters by parameter name in alphabetical order. Ideally, the parameters would be available in an array/hash to make manipulation easier and reduce code errors/repetition.

amount=1.23
cardholder_name=Max Mustermann
ccn=4242424242424242
city=Frankfurt
company=Powerpay21
country=DEU
currency=EUR
customerip=127.1.1.1
cvc_code=123
[email protected]
exp_month=01
exp_year=2015
firstname=Max
language=de
lastname=Mustermann
merchantid=gateway_test
orderid=1234-123456789-4321
payment_method=1
street=Hanauer Landstrasse
zip=60322

Append/Concatenate, the parameters values together according to the alphabetical sequence of parameter names. Input string for the SHA-1 function (not URL encoded) and add your secret to the end of the concatenated string (secret at the end of the string):

1.23Max Mustermann4242424242424242FrankfurtPowerpay21DEUEUR127.1.1.1123tech.support@powerpay21.com012015MaxdeMustermanngateway_test1234-123456789-43211Hanauer Landstrasse60322**VeryGoodSecret**

🚧

The “secret“ is known only by you and the payment gateway. It will be sent to you by email when onboarding complete.

Calculate a SHA-1 hex value of the string. This hash value must be in lowercase letters. SHA-1 hash value of the string above:

00f05286b075aecf621b5c3db67eb5d4f612e855

Request with signature

merchantid=gateway_test&amount=1.23&currency=EUR&orderid=1234-123456789-4321&language=de&
gender=&lastname=Mustermann&street=Hanauer+Landstrasse&zip=60322&city=Frankfurt&country=DEU
&firstname=Max&company=Powerpay21&email=tech.support%40powerpay21.com&customerip=127.1.1.1&payment_method=1&ccn=4242424242424242&cvc_code=123&cardholder_name=Max+Mustermann&exp_month=01&exp_year=2015&signature=00f05286b075aecf621b5c3db67eb5d4f612e855

Checkout pseudo code to calculate signature here:

// NOTE THIS CODE WILL NOT COMPILE, IT IS PSEUDOCODE

// WE HAVE PURPOSELY NOT OPTIMISED THIS CODE, SO IT IS AS SELF EXPLANATORY AS POSSIBLE

$signature = "";

// POST value validation / cleaning

// some code to check for legitimate values in the $_POST

$clean_post = clean_post($_POST);

// GENERATE THE SIGNATURE

// 1) Sort the parameters alphabetically (by key value)

key_sort($clean_post);

// 2) Use a foreach to loop through the POST array.

foreach( $clean_post as $key => $val )

{

// 3) Concatenate each value. Do not include the signature parameter.

if( $key != "signature" )

{

$signature .= $val;

}

}

// 4) Append the secret.

$signature .= "VeryGoodSecret";

// 5) Calculate SHA-1 checksum in lowercase characters.

$signature = lower_case ( sha1_hex( $signature ) );

If you have problems to calculate the correct signature, please check these steps:

  • The signature parameter has to be in hexadecimal format.
  • The hexadecimal string has to be written in lower-case letters.
  • Please make sure that the parameters are not URL encoded before signature calculation.
  • Please check that all parameter values are included in the signature calculation.
  • The secret must be appended to the SHA-1 function input string.

Simplified Signature for notifications

The simplified signature can be used ONLY for payabl. notifications.

We have implemented a simplified security parameter calculation based on a fixed sequence and set parameters, such notification has an additional parameter timestamp.
Parameters list will be strict now and include only:

  • transactionid
  • type
  • errorcode
  • timestamp
  • your_secret

Notification example 

expiry_year=2023&timestamp=1610018172&ccn_four=3036&transactionid=118656640&
cardholder=Muster+Mann&bin=513646&security=1f67d79aa5e2a4070b2091837fefae84cd15f08370de0cee4bf9ea75951e047b&errorcode=0&orderid=991135&type=capture&expiry_month=10&errormessage=

So the notification example above evaluates to: (secret=goodsecret)

sha256 (118656640capture01610018172goodsecret )

In this case security parameter will be the following:

1f67d79aa5e2a4070b2091837fefae84cd15f08370de0cee4bf9ea75951e047b

Updated 6 months ago