Architecture

The key operation of the product is to maintain synchronisation between SmarterPay Cloud and Salesforce. This is achieved through a series of queues that are processed asynchronously and independently of any other operation on going in either system. Queueing data exchanges allows SmarterPay to operate within Salesforce limits (API Call limits for example), but also allows for easier recovery from failures such as communication errors.

To fully utilise Salesforce functionality records will be created in Salesforce first as regular records. Records can therefore come from anywhere – Standard UI, Flows, Code, API, etc. The records can have additional fields or be linked to other records depending on requirements, such as an Opportunity or Contact. For example, a new Mandate may be created via a public Salesforce Site page and connected to the payee’s Contact record that is created as part of the same checkout process.

Once the record exists in Salesforce the 'After Insert' trigger will generate an API Queue record. By default, the API Queue is processed asynchronously by batch job. The API Queue can also be processed by Scheduled Job if this fits the Salesforce org or requirements better. Once the API call is successful, the SMPC Id and other response fields will be placed back onto the source record so any further update or webhooks can be linked correctly. In the event of a communication failure, the API Queue record will be 'retried' at increasing intervals (configurable). Any subsequent changes to the record will result in another API Queue record and is processed in the same way as described. Once the API Queue has been processed, the record is deleted as it is no longer required.

If an API Queue record expends all retries it will change to a 'Failed' status. It is recommended that administrators regularly check for failed records. The record will show what the problem was in the Error Log field. Admins can attempt to resolve the issue and reprocess the API Queue record or contact SmarterPay Client Services for assistance.

The exception to the above will be the processing of Bank Accounts. By default, Bank Account details such as Sort Code and Account Number will not be stored in Salesforce (see Configuration & Settings). A standard Flow and API method is provided instead. This sends the details directly to SmarterPay Cloud first and then inserts the Bank Account as a record in Salesforce without any sensitive details. Customers not wanting to store these details in Salesforce should use the standard methods provided. Customers that do not mind storing these details in Salesforce can create records directly as Bank Account records and therefore wouldn’t necessarily need to use the component or API methods, although modulus checking would need to take place at some point in the process. A validation rule will be set on Bank Account to stop users entering details on the record itself if the storage of bank account details is switched off.

SmarterPay Cloud sends batches of 'event' information to Salesforce using webhooks. An endpoint in Salesforce stores these events as Webhook Event records. By default, a Platform Event is triggered which handles the individual processing of each Webhook Event into the system. The Webhook Queue can also be processed by triggered batch job or Scheduled Job. Once the event has been processed, the Webhook Event record is deleted as it is no longer required. A full history of communication from SmarterPay Cloud can be found within SmarterPay Cloud.

Like API Queue, Webhook Queue makes use of an automatic retry. If the Webhook Event switches to Failed, these can be picked up by administrators and troubleshooted to resolve the described processing issue. If communication between SmarterPay Cloud and Salesforce fails, they webhooks are retried automatically at SmarterPay Cloud.

Events are processed in order that they occur. If for some reason events are received out of order, some objects have strict validation so important events are not skipped. For example, a Payment record cannot jump from Pending to Successful as it will have skipped the Submitted stage. This is important so that any customisation that relies on record Status will work reliably. The processing code will also not process 'old' events if a newer one has already been processed. This means that a record is unable to move 'back in time'.

The following shows examples of how records can be created within Salesforce/SmarterPay Cloud and how they will be processed.