Emerchantpay Gateway Copy

Integrating Umbraco Forms with emerchantpay

A new tool for handling online payments using Umbraco Forms

Adriancojocariu 500X500
Written by Adrian Cojocariu

With emerchantpay, Umbraco is expanding our DXP capabilities through an integration that enables you to handle online payments using Umbraco Forms! In recent releases, we’ve showcased integrations covering various areas like SEO, CRM, and Automation, and now, extending the Commerce ecosystem, we are taking you to explore new frontiers. This new integration provides an extension for Umbraco Forms with a custom workflow for handling online payments using a hosted payment page provided by 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


Screenshot: Customer journey map


Umbraco Forms → emerchantpay Data Workflow

Screenshot: Umbraco Forms emerchantpay dataflow


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.




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





Array of Strings

String with elements separated by ;

Strings Array


String with objects separated by ; and Key/Value elements by ,

JSON Object


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


Screenshot: Error message - Account detail missing


Workflow setup

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


Screenshot: Choose workflow - emerchantpay gateway


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).


Screenshot: Specify payment amount


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


Screenshot: select field - 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.


Screenshot: Customer details - select customer property Screenshot: Codestrip


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.


Screenshot: Cancen URL - select content - contact


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


Screenshot: Select customer property


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 …


Screenshot: Form creation


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


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:


Screenshot: payment form entries



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.

Loved by developers, used by thousands around the world!

One of the biggest benefits of using Umbraco is that we have the friendliest Open Source community on this planet. A community that's incredibly pro-active, extremely talented and helpful.

If you get an idea for something you would like to build in Umbraco, chances are that someone has already built it. And if you have a question, are looking for documentation or need friendly advice, go ahead and ask on the community forums.

Want to be updated on everything Umbraco?

Sign up for the Umbraco newsletter and get the latest news and special offers sent directly to your inbox