- Created by PAYONE Admin, last modified on 2021-10-25
Introduction
The hash value protects the request parameters from changes by the customer, e.g. price changes.
The hash value is calculated from
- the request parameters
- standard parameters -> see CA - General Interface Definitions
- request parameters in hash → see CalculationoftheHASHvalue-Parametersincludedinhashcalculation
- and the secret key
using the hash function hash(“md5” , $data) or hash_hmac(“sha2-384”, $data, $key).
Any parameter values to be protected are concatenated in alphabetical order. So by this e.g. the amount, basket and your reference are protected. Lastname and bankdata are not protected as they are subject to change by the customer.
Finally the key will be attached to the string and the hash value is calculated.
Parameters are sorted by their name. It does not matter in which order they are used in the request URL. See below table for the parameters to be protected.
Hash-method: MD5 or SHA2-384
You can assign the key to be used in the PMI (PAYONE Merchant Interface). Do not pass this key to third parties in any case. You can also choose the desired hash algorithm in the PMI:
PMI, configuration, payment portals, hash calculation
PMI-Selection | Meaning |
md5 (current method) | PAYONE platform expects hash value as md5 (md5 is compromised and should be replaced by sha2-384) for compatibility reason this is currently default. we strongly advise you use sha2-384 for new projects and migrate away from md5 for legacy projects. md5 is not a secure hashing function. |
sha2-384 (recommended method) | PAYONE platform expects hash value as sha2-384 (if you want to use sha2-384 hash values this option has to be activated) |
md5_or_sha2-384 (during migration) | PAYONE platform accepts both hash calculations (md5 and sha2-384) (this option should only be used for migration from md5 to sha2-384) |
Parameters included in hash calculation
The following parameter values must be included in the HASH value (when they're part of the request):
Remember: If it's part of your request, you need to include it in your hash.
[x] always means that all elements of the given array have to be part of the hash.
access_aboperiod access_aboprice access_canceltime access_expiretime access_period access_price access_starttime access_vat accesscode accessname addresschecktype aid amount amount_recurring amount_trail api_version autosubmit backurl booking_date cavv checktype clearingtype consumerscoretype currency customer_is_present customerid de[x] de_recurring[x] de_trail[x] display_address display_name document_date due_time eci ecommercemode encoding errorurl exiturl frontend_description getusertoken id[x] id_recurring[x] id_trail[x] invoice_deliverydate invoice_deliveryenddate invoice_deliverymode invoiceappendix invoiceid it[x] mandate_dateofsignature mandate_identification mid mode narrative_text no[x] no_recurring[x] no_trail[x] param period_length_recurring period_length_trail period_unit_recurring period_unit_trail portalid pr[x] pr_recurring[x] pr_trail[x] productid recurrence reference request responsetype settleaccount settleperiod settletime storecarddata successurl targetwindow ti[x] ti_recurring[x] ti_trail[x] userid va[x] va_recurring[x] va_trail[x] vaccountname vreference xid
PAYONE Platform expects the calculated hash value converted to lower case; e.g. 87dbc7c369b85b7a699adff1a2b27bab (“md5”) or d0ff16426ec9071cfe12c4440738875f...caf28c5ac9abb52b5d (“sha2-384”).
An example in PHP
// Standard parameter
$request="authorization"; // mandatory: Type of request
$mid=10001; // mandatory: Your Merchant Account ID
$portalid=2000001; // mandatory: Your Portal ID
$aid=10002; // mandatory: Your Sub Account ID
$mode="test"; // mandatory: Mode of transaction (either "test" or "live")
$api_version="3.11"; // recommended: API version to be used; it's recommended to use the newest version
$key="secret"; // mandatory: Your Key (configurable in the PMI -> configuration -> payment portal)
$responsetype="REDIRECT"; // Response type
// Basket
$id[1]="123-345"; // optional: Your item no.
$pr[1]=5900; // optional: Price in cent
$no[1]=1; // optional: Amount
$de[1]="Puma Outdoor"; // optional: Item description
$va[1]=19; // optional: Percentage of value added tax (option)
// Payment
$amount=round($pr[1]*$no[1]);// mandatory: Total
$currency="EUR"; // mandatory: Currency
$reference="73464354"; // mandatory: Merchant Reference no.
$customerid="123456"; // recommended: Merchant customer no. (option)
// usage of md5-hash
// select “md5” in PMI-portal-settings
// $hash=md5($aid . $amount . $api_version . $currency . $customerid . $de[1] .
// $id[1] . $mid . $mode . $no[1] . $portalid . $pr[1] . $reference .
// $request . $responsetype . $va[1] .
// $key); // Parameters in sorted order + key
// usage of sha2-384-hash
// select "sha2-384" in PMI-portal-settings
$hash=hash_hmac("sha384", $aid .
$amount .
$api_version .
$currency .
$customerid .
$de[1] .
$id[1] .
$mid .
$mode .
$no[1] .
$portalid .
$pr[1] .
$reference .
$request .
$responsetype .
$va[1], // Parameters in sorted order
$key); // $key is an individual parameter in sha2-384!
- No labels