Pre-Requisites

First, set up a Basic Payment Form with a minimum payment amount by following the steps here:

When is this Useful?

In some use-cases you may wish the amount to be paid to depend on the User's input into the Form Fields e.g.

• The User is making charitable donations. The minimum payment is $2, but they can choose to donate any amount above that they wish.

• The User will select options on the Form that will inform a logical function to decide how much they need to pay.

Both use-cases will require you to write a JavaScript function which will update the value of the amount due.

Step 1) Using Liquid to Fetch the Currency and Minimum Amount from Admin

You may find the following Liquid tags helpful while developing:

` | The currency for the Form defined in Admin | gbp | | `` | The symbol for the currency for the Form defined in Admin | £ | | `` | The `minimum payment` value defined in Admin, in the lowest denomination of that currency | 100 | | `` | The `minimum payment` value defined in Admin, formatted | 1.00 |

Step 2) Writing the function

The end goal of such a JavaScript function will be to set the value of hidden field with the ID "s_e_amount". The default value of this field will be the same as the minimum payment value you set in Admin, until it is changed via JavaScript. The final value should be an integer (whole number) of the number of cents that will be paid.

We'll give you an example of how this JavaScript may work here. You can adapt this example to suit your use case. The important thing is that you set the value of the field with the ID "s_e_amount".

Example 1 - Allowing the User to enter any value they wish

The following example allows the User to enter an amount of their choice into an input in the Form. Our function changes the format, then sets the value of the hidden field.

Liquid

<div class="">
  <label for="user_chooses_amount_to_pay">
    How much can you afford to donate (pounds and pence e.g. 10.00)?
  </label>
  <div style="display: flex; align-items: center;"
    <span style="margin-right: 5px;">{{context.exports.currency_map.data['GBP']}}</span>
    <input class="form-control" 
      id="user_chooses_amount_to_pay" 
      type="text" 
      placeholder="10.00"
    >
  </div>
</div>
{% endraw }

JavaScript

function changeAmountToPay() {
  var output = document.querySelector('#s_e_amount');
  output.value = parseInt(event.target.value * 100); 
  //As the end result must be in cents / pennies, we multiply the given value by 100 and make sure it is an integer. 
}
var input = document.querySelector('#user_chooses_amount_to_pay');
input.addEventListener('keyup', changeAmountToPay);

Example 2 - Using URL parameters to change the value of s_e_amount

This example shows how you can add an "amount" parameter to the URL- if this parameter exists then the s_e_amount will be updated.

The following Javascript can be added to your Basic Payment Form's Layout. The first half of the function will store the amount parameter within the "amount" variable, the second half checks if "amount" exists (this prevents "null" from getting added to s_e_amount) if so then s_e_amount is updated with the new price:

window.addEventListener('DOMContentLoaded', (event) => {
      //fetch amount param from the URL
      const urlParams = new URLSearchParams(window.location.search);
      const amount = urlParams.get('amount');
      //set s_e_amount value to amount from url param
      if(amount) {
            document.querySelector('#s_e_amount').value = amount;
      };
});

An example URL might be, to set the price to 20.00 or 2000 pence/cents:

/page-url?amount=2000

Prerequisites

• You have set up a PayPal Payment Gateway, with the required authentication:

Introduction

The PayPal Payment Gateway is compatible with Basic Payment Forms and Checkout Forms. However, there are a few differences to take into account when you choose this Payment Gateway.

Step 1) Removing the Submit Button

PayPal creates its own secure Submit Buttons for the payment Form. This means you should remove the default submit button from the Form Layout if you are using the PayPal Payment Gateway. We've included an error log in the JavaScript console to remind developers of this.

Step 2) Adding Custom Error Functions without the Submit Button

As custom error functions are normally passed in as an argument on the submit button's onclick listener, we've had to provide an alternative means to attach this: a global JavaScript variable.. You can set this in a <script> tag inside your Form Layout like so:

Step 3) Using a Custom JavaScript Notification/Message is Recommended with PayPal

Step 1) Head to CMS / Forms

Step 2) Create a New Form

Step 3) Add a Name and Redirect URL. Set up any Custom Fields you wish to add

Step 4) In the Payments Tab, Toggle Payments on and Select Basic Payment

Step 5) Optionally, Give Lifetime Access to a Secure Zone to Users Who Pay

In the Secure Zones tab, pick a Secure Zone. Access will be granted when payment is made and the Form is submitted.

Step 6) Save the Form

Step 7) Output your Form on a Page

Back in CMS Forms, find the ID for your newly created Form:

Use this ID in the Liquid tag when you insert the Form on the Page (or use Toolbox as a quick shortcut):

Your Payment Form is now set up and ready to accept payments using the minimum payment value you set.

Step 8) Testing

If your Payment Gateway is in 'Test Mode', then you may need to enter card details specific to the testing environment.

Step 9) Install a SiteBuilder Layout or Create your Own Layout

For PayPal or Authorize.net, you will need to follow the relevant extra steps:

See SiteBuilder to install a plug and play, themed Form Layout for your payment Form:

And set your Form to use it with the layout parameter.

See the Forms Reference for creating your own Layout:

Step 10) Optionally, set your Basic Payment Form to Allow Users to Choose How Much they Pay

By default, the Form will charge the minimum amount, but for some use cases like donations or invoices, you may want to allow them to pay more:

Including on a Page

To include a Basic Payment Form on the Page, use the same syntax as a :

Form Layouts

Authorize.net Specific Instructions

PayPal Specific Instructions

ecommerce/basic_payment Liquid Tag

What is it?

This is used to output payment fields in a basic payment form.

Where to use?

You should include this inside a basic payment form layout.

How to use?

s_e_amount Field

This HTML input field with the ID s_e_amount can be used to modify the amount which will be paid when the Form is submitted, see:

Payment Confirmation Layouts

Use Emails to send confirmation messages to customers, including a detailed breakdown of their Basic Payment Submission

Prerequisites

• You have installed eCommerce Module v1.1.4 or later. Check out to find out how you can install the latest version.

• You have set up a using the Stripe Payment Gateway

Introduction

You can now add details of a customer's Basic Payment Form to Workflow and Autoresponder transactional emails. Give your Client and the customer peace of mind, as well as valuable records for their safekeeping. Within the email, you can also access any fields that were submitted along with the original Form. Learn more here:

Step 1) Include the Payment Summary Feature

To include the details of the customer's most recent Order, include the following Liquid tag:

This can be outputted in one of two places:

• Inside the body of an e.g. autoresponder or workflow

• Inside a

Placing in either of these locations will allow the system to identify the last submitted Form case and, if there is one, the associated payment.

Step 2) Create or Find a Layout

File Structure

You can use an existing Layout, or create a new one in this File Structure: layouts/modules/module_14/payment/my_layout.liquid

Step 3) Develop the Layout

***Accessing Payment Details ***The layout file will have access to the this object, which will contain details about the Payment: {{this}} Within this object, you'll have access to the following fields:

Basic Payments are a way to take a payment when a form is submitted. They may be useful for allowing Users to pay invoices etc.

Prerequisites

• You have installed the eCommerce Module in Site Settings

• You have set up a

• Using PayPal as a Payment Gateway? There are additional setup instructions .

Introduction

Basic Payments are a way to take a payment against a standard Form submission.

You set the currency, and the minimum payment value in Form Builder.

When submitting the form, a value is sent to our payment processor, and validated server-side to check that it's higher than the minimum payment value you have set.

Here's 3 examples of when you'd use this payment system:

1. If you're sending invoices to a customer, and want them to pay online, they can enter their invoice number (in a custom field) and the amount to pay. You would then check 'offline' that the value paid matches that on the invoice. In this case you'd set the minimum payment value as '0.00'.

2. You know the exact value you want the users to pay (for example $10.00), so you set the minimum payment value as '10.00'. This is validated server-side to make sure they cannot pay less than that.

3. You want to charge a variable amount based on their form selections, and know the minimum value that should be. For example, the charge might be $10.00 as standard, but then have some optional custom fields that bring the price up to $20.00. See the section below: "Changing the Price based on User Form Input".

A note on Security

Remember, this kind of payment is designed for use cases where the customer intends to make a charitable donation or pay an invoice that is due. It is possible for the customer to modify the JavaScript and pay less (but not less than the minimum payment value). You should only use this kind of payment either when the customer does have a genuine choice, or the Client will be reconciling invoices and chasing where the correct amount has not been paid.

You must include 3 extra fields in the Form Layout for to work.

What is it?

This is used to output payment fields in a basic payment form.

Where to use?

You should include this on a basic payment form.

How to use?