The Stripe Payment Gateway provides its own iframe to accept Card Details securely so direct styling isn't possible. Instead use JavaScript.

Introduction

The Stripe Payment Gateway provides its own iframe to accept Card Details securely so it's not possible to have full access to the HTML structure so you can apply your own styles. Instead, you can use JavaScript to pass your styles safely to Stripe.

This method will work on any kind of Payment Form which uses Stripe. This includes:

• Basic Payment Form

• Checkout

• Subscription Sign Up

Setting Styles

Setting up the JavaScript Variable

Styles are passed securely to Stripe using JavaScript, rather than your traditional method of applying styles directly with a CSS file.

To do this, create a global JavaScript variable stripe_style at the top of your Form Layout or Page. Its value should be an object like the following:

<script>
var stripe_style = {
  base: {
    color: '#DDA0DD', //Sets CSS property "color" of "base" variant
    '::placeholder': {
      color: '#DDA0DD' // Sets CSS property of placeholders within the "base" variant
    }
  }
}
</script>

Available Selectors and CSS properties

As in the example above- the stripe_style variable is passed a JavaScript object.

You can see Stripe's full definition of how this object should be structured using their documentation here: https://stripe.com/docs/js/appendix/style. The first set of keys e.g. base represents a "variant" or state the elements might be in. Nested within this, certain allowed CSS properties may be set.

Renaming the Classes - Advanced

You can ask Stripe to rename some of the available classes by redefining the classes object. To do this in Siteglide, create a global variable stripe_classes:

<script>
var stripe_classes = {
    classes: {
        base: "my-custom-container-class" //Renames the base class from the default "StripeElement" to "my-custom-container-class". 
    }
}
</script>

Any styles you set in the stripe_styles object to base will still apply after changing the class, unless you specifically override them.

You can see a full reference for the available properties for this object in the Stripe documentation here: https://stripe.com/docs/js/elements_object/create_element?type=card#elements_create-options-classes

Pre-Requisites

Checkout Support

The payment flow will look for code in your set Custom Payment Gateway Partial Path. The file it's looking for is {{Custom Payment Gateway Partial Path}}/checkout.liquid(e.g. modules/my_ecommerce/payment_gateways/money_take/checkout)

Your code will be included inside the Form - where in the Form Layout you see the tag

To access information about your custom Payment Gateway such as the API Keys, you can output {{payment_gateway}} into the layout.

You may notice that many of the steps are similar to the steps for the Basic Payment Form and you may wish to re-use some of your code.

When building you layout consider the following process that needs to be take place.

Step 1) Set up Client Side Code on Page Load

Initially set up any Client-side HTML or JavaScript which the Payment Gateway requires to be rendered on Page Load e.g. elements for securely entering card details.

Step 2) Define a Payment Function to run after Form Validation

Define a JavaScript function which will set up and carry out the payment transaction. Depending on the complexity of your Payment Gateway, this may include multiple steps.

You should assign this function to window.s_e_payment = my_payment_function. The Siteglide Form will call this function when validation is complete and it is ready to begin the payment.

The function definition should return a JavaScript Promise- this will allow the Siteglide Form Submit function to wait for the payment to finish, before it continues submitting the Form.

Your function definition can use the parameter form - this contains the DOM element for the Form which has been submitted. This will be used in the JS selectors in the next step to make sure we target the DOM in the correct Form where more than one Form is present on the Page.

Step 3) Creating an Order Server-Side

Unlike Basic Payment Forms, the amount to be paid is not stored in a JavaScript variable. Instead, the amount will be calculated using the contents of the User's Cart.

As the process of converting Cart Data to an Order is lengthy, we've opened up our endpoint for your use:

• Email

• Cart

• Shipping Method (ID)

• Order ID (should normally be blank-this is to prevent duplicates)

• Slug

• Discount Code (ID) | var data = { user_id: form.querySelector('#s_user_id').value, email: form.querySelector('#s_email').value, cart: form.querySelector('#s_e_cart').value, shipping_method: form.querySelector('#s_e_cart_shipping').value, order_id: form.querySelector('#s_e_order_id').value, slug: form.querySelector('#s_e_slug').value, discount_code: form.querySelector('#s_e_cart_discount').value, form_id: form.querySelector('[name=parent_resource_id]').value, hcaptcha: form.querySelector('[name=h-captcha-response]')? form.querySelector('[name=h-captcha-response]').value : null}; | | Response | { "order_id": "xxxxx", "slug": "xxxxx", "errors": { "example_error_key": { "id": "xxxxx", "message": "example_message" } } } |

