• Generate URL Ecommpay Payment Page for one-step purchase.
• Processing callbacks from Ecommpay Platform, and update payments in Commercetools.
• Refund a payment back to the shopper.

This plugin simplifies integration with Ecommpay of merchants using the Commercetools platform. The plugin contains the following modules:

• Extension module - URL generation module for opening the Payment Page and performing refund operations
• Notification module - Ecommpay Gate callback processing module and updating payment information in Commercetools.

The modules are implemented as a "function as a service". It is possible to place these modules in a local or cloud service (AWS Lambda, Azure Functions or Google Cloud Functions). For modules to interact with Commercetools, the API Extensions should be used, which, under certain triggers, will access the functions of the plug-in modules.

When creating or updating a payment, Commercetools will call the Extension Module to generate a link to the Payment Page. The Payment Page link supports all additional parameters for opening the payment page. If you need to open the Payment Page with additional parameters (including fields in the Billing Address section), they must be passed in the request to create or update a payment in the custom "initial_request" field.

{
  "custom": {
    "type": {
      "typeId": "type",
      "key": "ecommpay-integration"
    },
    "fields": {
      "initial_request": "\"{\\\"customer_id\\\":123,\\\"billing_country\\\":\\\"DE\\\",\\\"customer_country\\\":\\\"DE\\\"}\""
    }
  }
}

After receiving the Payment Page URL, you need to open the page using one of the described methods:

• Opening Payment Page as a separate HTML page
• Opening Payment Page in a modal window
• Opening Payment Page in an iframe element of an HTML page

Next, you need to link the payment to the order yourself using the API Commercetools.

The Notification module will process the callback-notification from Ecommpay Gate and update the information in the payment.

Example flow:

To make a refund, you must send a request to Commercetools to update the payment with the Refund transaction type.

{
  "version": 1,
  "actions": [
    {
      "action": "addTransaction",
      "transaction": {
        "type": "Refund",
        "amount": {
          "centAmount": 8300,
          "currencyCode": "EUR"
        }
      }
    }
  ]
}

Next, the Extension Module will make a refund request to Ecommpay Gate.

In order for ECP modules to send requests to the project in Commetcetools, you need to configure the API Client in your commercetools project with access to the following grants:

• manage_payments
• manage_types

1. Submit the application for connecting to the payment platform, provide all necessary information, and receive a notification from ecommpay about the possibility to process payments.
2. Create zip archive(s) with extension and notification functions.
3. Create the notification function on one of the cloud platforms with the environment variable (ECP_PARAMETERS). Create and get this endpoint URL (this is the callback URL). Pay attention to the timeout value, it should be more than 15 seconds.
4. Create the extension function on one of the cloud platforms with the environment variable (ECP_PARAMETERS). Create and get this endpoint URL (this is the URL for Commercetools).
5. Upload payment-interface-interaction and payment extension into Commercetools.
6. Upload API extension with the URL received in point 4. We strongly recommend enabling authentication with your cloud platform (how to do it see here)
7. Add ecompay payment methods, script and styles to your store and pass "ecommpay-integration" value in the paymentMethodInfo.paymentInterface when creating payment. You can also pass the custom field "initial_request" with additional parameters for the payment page. After creating the payment, direct the user to the payment page.

Deploy the modules in one of the following ways:

• Deployment as a Node web server

• Deployment as a Docker containers

• Deployment as an Amazon Lambda Serverless Function

• Deployment as an Azure Cloud Serverless Function

• Deployment as a GCP Function

Set custom types to be able to save the payment information of Ecommpay transactions in the payment object.

For Payment interface interaction object:

{
  "key": "ecommpay-integration-interaction-payment-type",
  "name": {
    "en": "commercetools Ecommpay integration payment interface interaction type"
  },
  "resourceTypeIds": ["payment-interface-interaction"],
  "fieldDefinitions": [
    {
      "name": "operation_id",
      "label": {
        "en": "Operation id"
      },
      "required": false,
      "type": {
        "name": "Number"
      },
      "inputHint": "SingleLine"
    },
    {
      "name": "operation_type",
      "label": {
        "en": "Operation type"
      },
      "required": false,
      "type": {
        "name": "String"
      },
      "inputHint": "SingleLine"
    },
    {
      "name": "operation_status",
      "label": {
        "en": "Operation status"
      },
      "required": false,
      "type": {
        "name": "String"
      },
      "inputHint": "SingleLine"
    },
    {
      "name": "date",
      "label": {
        "en": "Date"
      },
      "required": false,
      "type": {
        "name": "DateTime"
      },
      "inputHint": "SingleLine"
    },
    {
      "name": "sum_initial",
      "label": {
        "en": "Sum initial"
      },
      "required": false,
      "type": {
        "name": "String"
      },
      "inputHint": "SingleLine"
    },
    {
      "name": "sum_converted",
      "label": {
        "en": "Sum converted"
      },
      "required": false,
      "type": {
        "name": "String"
      },
      "inputHint": "SingleLine"
    },
    {
      "name": "message",
      "label": {
        "en": "Message"
      },
      "required": false,
      "type": {
        "name": "String"
      },
      "inputHint": "SingleLine"
    }
  ]
}

For Payment object:

{
  "key": "ecommpay-integration",
  "name": {
    "en": "commercetools ecommpay integration"
  },
  "resourceTypeIds": ["payment"],
  "fieldDefinitions": [
        {
      "name": "initial_request",
      "label": {
        "en": "Initial request"
      },
      "type": {
        "name": "String"
      },
      "inputHint": "SingleLine",
      "required": false
    },
    {
      "name": "pp_url",
      "label": {
        "en": "Payment Page URL"
      },
      "type": {
        "name": "String"
      },
      "inputHint": "SingleLine",
      "required": false
    }
  ]
}

We strongly recommend enabling authentication with your cloud platform (how to do it see here)
If you deploy the extension module as a standalone server you should use the header authorization.

Set the API Extension to create a payment with JSON:

{
  "key": "ecommpay-integration-payment-extension",
  "destination": {
    "type": "HTTP",
    "url": "${ExtensionUrl}"
  },
  "triggers": [
    {
      "resourceTypeId": "payment",
      "actions": ["Create","Update"],
      "condition": "paymentMethodInfo is defined AND paymentMethodInfo(paymentInterface is defined) AND paymentMethodInfo(paymentInterface=\"ecommpay-integration\")"
    }
  ],
  "timeoutInMs": 10000
}