Installation
The following provides a set of steps that will get you setup to use the Smarter Cloud for Salesforce managed package with the default settings. An explanation of these settings and more customisation options can be found under the 'Settings and Configuration' section.
Prerequisites
- An active SmarterPay Cloud client account in UAT and/or Live. (Please contact SmarterPay to acquire this).
- SmarterPay for Cloud Salesforce managed package installation URL and password.
Instance Setup
- Login to your Salesforce instance and install the SmarterPay Cloud for Salesforce managed package.
- So the package knows which SmarterPay Cloud instance to use, we need to activate an Instance.
To do this go to: Setup → Custom Metadata → SmarterPay Instance - Select Edit on the instance you want to use (UAT or Live). Click the Active checkbox and press save. We will come back to this record later.
API Setup
Step 1
SmarterPay Cloud API communication uses Named Credentials.
Go to Setup → Named Credentials → External Credentials → New
Step 2
Use the recommended details below depending on the instance you are connecting to. Once populated click Save.
UAT:
Label: SmarterPay Cloud UAT Name: SmarterPay_Cloud_UAT Authentication Protocol: Custom
Live:
Label: SmarterPay Cloud Live Name: SmarterPay_Cloud_Live Authentication Protocol: Custom
Step 3
Next, create a new 'Custom Header'. Here we are entering the API Key that will be used to communicate with SmarterPay Cloud. You will need to get your API Key from your SmarterPay Cloud account – to get this, login to SmarterPay Cloud and go to the System Settings in the Settings area.
Step 4
In the external credentials you will have a section called ‘Principals’. Click new and create the records with the following details:
- Parameter Name: SmarterPay Admin
- Parameter Name: SmarterPay User
- Leave the sequence number to auto populate. You do not need to add authentication parameters.
- Once the principles are created, got to Profiles and clone the 'SmarterPay Admin' and 'SmarterPay User' Permission Sets. These can be renamed to anything you choose but we suggest the following format 'SmarterPay Admin (CompanyName)'
- Add the Principle to the permission set in the 'External Credential Principle Access'.
Step 5
Now we have our External Credentials, we need to create two Named Credentials depending on your setup. The first is required, whereas the second is only for those users that want to process card payments.
All Users:
UAT:
Label: SmarterPay Cloud UAT Name: SmarterPay_Cloud_UAT URL: https://uatapi.smarterpaycloud.com/Service.svc External Credential: SmarterPay Cloud UAT Allowed Namespaces: SmarterPay
Live:
Label: SmarterPay Cloud Live Name: SmarterPay_Cloud_Live URL: https://api.smarterpaycloud.com/Service.svc External Credential: SmarterPay Cloud Live Allowed Namespaces: SmarterPay
Card Payment Users Only:
UAT:
Label: SmarterPay Card Payments UAT Name: SmarterPay_Card_Payments_UAT URL: https://uat-CardPayments.Smarterpaycloud.com External Credential: SmarterPay Cloud UAT Allowed Namespaces: SmarterPay
Live:
Label: SmarterPay Card Payments Live Name: SmarterPay_Card_Payments_Live URL: https://pay.smarterpay.com/SmarterPayCardPaymentService External Credential: SmarterPay Cloud Live Allowed Namespaces: SmarterPay
Webhook Setup - OAuth
Using OAuth to authenticate the webhook connection is the recommended method for the SmarterPay package.
Prerequisites
You will need to generate a webhook key with a length of up to 45 characters. We would recommend a 128bit or 256bit key length. There are several free services that can do this for you. Keep this key handy, we will need it later. This key is used to verify that the webhook is coming from SmarterPay Cloud.
Step 1
Go to the SmarterPay Setup tab in Salesforce under the SmarterPay App. Enter the webhook key that you created under the 'Webhook Private Key' field and click save next to the input field. Note: To maintain security, you will only be able to update this value in Salesforce and will not be able to see what is currently set.
Step 2
Open SmarterPay Cloud and go to Subscriptions in the Setup area. Click 'New Subscription'. See the screenshot below for the recommended settings.
In the security section choose 'OAuth' which should provide you with the following fields:
Populate the following fields using the format below:
| AUTHORISATION ENDPOINT | https://salesforcedomain.my.salesforce.com/services/oauth2/authorize |
| WEBHOOK URL | https://salesforcedomain.my.salesforce.com/services/apexrest/SmarterPay/WebhookV2Receiver |
| TOKEN ENDPOINT | https://salesforcedomain.my.salesforce.com /services/oauth2/token |
| WEBHOOK SIGNATURE KEY | Webhook Key generated in step 1 |
Under 'Events' select all events with all sources.
Once done, click 'Save'. You will now see your new SmarterPay Cloud subscription. Please note, these new settings can take up to 30 minutes to propagate to our backend systems.
Step 3
To activate the subscription you will need:
- Salesforce Integration user username
- Salesforce Integration user password
Click 'Setup Auth' to start the activation process. This will ask if you want to be forwarded you to the relevant endpoint for Authorisation. Confirm by clicking 'Ok'.
You will now be forwarded to the Salesforce login screen. Enter the username and password of the user you wish to use for the integration.
On successfully setting up the OAuth you'll be redirected to Cloud which will show the following message:
Webhook Setup - Sites Pages
This method is supported in the package if your organisation is unable to accommodate OAuth connections.
Prerequisites
You will need to generate a webhook key with a length of up to 45 characters. We would recommend a 128bit or 256bit key length. There are several free services that can do this for you. Keep this key handy, we will need it later. This key is used to verify that the webhook is coming from SmarterPay Cloud.
Step 1
Go to the SmarterPay Setup tab in Salesforce under the SmarterPay App. Enter the webhook key that you created under the 'Webhook Private Key' field and click save next to the input field. Note: To maintain security, you will only be able to update this value in Salesforce and will not be able to see what is currently set.
Step 2
Now we need to create a Salesforce Site. Once saved, make a note of the full URL. Setup → Sites → New You can create a site with the any details you want, but we would recommend the following:
- Site Label: SmarterPay
- Site Name: SmarterPay
- Default Web Address: smarterpay
- Active: True
Finally, we need to give access to the Webhook Receiver apex class. To do this, click 'Public Access Settings' and scroll down to 'Enabled Apex Class Access'. Click 'Edit' and select 'SmarterPay.WebhookV2Receiver'.
Step 3
Open SmarterPay Cloud and go to Subscriptions in the Setup area. Click 'New Subscription'. See the screenshot below for the recommended settings. You will need to enter your webhook key and Salesforce Sites URL you made earlier.
Under 'Events' select all events with all sources.
Once done, click 'Save'. You will now see your new SmarterPay Cloud subscription. Please note, these new settings can take up to 30 minutes to propagate to our backend systems
Step 4
Additional details of SmarterPay Clouds Webhooks 'Signature' Subscriptions can be found in our wiki: https://wiki.smarterpay.com/smarterpaycloud/webhooks/signature
Multiple Service User Numbers
Cloud can handle multiple Service User Numbers; these must be configured in the Custom Metadata to ensure that the records are set up against the corresponding SUN.
- If you have not already done so, please provide the SUN and Client Bank Account details to SmarterPay so that theses can be configured in your SmarterPay Cloud Account.
- SmarterPay will return the corresponding record Ids for the SUNs and related Client Bank accounts.
- Create the Service User Number Records and populate the lookup to the Instance Record
- Create the Client Bank Account Records and populate the look up to the Service User Number Record.