Step 4) Create a Relationship Between the Case and the Order

After receiving your response, you should store the resulting order_id as the value of the hidden field #s_e_order_id. This will allow the Form to store a relationship between the Order and the Case when the submission is complete. It will also allow you to access that Order when needed server-side.

Step 5) Check the Order Details Server-Side and Complete the Payment

Depending on the complexity of your Payment Gateway, the payment can either be carried out in a single step, or in multiple steps - this is up to you.

You will however have to send at least one API call to your Payment Gateway from your own Liquid endpoint Page in order to securely send the details of the Order.

To do this, you'll need to run a GraphQL query to fetch the Order, filtering by its ID (the ID returned from the order_pre_payment_processor endpoint) and model_schema_name: "module_14/order".

The table below shows the fields you can access or update in the Order model:

Step 6) Resolve any Errors

To halt both your Payment Function and Form Submission and throw errors to the User, you'll need to resolve your Payment Function's promise with an object containing an errors property - an array of objects, each with a message String property.

Note, your Promise should not include a reject, as this will not be used.

Step 7) Resolve your Payment

Once your my_payment_function payment function is complete and the funds have been captured, you will want to let the Siteglide Form Submit Function finish submitting the Form. To do this, resolve the Promise (without an errors object):

Pre-Requisites

Basic Payment Form Support

The payment flow will look for code in your set Custom Payment Gateway Partial Path. The file it's looking for is {{Custom Payment Gateway Partial Path}}/basic_payment.liquid(e.g. modules/my_ecommerce/payment_gateways/money_take/basic_payment)

Your code will be included inside the Form - where in the Form Layout you see the tag

To access information about your custom Payment Gateway such as the API Keys, you can output {{payment_gateway}} into the layout.

When building you layout consider the following process that needs to be take place.

Step 1) Set up Client Side Code on Page Load

Initially set up any Client-side HTML or JavaScript which the Payment Gateway requires to be rendered on Page Load. E.g. elements for securely entering card details.

Step 2) Define a Payment Function to run after Form Validation

Define a JavaScript function which will set up and carry out the payment transaction. Depending on the complexity of your Payment Gateway, this may include multiple steps.

You should assign this function to window.s_e_payment = my_payment_function. The Siteglide Form will call this function when validation is complete and it is ready to begin the payment.

Your function definition can use the parameter form - this contains the DOM element for the Form which has been submitted. This will be used in the JS selectors in the next step to make sure we target the DOM in the correct Form where more than one Form is present on the Page.

All of the following information is available in the HTML DOM and therefore is also accessible via JavaScript.

The parameter form from the previous step is used for specificity.

See the next step r.e. checking the amount on the Server Side.

Step 3) Check the Minimum Value is Met

Siteglide Basic Payment Forms have a "Minimum Value" defined in the Form Structure. This can be used in two ways:

• As the actual value of products or services

• When the User is choosing their own price e.g. a donation Form, the minimum price the Client will accept in order to not make a loss on the donation when the Payment Gateway's fees are paid.

All of our native Payment Gateways include a server-side check to make sure the amount is met- so most likely you'll wish to do the same.

In order to do this- your Payment Gateway should make a request to a Liquid Page you create. The Form Configuration ID and Amount should be sent over in your data payload or query parameters.

The Endpoint Page should run an admin_form_configurations query:

In the results of this query, you'll be able to verify the true minimum amount and currency. You can compare these to the s_e_amount value calculated on the Front-end. Depending on the result_name you choose - the values from this example query of note are:

On this endpoint, you'll have secure access to these values, so it might make sense to use this same endpoint to:

• send an API call to your Payment Gateway to set up a Payment Intent (or complete Payment Transaction).

• run a GraphQL mutation to create a "module_14/payment" model in the database, (with a status of "Intent Created" or "Payment Complete" as appropriate) (see below)

Step 4) Create a Record of the Payment in Siteglide

In order for the Client to see a record of the Payment in the Siteglide Admin, you must:

• Create a database object with the model_schema_name of module_14/payment.

