emerchantpay with Umbraco Forms

Details an integration available for emerchantpay with Umbraco Forms, built and maintained by Umbraco HQ.

This integration provides a custom workflow for handling online payments using a hosted payment page provided by emerchantpay.

Package Links

• NuGet install

• Source code

• Umbraco marketplace listing

Minimum version requirements

Umbraco CMS

To ensure compatibility, check the Dependencies tab on NuGet for the required Umbraco CMS version. For example, see Umbraco.Forms.Integrations.Commerce.emerchantpay.

How To Use

To get started with emerchantpay a merchant needs to be onboarded. This will allow you to get a merchant ID and obtain the keys required by the integration.

To begin the onboarding process and obtain the merchant account, you need to fill out this form.

Afterwards, a member of the emerchantpay team will reach out to you.

Authentication

All requests to emerchantpay API are authenticated by providing the merchant's username and password.

If the configuration is incomplete, the user will receive an error message.

Configuration

The below configuration is required. It consists of authentication settings, merchant specific details and customizable payment fields. Some configuration items are stored as an array of strings or a dictionary, and parsed using a specific service.

Versions 9 and above

appsettings.json

{
  "Umbraco": {
    "Forms": {
      "Integrations": {
        "Commerce": {
          "Emerchantpay": {
            "Settings": {
              "GatewayBaseUrl": "https://staging.gate.emerchantpay.net/",
              "WpfUrl": "https://staging.wpf.emerchantpay.net/wpf/",
              "Username": "[your_merchant_username]",
              "Password": "[your_merchant_password]",
              "UmbracoBaseUrl": "[your_website_url]",
              "Supplier": "Umbraco",
              "Usage": "Payment Gateway using Umbraco Forms",
              "Currencies": {
                "USD": "US Dollar",
                "EUR": "Euro",
                "GBP": "British Pound",
                "DKK": "Danish Krone"
              },
              "TransactionTypes": [ "authorize", "sale" ],
              "MappingFields": [ "Email", "FirstName", "LastName" ]
            }
          }
        }
      }
    }
  }
}

Version 8

web.config

<appSettings>
...
  <add key="Umbraco.Forms.Integrations.Commerce.eMerchantPay.GatewayBaseurl" value="https://staging.gate.emerchantpay.net/"/>
  <add key="Umbraco.Forms.Integrations.Commerce.eMerchantPay.WpfUrl" value="https://staging.wpf.emerchantpay.net/wpf"/>
  <add key="Umbraco.Forms.Integrations.Commerce.eMerchantPay.Username" value="[your_merchant_username]"/>
  <add key="Umbraco.Forms.Integrations.Commerce.eMerchantPay.Password" value="[your_merchant_password]"/>
  <add key="Umbraco.Forms.Integrations.Commerce.eMerchantPay.UmbracoBaseUrl" value="[your_website_url]"/>
  <add key="Umbraco.Forms.Integrations.Commerce.eMerchantPay.Supplier" value="Umbraco"/>
  <add key="Umbraco.Forms.Integrations.Commerce.eMerchantPay.Usage" value="Payment Gateway using Umbraco Forms"/>
  <add key="Umbraco.Forms.Integrations.Commerce.eMerchantPay.Currencies" value="USD,US Dollar;EUR,Euro;GBP,British Pound;DKK,Danish Krone"/>
  <add key="Umbraco.Forms.Integrations.Commerce.eMerchantPay.TransactionTypes" value="authorize;sale"/>
  <add key="Umbraco.Forms.Integrations.Commerce.eMerchantPay.MappingFields" value="Email;FirstName;LastName"/>
...
</appSettings>

Working with the integration

Follow the steps below to start using the integration.

1. Attach the emerchantpay Gateway workflow to a form.

2. Map the following values with matching form fields:

   • Amount

   • Currency

   • Number of Items

   • Record Status

   • Record Payment Unique ID

   • Consumer Details

3. Configure the event handlers for payment successfully processed, failed, or canceled.

A consumer has the following properties available that can be mapped against form fields:

• Email

• FirstName

• LastName

• Address1

• Address2

• ZipCode

• City

• State

• Country

• Phone

When a form is submitted on the website, the workflow will execute. Two data payloads will be sent to emerchantpay. One for creating or retrieving the details of a consumer and the other for creating a payment.

The response for the second request will provide the URL for the hosted payment page, and the user will be redirected there.

On completing the payment the emerchantpay API will return the user to the page provided in the matching event handler of the workflow.