TABLE OF CONTENTS




Using the paypage as an Overlay

The simplest way of using the template is as an overlay - this can be achieved by inserting minimal Javascript into an existing web page.


Please note that this overlay library is intended to be used as a mechanism to show a payment page overlay which then returns back to the place it started from. To do something more sophisticated then you should look at the source of the library and create your own version of it.


The parameters which are used for setting up the overlay are equivalent to the parameters specified in the "eCommerce URL" (which can be found on any payment record):


The "pid" parameter on the URL is the "paymentRef" parameter on the overlay

The "pmRef" parameter on the URL is the "customerRef" parameter on the overlay

The “dit” parameter on the URL is the “key”


For example, if the URL on a payment record is 

https://demo.protectedpayments.net/PMWeb1?pmRef=121&pid=a031n00000XGkm5&locale=en-GB&dit=9527c1725cc56eb739d452651a46bc29e286ac6d7b63994f16b035f746455179

then the customerRef parameter is 121 and the paymentRef parameter would be a031n00000XGkm5


To use the template as an overlay, just three bits of javascript are needed:


  • The following should be inserted in the <head> tag of the document:


<script src="https://live.protectedpayments.net/donationline/newnew/asperato-form-1.0.js"></script>


  • Also include in the initialisation of the page (eg. in <head> or window.onload):

