How to setup Encrypted URL Parameters

Encrypted URL Parameters are similar to Dynamic URL Parameters except they are encrypted and not human-readable.  This means they cannot be tampered with by website visitors - making them more secure and useful.

See procedure Which parameters can I use with the various URL Parameter options for a list of parameters that work with Encrypted URL Parameters

We provided a number of ways of generating Encrypted URL Parameters.  These are documented in this procedure below.  The options are:

  1. Enter details in the URL Tokens.  Select "Create Encrypted URL Parameters".   This is the simplest option, but provides limited advantages over standard URL Tokens.
  2. Using Process Builder to generate and save the Encrypted URL Parameters.  This option is very flexible, but requires medium to advanced Salesforce Admin skills.
  3. Generating Encrypted URL Parameters with Javascript.  This is for web developers so they can generate secure links from lead-in forms to Payments2Us forms.

Encrypted URL Parameters is currently in beta.  This means it is fully working, but we may make adjustments based on customer feedback.

1. Setup for using Encrypted URL Parameters

Make sure the Payment Form being used has a value in the "URL Encrypted Parameters Key".  This value must be exactly 32 characters long.

If you simply do an edit/save on the Payment Form, it will dynamically create the URL Encrypted Parameters Key.

2. Generating an Encrypted URL Parameter from a URL Token

This method is the simplest way of creating an Encrypted URL Parameter.  

Create a New URL Token, enter the defaults you wish to use.  It is recommended that the Merchant Facility and Payment Form are entered.

Select the "Create URL Encrypted Parameter" checkbox.

On save, the URL Encrypted Parameters are generated.

3. Generating an Encrypted URL Parameter using Process Builder

3.1. Creating a sample Process Builder to generate Encrypted URL Parameters

Process builder provides a simple and flexible method for generating URL parameters and associating this with any object in Salesforce.

The below example is for generating an Encrypted URL Parameter and saving this to the URL Tokens object.  This should not be confused with the URL Token process described above; this example just happens to be producing a similar result with the Process Builder technique instead of the inbuilt option for URL Tokens.

To start this process go to setup (cog top right hand corner) > search "Process Builder".  Click into Process Builder and press the "New" button.

  • Enter name "GenerateEncryptedURLParams".  Process Starts "When a Record Is Changed".  "Save" Button
  • Object "URL Token".  When a record is created or edited. "Save" Button.
  • Decision. Name "When missing Encrypted URL Parameters".  Criteria "URL Parameters" equals Global Constant "Null".  "Save" button.
  • Add Action.  Action Type "Apex". Name "Generate Encrypted URL Parameters".  Search "Payments2us" and select "Payments2Us Encrypted URL Parameters".
  • Add Rows:
    • SObjectToUpdateAPIName.  Set to String "AAkPay__URL_Tokens__c".  This is the API name of the Sobject you wish to update.
    • SObjectToUpdateRecordId. Set to Field Reference "[AAkPay__URL_Tokens__c].id".  This is the record Id of the SObject (URL Token) that you wish to update.
    • SObjectToUpdateFieldAPIName. Set to String "AAkPay__URL_Encrypted_Parameters__c".  This is the API Name of the field where you would like to save the encrypted URL Parameter to.
    • MerchantFacilityId.  Locate a Merchant Facility Record Id.  Paste value.
    • PaymentFormId.  Locate a Payment Form Record Id.  Paste value.
    • DefaultAmount.  Enter 100
  • Press "SAVE" button
  • Press "Activate" button

Your entry should look similar to the example below.

3.2. Testing the generation of your process builder

Navigate to the URL Token tab. Create a NEW URL Token without completing any fields and press "Save" button.

Reviewed the Saved record and notice the "URL Encrypted Parameters".  

Copy this value including the "?" for the step later.

3.3. Testing the Encrypted URL Parameter

Navigate to the Merchant Facility Tab.  Click into the Primary Merchant Facility.

Then click on the "URL For your Website"

 

Now, paste the Encrypted URL Parameter that was copied in 3.2 above and paste in the URL after the ....AAkPay__CheckoutM (1)

Notice how the donation amount value has defaulted to 100, because it was set by the process builder (2)

4. Generating Encrypted URL Parameters with Javascript

This option is best suited for website developers that wish to integration with Payments2Us Forms.

4.1. Locate the "URL Encrypted Parameters Key"

On the Payment Form, locate the value for "URL Encrypted Parameters Key".  If this field is blank, simply edit / save the Payment Form and a value will be assigned.

4.2. Access Crypto library.

The below is provided for your information and assistance.  If you require help or more information, then this is only covered by one of our premium support options.

The initialisation vector must be 128 bits (16 bytes.) and should be first 16 bytes of the SHA 256 key.

The following example is using CryptoJS library.

//Create key using "URL Encrypted Parameter Key"
var key = CryptoJS.enc.Utf8.parse('I/ypsFm3wO1/KPyWjNKqGgd55r8OZv/U');
// iv is first 16 characters of "URL Encrypted Parameter Key"
var iv = CryptoJS.enc.Utf8.parse('I/ypsFm3wO1/KPyW');
//Named value pars in JSON format.  See procedure "Payments2Us ManualsPayments2Us User Manual Enhanced Form ControlsWhich parameters can I use with the various URL Parameter options         
Which parameters can I use with the various URL Parameter options" for a list of "names" that can be used.
var pw = CryptoJS.enc.Utf8.parse( '{"LastName":"Smith","FirstName":"John","Amount":100.23}' );
//Encrypt
var encrypted = CryptoJS.AES.encrypt(pw, key,{ iv: iv});
//Encrypt string
var encrypted_data = encrypted.toString();
Click to copy

4.3. URL to use in website code

Make sure the result returned from the above encryption is URL Encoded.

Locate the base "URL for your Website" from the Merchant Facility.  Append "?params="+{encrypted URL parameters from 4.2}