Hosted Payments Message Authentication Code (MAC)

Hosted Payments

Print Friendly, PDF & Email

Message Authentication Code (MAC)

All merchant requests must include a signature parameter to verify the authenticity of the message and the sender.

To generate the signature, combine parameter values of the request in alphabetical order, by parameter name, along with the merchant authkey (provided to the merchant by Snap* Hosted Payments); then, hash the string using an MD5 hash.

 

Example:

 

Assuming the parameters for the Snap* Hosted Payments request are as follows:

    • - code = merchant
    • - action = get_order
    • - return = json
    • - merchant_order_id = 808
 

And assuming the merchant’s authkey is “12345678”, a signature can be generated using the following PHP code:

?php
// private key known only to merchant and Snap* Hosted Payment
$authkey = "12345678";

// parameters and values
$code = “merchant”;
$action = “get_order”;
$return = “json”;
$merchant_order_id = “808”;

// concatenate the parameter values in alphabetical order by parameter name
$plain = $action.$code.$merchant_order_id.$return;

// then add the private authkey
$plain.= $authkey;

// now generate the signature using the md5() function
$signature = md5($plain);
?
 

Another example of PHP code for generating a MAC signature:

?php
// private key known only to merchant and Snap* Hosted Payment
$authkey = "12345678";

// parameters and values
$code = “merchant”;
$email = “carissa@pycroft.com”;
$merchant_order_id = “100000546”;
$order_total_subtotal = “19.99”;
$order_total = “21.99”;

// concatenate the parameter values in alphabetical order by parameter name
$plain = $code.$email.$merchant_order_id.$order_total.$order_total_subtotal;

// then add the private authkey
$plain.= $authkey;

// now generate the signature using the md5() function
$signature = md5($plain);
?
SECURITY WARNING: In order to prevent the merchant authkey from being vulnerable to security threats, Snap* recommends generating the hash by a server-side script where the authkey is only known behind the script versus creating the hash in the browser (e.g.: JavaScript).
 
IMPORTANT! While generating the MAC signature any total and total_subtotal fields should be formatted with commas between every group of thousands. This is only for MAC generation, any total or total_subtotal fields in the body of the request should remain as decimal numbers with no comma separators.
 
IMPORTANT! Due to the large number of parameters passed when a checkout POST is sent to Snap* Hosted Payments, the list below contains the parameters that must be used when generating the MAC signature.

For each of the API actions the Merchant code, Merchant authkey, API action and all required action-specific parameters should be used to generate the MAC signature. The Merchant authkey is expected as the last parameter of every MAC signature prior to encoding.

There should be no spaces between the parameters when they are concatenated into a string.

 

Use the following parameters in the sequences listed to generate the MAC signature:

 
Checkout Type MAC parameters (in sequence)
Order only code + customer[email] + order[merchant_order_id] + order[total] + order[total_subtotal] + authkey
Subscription only code + customer[email] + sub[merchant_subscription_id] + sub[total] + sub[total_occurrences] + sub[total_subtotal] + sub[trial_amount] + sub[trial_occurrences] + authkey
Order + Subscription code + customer[email] + order[merchant_order_id] + sub[merchant_subscription_id] + order[total] + order[total_subtotal] + sub[total] + sub[total_occurrences] + sub[total_subtotal] + sub[trial_amount] + sub[trial_occurrences] + authkey
Token only code + customer[email] + token[merchant_token_id] + authkey
 
API Action Fields
chargeback action + merchant_code + merchant_order_id + txn_id + chargeback_txn_id + merchant_authkey
credit action + merchant_code + merchant_order_id + txn_id + merchant_authkey
process_token action + merchant_code + merchant_token_id + merchant_authkey
get_token action + merchant_code + merchant_token_id + merchant_authkey
process_subscription action + merchant_code + merchant_subscription_id + merchant_authkey
suspend_subscription action + merchant_code + merchant_subscription_id + merchant_authkey
resume_subscription action + merchant_code + merchant_subscription_id + merchant_authkey
cancel_subscription action + merchant_code + merchant_subscription_id + merchant_authkey
get_subscription action + merchant_code + merchant_subscription_id + merchant_authkey
insert_order action + merchant_code + merchant_order_id + merchant_authkey
update_order action + merchant_code + merchant_order_id + merchant_authkey
get_orders action + merchant_code + merchant_authkey
get_order action + merchant_code + merchant_order_id + merchant_authkey
get_order_by_txn_id action + merchant_code + txn_id + merchant_authkey
get_callbacks action + merchant_code