DocumentationAPI Reference

Signature Calculation2

Learn how to calculate signatures to send API requests.

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 alphabetically by parameter name and your secret added to the end. This ensures the origin of the request is really coming from your server and has not been tampered with.

API credentials include Merchant ID and a Secret word that should be added to your signature. Sandbox credentials are available here for Credit Cards and here for Alternative Payment methods. Production credentials will be sent to you upon finishing your onboarding process.

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.

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.

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.

Request without signature

merchantid=gateway_test&orderid=Payabl-Test&amount=19.99&currency=EUR&payment_method=1&language=en&
customerip=93.109.250.238&[email protected]&firstname=John&lastname=Doe&zip=3035&street=Olympion&
house=23&city=Limassol&country=CYP&ccn=4012001036298889&exp_month=12&exp_year=2027&cvc_code=345&
cardholder_name=John Doe&param_3d=non3d&url_return=https://yourshop.example/thank_you&
notification_url=https://yourshop.example/notification

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=19.99
cardholder_name=John Doe
ccn=4012001036298889
city=Limassol
country=CYP
currency=EUR
customerip=93.109.250.238
cvc_code=345
[email protected]
exp_month=12
exp_year=2027
firstname=John
house=23
language=en
lastname=Doe
merchantid=gateway_test
notification_url=https://yourshop.example/notification
orderid=Payabl-Test
param_3d=non3d
payment_method=1
street=Olympion
url_return=https://yourshop.example/thank_you
zip=3035

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 (the secret for merchantid gateway_test is b185):

19.99John Doe4012001036298889LimassolCYPEUR93.109.250.238345test@payabl.com122027John23enDoegateway_testhttps://yourshop.example/notificationPayabl-Testnon3d1Olympionhttps://yourshop.example/thank_you3035b185

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:

41223dcc56eb633633ce0358d5702ba680a73ac9

Request with signature

https://sandbox.payabl.com/pay/backoffice/payment_authorize?merchantid=gateway_test&orderid=Payabl-Test&amount=19.99&
currency=EUR&payment_method=1&language=en&customerip=93.109.250.238&[email protected]&firstname=John&lastname=Doe&
zip=3035&street=Olympion&house=23&city=Limassol&country=CYP&ccn=4012001036298889&exp_month=12&exp_year=2027&cvc_code=345&
cardholder_name=John Doe&param_3d=non3d&notification_url=https://yourshop.example/notification&url_return=https://
yourshop.example/thank_you&signature=41223dcc56eb633633ce0358d5702ba680a73ac9

Check out 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 provided a wrong signature, our system will return the error -999 Unknown error.

In this case, if you have problems with calculating 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.

Signature for notifications

When sending callbacks from payabl. side we add a signature based on a fixed sequence and set parameters.

Parameters list is strict and includes 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 4 months ago