Building a Custom Payment Gateway

26min

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:
Field Name
Field ID
Purpose/Notes
Name
module_field_14/payment_gateway_1
Payment Gateway Display Name
Active
module_field_14/payment_gateway_2
Boolean

Only one Payment Gateway should be active at a time.
Type
module_field_14/payment_gateway_5
Payment Gateway Name in snake_case - Must be unique to your Payment Gateway
In test mode?
module_field_14/payment_gateway_8
Boolean
Custom Payment Gateway Partial Path
module_field_14/payment_gateway_19
Folder path for the partials you will use to include your Gateway code on the Form (see next section)
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
{%- include 'ecommerce/basic_payment', amount: '500', currency: 'gbp' -%}
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.
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.
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.  
JS
window.s_e_payment = function(form){
	return new Promise(async function (resolve) {
		<!-- Run your payment -->
	});
}
window.s_e_payment = function(form){
	return new Promise(async function (resolve) {
		<!-- Run your payment -->
	});
}
﻿
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.  
Field
JavaScript Selector
Purpose/Notes
Amount
form.querySelector('#s_e_amount').value;
The amount of money the customer intends to pay. 

For Basic Payment Forms, this value is editable on the Client Side. If you need the original Minimum Amount defined against the Form, run a server -side check.
Currency
form.s_e_currency('#s_e_currency').value;
The currency the customer intends to use.

If you need the original currency set up against the Form, use a server-side check.
Form Configuration ID
form.querySelector('[name="form_id"]').value;
This Form Configuration ID can be sent to your own Liquid XHR endpoint and used in a GraphQL query to confirm the details of this Form. 
﻿
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:
GraphQL
query(
	$fc_id: ID!
){
	result: admin_form_configurations(
		filter: {
			id: {
				value: $fc_id
			}
		}
	){
		items: results{
			configuration
		}
	}
}
query(
	$fc_id: ID!
){
	result: admin_form_configurations(
		filter: {
			id: {
				value: $fc_id
			}
		}
	){
		items: results{
			configuration
		}
	}
}
﻿
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:
HTML
{%- assign currency = form_configuration_data.result.items[0].configuration.properties.form_payment_currency.value | downcase -%}
{%- assign currency = form_configuration_data.result.items[0].configuration.properties.form_payment_currency.value | downcase -%}
﻿
HTML
{%- assign minimum_amount = form_configuration_data.result.items[0].configuration.properties.form_payment_amount.value | plus: 0 -%}
{%- assign minimum_amount = form_configuration_data.result.items[0].configuration.properties.form_payment_amount.value | plus: 0 -%}
﻿
 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) 
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:
Field Name
Field ID
Purpose / Notes
Payment ID
module_field_14/payment_1
The Payment Gateway's ID for this Payment Intent
Gateway ID
module_field_14/payment_2
Optional - The ID of the Payment Gateway in Siteglide that handled this payment.
Gateway Type
module_field_14/payment_4
Optional - The type of the Payment Gateway in Siteglide that handled this payment.
Status
module_field_14/payment_5
The status of this Payment: Intent Created, Payment Complete or a custom Status of your choice.
Charge ID (Stripe), Capture ID (PayPal) or use for a similar purpose in another Payment Gateway.
module_field_14/payment_6
Optional
Currency
module_field_14/payment_7
The actual currency used.
Amount
module_field_14/payment_8
The actual amount to be paid.
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. 
JS
window.s_e_payment = function(form){
	return new Promise(async function (resolve) {
		<!-- Run your payment -->
		<!-- Oops, an error -->
		resolve({ errors: [ { message: my_error } ] });
	});
}
window.s_e_payment = function(form){
	return new Promise(async function (resolve) {
		<!-- Run your payment -->
		<!-- Oops, an error -->
		resolve({ errors: [ { message: my_error } ] });
	});
}
﻿
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):
JS
window.s_e_payment = function(form){
	return new Promise(async function (resolve) {
		<!-- Run your payment -->
		resolve('complete');
        <!-- Form Submission continues -->
	});
}
window.s_e_payment = function(form){
	return new Promise(async function (resolve) {
		<!-- Run your payment -->
		resolve('complete');
        <!-- Form Submission continues -->
	});
}
﻿
﻿
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
{%- include 'ecommerce/checkout_standard' -%}
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.
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.
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.  
JS
window.s_e_payment = function(form){
	return new Promise(async function (resolve) {
		<!-- Run your payment -->
	});
}
window.s_e_payment = function(form){
	return new Promise(async function (resolve) {
		<!-- Run your payment -->
	});
}
﻿
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:
Setting
Value
URL
api/ecommerce_general/order_pre_payment_processor.json
Method
POST
Required Headers
xReq.setRequestHeader('content-type', 'application/json');
 
xReq.setRequestHeader('X-CSRF-Token', form.querySelector('[name=\'authenticity_token\']').value);
 
xReq.setRequestHeader('X-Requested-With', 'X-Requested-With: XMLHttpRequest');
Body Data:
 
User ID
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" }  }  }
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. 
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:
Field Name
Field ID
Purpose/Notes
User ID
module_field_14/order_1
 
User Email
module_field_14/order_2
 