let form = new PaymentFormDisplay(    

{        

customerRef: 9797, //Replace with your customer reference

environment: "test" //"test", "live"    } );


As per the comment, the customer reference 9797 is an example and will need to be changed to your Asperato customer ID (obtained when you connect your Salesforce Org to Asperato from the Asperato Set Up Page)


Also, as per the comment, the environment name is available in the payment page URL. For example, if the URL on a payment record is "https://test.protectedpayments.net/PMWeb1?pmRef=121&pid=a031n00000XGkm5&locale=en-GB&dit=9527c1725cc56eb739d452651a46bc29e286ac6d7b63994f16b035f746455179" then "test" is the environment name.


  • To show the form (such as in the onclick attribute of a button) for a particular payment reference in Salesforce with the relevant details pre-populated:

form.showForm(    

{        

 paymentRef: "a030Y008393c4E4",                                dit: "a030Y008393c4E487647bdbnfjhsgvd83yghsd" //Obtain the value of "dit" from "data integrity token" field available on payment record. This field is available 2.17+ and is used to enforce the data integrity   

} 

);


You can optionally set the default payment type on the form using

form.showForm(    

{        

paymentRef: "a030Y008393c4E4",        defaultPayType: "dd", //"card", "dd", "paypal" or "echeck"        dit: "a030Y008393c4E487647bdbnfjhsgvd83yghsd" //Obtain the value of "dit" from "data integrity token" field available on payment record. This field is available 2.17+ and is used to enforce the data integrity    

} 

);


Using the paypage within a Lightning Component (aura)


To access a visualforce page in the Lightning community we have to make it available for lightning experience by enabling the Available for Lightning Experience, Lightning Communities, and the mobile app checkbox on Visualforce page in setup.

To use the paypage template in a Lightning Component, follow the steps below:


1. Download the script from below URL, and save it in a new Javascript file

https://live.protectedpayments.net/donationline/newnew/asperato-form-lighnting-1.0.js


2. Add this new file in a new static resource named PayPageJS

3. Add this code in lightning component 

<ltng:require scripts="{!$Resource.PayPageJS}" afterScriptsLoaded="{!c.onScriptLoad}"> </ltng:require>


4. Add the below code in lightning component controller

(

{      

    onScriptLoad: function(component, event, helper) {          var form         = new PaymentFormDisplay(            {                customerRef: 9797, //Replace with your customer reference                environment : "test" //"test", "live"            }            

);         

    form.showForm(         

{              

paymentRef: "a030Y008393c4E4", // Replace with payment Id              dit: "a030Y008393c4E487647bdbnfjhsgvd83yghsd" //Obtain the value of "dit" from "data integrity token" field available on payment record. This field is available 2.17+ and is used to enforce the data integrity         

}         

);     

} 

})


5. To access this page in a Salesforce Community, add the payment page URL in CSP Trusted Sites in the Salesforce Community. For example, if the URL on a payment record is https://live.protectedpayments.net/PMWeb1?pmRef=121&pid=a031n00000XGkm5&locale=en-GB&dit=9527c1725cc56eb739d452651a46bc29e286ac6d7b63994f16b035f746455179, then add https://live.protectedpayments.net

in CSP Trusted Sites in salesforce.

6. You will also need to implement the forceCommunity:availableForAllPageTypes interface in your lightning component

<aura:component implements="forceCommunity:availableForAllPageTypes">


Using the paypage within an iframe


Many customers wish to use the template in an iframe as part of their existing site, rather than displaying it as a standalone page - this is supported by Asperato, as long as the containing site is served over TLS1.2 or newer. Please make sure your iframe element is large enough to contain the payment form without any scrollbars. We recommend a size of at least 500px width and 1000px height.


Non-secure pages may not iframe the Asperato payment page in this way, as customers have no easy way of determining that the iframe itself is secure if the surrounding page is not.


Important Note - We require that we whitelist your domain when you move your iframed paypage into your live environment - please contact our support team (support@asperato.com) to enable this for you when you are ready to move from your test environment.


PostMessage events


There are a number of standard postmessage events that occur when the template is operating in iframe mode. The postmessage content is a simple string. The values and their related events are documented in the table below.


Text stringEvent
asp--redir:REDIR URLOn redirect to an external authorisation page (such as in the case of Paypal.) This message contains the value of that URL, so on receiving this message the parent page may choose to close the iframe and launch the new in a new tab / window.
asp--exit-screenOn load of the payment success screen
asp--error--value:ERROR MESSAGEOn load of the payment error screen, this message contains the value of the error message displayed to the user.
asp--error-screenOn load of the payment error screen
asp--errorWhen the Close Without Retry button is pressed on the error page
asp--completeWhen the Finish button is pressed on the exit page
asp--cancelWhen the cancel link is pressed on the main pay page
asp--processingWhen the processing gears are displayed, after the user has submitted the form
asp--pcdialogWhen the postcode lookup dialog is displayed
asp--dddialogWhen the DD confirmation dialog box is displayed (allows the parent frame to refocus the iframe using "window.scrollTo(0,0)")
aspPageSizeMessage
 Allows the iFrame to respond to any sizing changes of the payment page

By implementing an appropriate listener in the parent HTML you can make decisions based on these postmessage events.

For example if you want to suppress the display of the success screen then you can close the iframe when the listener detects the text content "asp--exit-screen" in the body of the postmessage.


Page size example:

Convert the postMessage string to a JSON object JSON.parse(that aspPageSize as a String) and then set the showForm() size to the aspPageSize.width and .height

let size = JSON.parse(aspPageSizeMessage);

aspPageSizeMessage is the postMessage returned String and

size is then the JSON object so you can do size.aspPageSize.width which will give you the value of "600px"

if you only need the integer formatted value, then the width value would be this:

let size = JSON.parse(aspPageSizeMessage);

let width = parseInt(size.aspPageSize.width);


Please note that we may add additional postmessage events from time to time - you must make sure that your integration won't cause an error if it receives a postmessage that it doesn't know about (ignoring it is fine.)


Using the paypage within a Lightning Web Component (LWC)


To use the paypage template in a Lightning Web Component, follow the steps below:

  1. Download the script from the below URL, and save it in a new Javascript file https://live.protectedpayments.net/donationline/newnew/asperato-form-lighnting-1.0.js
  2. Add this new file in a new static resource named PayPageJS
  3. Create a new lightning web component named AsperatoPayPage.
  4. Add below code in AsperatoPayPage.html    

<template>

<!-- You can also give a different data-id value, remember to pass the same in js -->

  <div data-id="paypage-container"></div>

</template>

5. Add below code in AsperatoPayPage.js 

import { LightningElement, api } from 'lwc';

import { loadScript } from 'lightning/platformResourceLoader';

import PayPageJS from '@salesforce/resourceUrl/PayPageJS';


export default class AsperatoPayPage extends LightningElement {

    @api error ='';


    connectedCallback(){

        loadScript(this, PayPageJS)

        .then(() => {

            let form = new PaymentFormDisplay(

                {

                    customerRef: 10531, //Replace with your customer reference

                    environment: "test" //"test", "live"

                }

            );

            form.showForm(

                {

                    paymentRef: "a040C000004SsajQAC",

                    dit: "f654815b4b7a189bd9239d0ef3defdcada3560aec64b66ff8ef61f21e6e33999", //Obtain the value of "dit" from "data integrity token" field available on payment record. This field is available 2.17+ and is used to enforce the data integrity

                    container: this.template.querySelector('[data-id="paypage-container"]') // Obtain the value of “data-id” from the component where you've passed in. No need to change if it's the same

                }

            );

        })

        .catch((error) => {

            console.log('Error---> '+error);

        });

    }


}

6.To set the visibility of your component to different pages you need to update the component's xml. Update AsperatoPayPage.js-meta.xml. If you want to display your component on the home page add lightning__HomePage to the target. If you want to display it on an experience cloud add lightningCommunity__Page, lightningCommunity__Default .And similarly for others.

<isExposed>true</isExposed>

    <targets>

        <target>lightning__HomePage</target>

        <target>lightning__RecordPage</target>

        <target>lightningCommunity__Page</target>

        <target>lightningCommunity__Default</target> </targets>

Optional Steps for styling


  1.  You can add custom styling to the paypage by adding a css to your component, simply create a new file named AsperatoPayPage.css 

.iframeStyle{

    background-color: rgb(191, 201, 241); // you may add other styles too}

2. and then add this class to your AsperatoPayPage.html

<template>

  <div class="iframeStyle" data-id="paypage-container"></div>

</template>