Embed Paypage as Overlay

You can add a paypage to your website as an "overlay" on top of your current webpage. This way, you can let customers make payments without leaving your site. You can do this by adding a paypage template, in the form of a small amount of JavaScript code, to your website.

How it works

When they click the button:

A payment form smoothly appears on top of your website content.

They fill in their payment details directly in this pop-up form.

Once they're done (whether they pay successfully or cancel), the payment form disappears, and they're still right where they started on your website

Flow

sequenceDiagram
    participant C as Customer
    participant M as Your Website
    participant A as Unaric Payments
    participant S as Salesforce
    
    C->>M: Initiates payment
    M->>A: paymentRef=XYZ<br/>customerRef=123<br/>dit=****
    critical Payment Processing
        A->>A: Validate dit token
        A->>A: Process payment
        A->>S: Update payment record
    option Success
        A-->>M: Success response
        M-->>C: Confirmation message
    option Failure
        A-->>M: Error details
        M-->>C: Error handling
    end

This overlay is designed for basic use. If you need more complex features or want to customize the payment process deeply, you'd need to dive into the actual code of this "overlay library" and create your own, more advanced version. For simple use cases, this basic overlay is sufficient.

Parameters

To make the overlay work, you need to provide some information. This information is the same as what you would find in a normal payment page web address ("eCommerce URL"). You can find this URL as a payment record in Salesforce. Think of parameters as pieces of information needed to configure the payment page.

The parameters that 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):

URL Parameter	Overlay Parameter	Description
pid	paymentRef	Payment record ID
pmRef	customerRef	Your organization ID
dit	dit	Data integrity token

Example

Let's say you have this payment page URL:

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

From this URL, we can see:

customerRef (pmRef) is 121

paymentRef (pid) is a031n00000XGkm5

dit is 9527c1725cc56eb739d452651a46bc29e286ac6d7b63994f16b035f746455179

Implementation

You only need to add a few snippets of JavaScript code to your webpage to get the overlay working.

1. Include the JavaScript Library

Include this line of code within the <head> section of your HTML document:

2. Initialize the Payment Form

Set up the PaymentFormDisplay payment form with your specific details. You'll need to add this JavaScript code either:

Inside <script> tags in your HTML page (e.g., in the <head> or <body>)

Within your existing JavaScript code that runs when the page loads (like in a function that runs on page load or inside window.onload).

Code reference

customerRef: Your customer ID. You get this ID when you connect your Salesforce organization to Unaric Payments through the Unaric Payments Setup tab. This is how the system knows it's your payment form.

Environment: Use test or live as values for testing and production environments, respectively.

Example

let form = new PaymentFormDisplay( { customerRef: 9797, // **Replace 9797 with your customer ID** environment: "test" // **IMPORTANT: Set to "test" for testing, "live" when you go live for real payments.** } );

You can additionally set parameters to the PaymentFormDisplay initialisation to set the iframe size: iframeheight and iframewidth. As an example:

let form = new PaymentFormDisplay( { customerRef: 1234, environment: "test", iframeheight: "300px", iframewidth: "999px" });

3. Trigger payment form

Lastly, you need to trigger the payment form to appear when a customer interacts with your page, like clicking a button. You'll typically do this in the onclick event of a button or link.

Let's say you have a button like this in your HTML:

<button onclick="showPaymentOverlay()">Donate Now</button>

You need to create the JavaScript function showPaymentOverlay() (or whatever you want to name it) to display the form.

Code reference

paymentRef: The Payment Reference ID from the specific payment record in your Salesforce. This tells the payment form which payment in Salesforce it's related to.

dit: Data Integrity Token (DIT) from the same Salesforce payment record.

Example

function showPaymentOverlay() { form.showForm( { paymentRef: "a030Y008393c4E4", // **IMPORTANT: Replace with the actual Payment Reference from Salesforce!** dit: "a030Y008393c4E487647bdbnfjhsgvd83yghsd" // **IMPORTANT: Replace with the Data Integrity Token (DIT) from your Salesforce Payment Record!** } ); }

Optional: Setting a Default Payment Type

You can also tell the payment form to default to a specific payment method when it first appears (like credit card, direct debit, etc.). To do this, add the defaultPayType parameter to the showForm() function.

Code reference

defaultPayType: Payment type. You can set this to:

card for Credit Card

dd for Direct Debit

paypal for PayPal

echeck for eCheck (if supported)

Example

function showPaymentOverlay() { form.showForm( { paymentRef: "a030Y008393c4E4", defaultPayType: "dd", // Optional: Set default payment type ("card", "dd", "paypal", "echeck") dit: "a030Y008393c4E487647bdbnfjhsgvd83yghsd" } ); }

Complete example

<!DOCTYPE html>
<html>
<head>
    <script src="https://live.protectedpayments.net/donationline/newnew/asperato-form-1.0.js"></script>
</head>
<body>
    <button onclick="showPaymentOverlay()">Pay Now</button>

    <script>
    document.addEventListener('DOMContentLoaded', () => {
        window.paymentForm = new PaymentFormDisplay({
            customerRef: "SFDC_ORG_123",
            environment: "test",
            onPaymentSuccess: (data) => {
                alert('Payment successful! Reference: ' + data.transactionId);
            }
        });
    });

    function showPaymentOverlay() {
        window.paymentForm.showForm({
            paymentRef: "a031n00000XGkm5",
            dit: "9527c1725cc56eb739d452651a46bc29e286ac6d7b63994f16b035f746455179",
            defaultPayType: "card"
        });
    }
    </script>
</body>
</html>