Status
module_field_14/order_3
Either Intent Created, Payment Complete or a custom status of your choice. 
Billing Address
module_field_14/order_4
Not yet used by Siteglide
Shipping Address
module_field_14/order_5
Not yet used by Siteglide
Payment Method
module_field_14/order_6
Not yet used by Siteglide. 

You must not use this field to store full card numbers. 

You may choose to store either an ID or fingerprint (e.g. https://stripe.com/docs/api/payment_methods) which your Payment Gateway uses to reference a payment method. 
Shipping Method ID
module_field_14/order_7
 
Tracking Number
module_field_14/order_8
Not yet used by Siteglide
Total Price
module_field_14/order_9
 
Currency
module_field_14/order_10
 
Discount Code
module_field_14/order_11
 
Shipping Method Price
module_field_14/order_12
 
Shipping Method Name
module_field_14/order_13
 
Discount Code ID
module_field_14/order_14
 
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. 
JS
window.s_e_payment = function(form){
	return new Promise(async function (resolve) {
		<!-- Run your payment -->
		<!-- Oops, an error -->
		resolve({ errors: [ { message: my_error } ] });
	});
}
window.s_e_payment = function(form){
	return new Promise(async function (resolve) {
		<!-- Run your payment -->
		<!-- Oops, an error -->
		resolve({ errors: [ { message: my_error } ] });
	});
}
﻿
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):
JS
window.s_e_payment = function(form){
	return new Promise(async function (resolve) {
		<!-- Run your payment -->
		resolve('complete');
        <!-- Form Submission continues -->
	});
}
window.s_e_payment = function(form){
	return new Promise(async function (resolve) {
		<!-- Run your payment -->
		resolve('complete');
        <!-- Form Submission continues -->
	});
}
﻿

Field Name	Field ID	Purpose/Notes
Name	module_field_14/payment_gateway_1	Payment Gateway Display Name
Active	module_field_14/payment_gateway_2	Boolean Only one Payment Gateway should be active at a time.
Type	module_field_14/payment_gateway_5	Payment Gateway Name in snake_case - Must be unique to your Payment Gateway
In test mode?	module_field_14/payment_gateway_8	Boolean
Custom Payment Gateway Partial Path	module_field_14/payment_gateway_19	Folder path for the partials you will use to include your Gateway code on the Form (see next section)

Field	JavaScript Selector	Purpose/Notes
Amount	form.querySelector('#s_e_amount').value;	The amount of money the customer intends to pay. For Basic Payment Forms, this value is editable on the Client Side. If you need the original Minimum Amount defined against the Form, run a server -side check.
Currency	form.s_e_currency('#s_e_currency').value;	The currency the customer intends to use. If you need the original currency set up against the Form, use a server-side check.
Form Configuration ID	form.querySelector('[name="form_id"]').value;	This Form Configuration ID can be sent to your own Liquid XHR endpoint and used in a GraphQL query to confirm the details of this Form.

Field Name	Field ID	Purpose / Notes
Payment ID	module_field_14/payment_1	The Payment Gateway's ID for this Payment Intent
Gateway ID	module_field_14/payment_2	Optional - The ID of the Payment Gateway in Siteglide that handled this payment.
Gateway Type	module_field_14/payment_4	Optional - The type of the Payment Gateway in Siteglide that handled this payment.
Status	module_field_14/payment_5	The status of this Payment: Intent Created, Payment Complete or a custom Status of your choice.
Charge ID (Stripe), Capture ID (PayPal) or use for a similar purpose in another Payment Gateway.	module_field_14/payment_6	Optional
Currency	module_field_14/payment_7	The actual currency used.
Amount	module_field_14/payment_8	The actual amount to be paid.

Setting	Value
URL	api/ecommerce_general/order_pre_payment_processor.json
Method	POST
Required Headers	xReq.setRequestHeader('content-type', 'application/json'); xReq.setRequestHeader('X-CSRF-Token', form.querySelector('[name=\'authenticity_token\']').value); xReq.setRequestHeader('X-Requested-With', 'X-Requested-With: XMLHttpRequest');
Body Data: User ID 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" } } }

Field Name	Field ID	Purpose/Notes
User ID	module_field_14/order_1
User Email	module_field_14/order_2
Status	module_field_14/order_3	Either Intent Created, Payment Complete or a custom status of your choice.
Billing Address	module_field_14/order_4	Not yet used by Siteglide
Shipping Address	module_field_14/order_5	Not yet used by Siteglide
Payment Method	module_field_14/order_6	Not yet used by Siteglide. You must not use this field to store full card numbers. You may choose to store either an ID or fingerprint (e.g. https://stripe.com/docs/api/payment_methods) which your Payment Gateway uses to reference a payment method.
Shipping Method ID	module_field_14/order_7
Tracking Number	module_field_14/order_8	Not yet used by Siteglide
Total Price	module_field_14/order_9
Currency	module_field_14/order_10
Discount Code	module_field_14/order_11
Shipping Method Price	module_field_14/order_12
Shipping Method Name	module_field_14/order_13
Discount Code ID	module_field_14/order_14

PayPal - Custom Parameters

Subscriptions