Integrating Umbraco Forms with emerchantpay

The integration with emerchantpay allows businesses to accept one-off payments in Umbraco Forms. So, it is not a full e-commerce solution, but a great option for businesses that want to accept payments for items like event tickets. Once businesses have their emerchantpay account set up, they will be able to create a payment form within minutes and start accepting online payments. 

All payment requests will simply re-direct to emerchantpay’s web payment form, hosted on their secure servers. So, the PCI DSS compliance requirements for handling customer data are covered by emerchantpay. When you set up your web payment page with emerchantpay, you’ll be able to choose the payment methods you want to accept and customize the page with your branding. To learn more about the configuration options for the web payment form, check out emerchantpay’s documentation. 

In addition to the Forms integration, emerchantpay’s NuGet package can provide businesses with a full eCommerce solution. Connect with their team today to learn more.

About emerchantpay

emerchantpay is a leading global payment service provider for online, mobile, in-store, and over-the-phone payments. Its global payments solution is available through a simple integration, offering a wealth of features, including global acquiring, alternative payment methods, advanced fraud management and performance optimization. It works with businesses of all sizes across various industries to create bespoke solutions and strategies that help them increase their payment systems' efficiency and profitability. With cutting-edge technology and a unique customer-centric approach, they empower businesses to design seamless and engaging payment experiences for their consumers.

Learn more about emerchantpay: www.emerchantpay.com

Getting Started with the Forms integration

To get started with the emerchantpay package for Umbraco Forms, you must have an emerchantpay merchant account.  To begin, fill out a form on their website, and a member of their team will reach out to you. 

The focus of our extension for Umbraco Forms is to provide businesses with a custom workflow for handling payments through emerchantpay’s Web Payment Form (WPF).

Customer Journey Map

A merchant getting started with emerchantpay and Umbraco will need to make sure that they have an emerchantpay merchant account enabled and then cover these steps:

1. Package Installation
2. Site Settings
3. Workflow Setup

Umbraco Forms → emerchantpay Data Workflow

Before getting into specifics, it is mandatory that the setup procedure from the next chapter is completed successfully! Please refer to the setup documentation if you encounter any issues with the workflow detailed below.

Data is exchanged between the Umbraco website and emerchantpay API through the following steps:

1. User submits the form that has the emerchantpay Gateway Umbraco Forms workflow configured and attached. 
   1.  ConsumerService issues a request to the API to create a new consumer using the Email value specified in the form.
      
      
   2.  If the response code specifies that the consumer already exists, then the ConsumerService will issue a new request to retrieve the consumer ID; otherwise, the consumer gets created and the ID returned in the response.
      
      
   3. PaymentService issues a request to emerchantpay’s payment gateway carrying the mandatory, initial payload. If successful, the response will contain the URL of the WPF form, and will redirect the user there.
      
      
2. Depending on the mapping fields that have been sent in the payment payload, the WPF form will be prefilled with those values.
3. After completing the checkout process, the user will be redirected back to the Umbraco website.
4. After the payment has been processed and reached a final state, the merchant will receive a notification, using the supplied notification URL in the payment payload.
5. The notification endpoint  will validate the payment’s integrity and make a new request to the emerchantpay API to reconcile.

The emerchantpay API endpoints accept and return XML data.

If you want to find out more about the WPF, please refer to this section of emerchantpay’s API documentation

Setting up the Umbraco Forms workflow

Getting started with the integration requires you to make sure that the following steps are covered:

Package installation

use the backoffice Packages section or install the NuGet package. 

Site settings

consisting of authentication settings, merchant-specific details and customizable payment fields. Settings vary from Umbraco 8 to 9+, and use different services to parse them: here and here.

Please edit the site settings to insert your unique merchant username and password from emerchantpay. This information will be provided by emerchantpay's Tech Support team.

and

As you might have noticed there are two patterns emerging here:

If the merchant’s Username or Password values are missing, an error will be prompted when trying to set up the workflow.

Workflow setup

The values sent in the Consumer or Payment payloads are mapped with form fields, taking into account the following specifications:

a. Amount → the value needs to be specified without a decimal point, the emerchantpay API will consider the last two digits as decimals (e.g. 10000 = 100.00 in the WPF form).

b. Currency → picked from the settings of the website.

c. Number of Items → allows the merchant to sell an item by quantity. If value is specified, the final payable amount will be the result of Amount x Number_of_Items

d. Record Status and Record Payment Unique ID → these need to be hidden fields in the form, and they will hold the status of the payment (new, approved, failed, canceled) and the unique ID of the payment. The unique ID of the payment is very important as it will be a query string parameter of the notification URL sent as part of the payment payload when the PaymentService sends a request to Genesis. When the payment will be finalized and the emerchantpay API will send a notification, this unique ID will be used to identify the record data of the form and update the status.

e. Consumer Details → the available properties that can be sent with the payloads are: Email, FirstName, LastName, Address1, Address2, ZipCode, City, State, Country, Phone, but the merchant can choose which of them are required to be sent with the payment payload by specifying them in the MappingFields setting.

f. Four event handlers: three configurable from the workflow, for payment successfully processed, failed or canceled, and one API endpoint which is used by emerchantpay’s API to notify about the status of the payment and update record data.

g. Approve Record → if payment is successful, this will mark the record as Approved in the notification event.

Managing payments using Umbraco Forms

Once the workflow has been configured without any errors, starting to process payments is like a walk in the park.

You just need to reference the form in a content page and voila …

After the form gets submitted, if no errors are returned by emerchantpay’s gateway you will be redirected to the WPF form:

If the checkout process has completed successfully, I need to congratulate you for your first purchase using Umbraco Forms and emerchantpay 😄 , you can go ahead and check your form entry to see the updated status of the payment:

Conclusion

The integration is open-sourced here and can be used as inspiration for your own integrations whether you are running a website on Umbraco 8, 9 or 10. You’re also welcome to submit contributions and raise issues. 

Minimum requirements for the integration are:

• Umbraco 8.5.4 and Umbraco Forms 8.13
• Umbraco 9.0.1 and Umbraco Forms 9.5.0
• Umbraco 10.1 and Umbraco Forms 10.1.0

You can find the integrations by searching for Umbraco.Forms.Integrations.Commerce.emerchantpay in the backoffice Package Section or head over to the Umbraco Forms emerchantpay Integration download page.