• Via the JavaScript in your Payment function, store the ID of this newly created Payment Model in the hidden HTML field #s_e_order_id. This way it will be submitted with the Form and a relationship will be established between the Payment and the Case- allowing their information to be linked in the Admin.

Depending on the complexity of your Payment Gateway, you may wish to:

• Create the Payment Model at the same time a Payment Intent is created with the status Intent Created. After capturing funds in a later step, you may wish to update the same model by referring to it by its ID, this time giving it the status Payment Complete.

• Create the Payment Model at the end of the Payment process- to confirm its success. This would immediately be given the status Payment Complete.

The key fields you will need to set on the Payment Model are shown in the following table:

Step 5) Resolve any Errors

To halt both your Payment Function and Form Submission and throw errors to the User, you'll need to resolve your Payment Function's promise with an object containing an errors property - an array of objects, each with a message String property.

Note, your Promise should not include a reject, as this will not be used.

Step 6) Resolve your Payment

Once your my_payment_function payment function is complete and the funds have been captured, you will want to let the Siteglide Form Submit Function finish submitting the Form. To do this, resolve the Promise (without an errors object):

PayPal allows you to include different parameters as part of the SDK such as disabling payment options that are unwanted, as per the following link ->

To use these parameters add this code to top of your Form layout, containing the parameters you want:

This specific example will stop Sofort being offered as a payment option.

Prerequisites

• Good understanding of Liquid

• Good understanding of JavaScript

• Good understanding of GraphQL, including queries, related_models, mutations and using mutations to send API calls.

• Good understanding of APIs

Introduction

Siteglide have built integrations between its eCommerce Module and three Payment Gateways:

• Stripe - integrated with all Siteglide eCommerce Features

• PayPal - for Checkout and Basic Payment Forms

• Authorize.net - for Basic Payment Forms

In order to focus on improving features for the Payment Gateways we have, we won't be building integrations to any other Payment Gateways at this point. Instead, this Article is intended to help experienced Siteglide Partners build their own Payment Gateway Integrations.

Payment Gateway Configuration

We've opened up the Payment Gateway model (model_schema_name: "module_14/payment_gateway") to allow you to customize it to suit your own Payment Gateway:

Use GraphQL to create a record in this table using the filelds above.

Next Steps

Now your Payment Gateway exists, it's time to give it some functionality. You can add support for one or more of the following:

Step 1 - Create a Payment Form

Create a Form in the Siteglide Admin and turn on the setting to use it as a payment form. (Basic Payment Form and Checkout will be supported as both support at least 2 payment gateways.)

Step 2 - Create a Custom Form Layout

In Code Editor or CLI, make a copy of the default form layout, ready to customise it.

In any Page, output your form and select the custom layout with the layout parameter. E.g. if your form ID is 1, your layout should be at marketplace_builder/views/partials/layouts/forms/form_1/my-custom-layout.liquid

For Basic Payment forms:

Step 3

For Checkout Forms, use the ecommerce/checkout_standard include to output multiple payment gateways inside your checkout form Liquid layout file.

For Basic Payment Forms:

Step 4

Once you have multiple options, you'll need a way to tell the system which to use.

The following JS function will do that for you:

Pass in the name of the Payment Gateway you wish to switch to as the only argument.

This can be applied as a callback to any JS event you like, such as clicking a radio button, or opening an accordion. e.g.

Liquid

JavaScript

If the JS function is not called, the default payment gateway from the multiple available gteways will be used.

• Stripe: https://docs.stripe.com/testing?locale=en-GB

• PayPal: https://developer.paypal.com/tools/sandbox/card-testing/#link-creditcardgenerator

• Authorize.net https://developer.authorize.net/hello_world/testing_guide.html

After you've installed the eCommerce Module on a Site, setting up a Payment Gateway is the next step!

What is a Payment Gateway?

Siteglide never stores your customers' full card details. Instead we integrate with globally recognised and trusted payment gateways to store that information and process payments on your behalf e.g. Stripe or PayPal.

Stay in this section for information about how to set up, different configuration advice for different gateways and how to run multiple gateways on a site and let customers choose between them.

Compatibility

At the current time, some Payment Gateways allow more access to Siteglide features than others.

The Stripe Payment Gateway is recommended as fully compatible with all Siteglide Features.

PayPal is compatible with Basic Payment Forms and Cart + Checkout

Authorize.net is only compatible with Basic Payment Forms

This section gives you a detailed understanding of the different payment gateway options available: