Introduction


The hash value protects the request parameters from changes by the customer, e.g. price changes.

The hash value is calculated from

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: 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:

---end

PMI, configuration, payment portals, hash calculation
PMI-Selection Meaning

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)

---end

Parameters included in hash calculation

The following parameter values must be included in the HASH value (when they're part of the request): 

---end

parameters to include in hash in alphabetical order
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.

---end

available Parameter
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

---end of collapsable content

---end

PAYONE Platform expects the calculated hash value converted to lower case; e.g.  d0ff16426ec9071cfe12c4440738875f...caf28c5ac9abb52b5d (“sha2-384”).

---end

An example in PHP 
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 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!

---end