Adyen · LEQADA · Apr 15, 2019 · Apr 1, 2019 · Apr 2, 2019 · Apr 3, 2019
diff --git a/README.md b/README.md
@@ -1,9 +1,15 @@
 # commercetools-adyen-integration
-Integration between Commercetools and Adyen payment service provider
+This repository provides integration between Commercetools and Adyen payment service provider.
 
-## Glossary
-In this process, there are 3 parties involved:
+It contains two standalone modules that connects the two platforms.
+In order to make the integration run properly, both modules have to run.
+
+## Extension module
+Extension module interacts between CTP Platform and Adyen using [API Extensions](https://docs.commercetools.com/http-api-projects-api-extensions).
+1. Read [Integration Guide](./extension/docs/IntegrationGuide.md) for information how to integrate your shop with this module.  
+1. Read [Development Guide](./extension/docs/DevelopmentGuide.md) if you want to run the extension module by yourself or contribute to it.
+
+## Notification module
+Notification module is a public service which receives notifications sent by Adyen,
+processes them and saves on a commercetools project.
 
-Frontend - the browser part of the shop. This is what the user interacts with.
-Backend - the shop server which supplies front end with data.
-Adyen-integration - hosted service (this repository) which exposes public endpoints.
diff --git a/docs/BEST_PRACTICES.md b/docs/BEST_PRACTICES.md
@@ -0,0 +1,8 @@
+## Deployment best practices
+
+- Both modules should be deployed as a publicly exposed services.
+- Modules are **stateless** which makes running multiple instances in parallel possible.
+It is recommended to **enable horizontal scaling**
+with at least 2 running instances at the same time in order to omit downtime
+possibility.
+- It's also recommended to use HTTPS.
diff --git a/notification/README.md b/notification/README.md
@@ -0,0 +1,72 @@
+# Notification Module
+
+Notification module is a part of the commercetools Adyen integration
+which is responsible for receiving notifications from Adyen payment service provider,
+processing and storing them on a commercetools platform project.
+
+![image](https://user-images.githubusercontent.com/9251453/56137277-bbad3500-5f94-11e9-8559-7d46113dbbf6.png)
+
+Check out the [Integration Guide](./docs/IntegrationGuide.md) for more information on how to deploy and configure the notification module
+
+Check out the [Development Guide](./docs/DevelopmentGuide.md) for more information on how to install dependencies and run tests
+
+### Processing notifications
+Adyen sends notifications which look like this:
+
+```
+{
+  "live": "false",
+  "notificationItems": [
+    {
+      "NotificationRequestItem": {
+        "additionalData": {
+          "expiryDate": "12\/2012",
+          " NAME1 ": "VALUE1",
+          "authCode": "1234",
+          "cardSummary": "7777",
+          "totalFraudScore": "10",
+          "NAME2": "  VALUE2  ",
+          "fraudCheck-6-ShopperIpUsage": "10"
+        },
+        "amount": {
+          "currency": "EUR",
+          "value": 10100
+        },
+        "eventCode": "AUTHORISATION",
+        "eventDate": "2019-01-30T18:16:22+01:00",
+        "merchantAccountCode": "XXX",
+        "merchantReference": "YYY",
+        "operations": [
+          "CANCEL",
+          "CAPTURE",
+          "REFUND"
+        ],
+        "paymentMethod": "visa",
+        "pspReference": "test_AUTHORISATION_1",
+        "reason": "1234:7777:12\/2012",
+        "success": "true"
+      }
+    }
+  ]
+}
+
+```
+
+Notification module maps `eventCode` and `success` pair to
+commercetools [transactionType](https://docs.commercetools.com/http-api-projects-payments#transactiontype)
+and [transactionState](https://docs.commercetools.com/http-api-projects-payments#transactionstate).
+
+All mappings can be found in the [adyen-events.json](./resources/adyen-events.json) file.
+
+After finding a mapping the Notification module will find a proper
+payment on a commercetools project.
+
+If there is no transaction on the payment with the received `transactionType`
+the Notification module will create a transaction with the received `transactionType` and
+`transactionState`. Otherwise it will update the existing transaction with a new `transactionState`.
+
+Received notification will be stored on the [interfaceInteraction](https://docs.commercetools.com/http-api-projects-payments#add-interfaceinteraction) of the payment.
+
+If mapping for the received notification was not found then payment will be updated only with a new `interfaceInteraction`.
+
+If payment was not found then the notification will be skipped from processing.
diff --git a/notification/docs/DevelopmentGuide.md b/notification/docs/DevelopmentGuide.md
@@ -0,0 +1,39 @@
+# Development guide
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Contents**
+
+- [Requirements](#requirements)
+- [Run Module](#run-module)
+- [Run Tests](#run-tests)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Requirements
+Node.js version 8 LTS or higher is supported.
+
+## Run Module
+Execute `npm сi` to download all dependencies.
+
+In order to run the notification module, you have to provide following environmental variables:
+
+Name | Content | Required | Default value
+------------ | ------------- | ------------- | -------------
+CTP_PROJECT_KEY | commercetools project key (you can get in the [commercetools Merchant Center](https://mc.commercetools.com)) | **YES** |
+CTP_CLIENT_ID | commercetools client ID with `manage_types` and `manage_payments` scopes (you can get in the [commercetools Merchant Center](https://mc.commercetools.com)) | **YES** |
+CTP_CLIENT_SECRET | commercetools client secret (you can get in the [commercetools Merchant Center](https://mc.commercetools.com)) | **YES** |
+LOG_LEVEL | bunyan log level (`trace`, `debug`, `info`, `warn`, `error`, `fatal`)| NO | `info`
+PORT | port on which the application will run | NO | 443
+
+Don't forget to provide all required environment variables
+After setting all variables, execute command `npm run start` to run the module.
-After setting all variables, execute command `npm run start` to run the module.
+After setting all environment variables, execute command `npm run start` to run the module.
-After setting all variables, execute command `npm run start` to run the module.
+After setting all environment variables, execute command `npm run start` to run the module.
+
+## Run Tests
+
+- Execute `npm run unit-test` to run [Unit tests](../test/unit)
+- Execute `npm run integration-test` to run [Integration tests](../test/integration) (all required environment variables must be set)
+
+Execute `npm run test` to run all tests
+
+In the end a code coverage report will be printed.
diff --git a/notification/docs/IntegrationGuide.md b/notification/docs/IntegrationGuide.md
@@ -0,0 +1,86 @@
+# Integration of payment into checkout process
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Contents**
+
+  - [Glossary](#glossary)
+  - [Requirements](#requirements)
+- [Deployment](#deployment)
+      - [Environment variables to configure the notification module:](#environment-variables-to-configure-the-notification-module)
+  - [Deployment using Docker image](#deployment-using-docker-image)
+      - [Pull the image](#pull-the-image)
+      - [Run the container](#run-the-container)
+- [Configuration](#configuration)
+    - [Register the endpoint](#register-the-endpoint)
+- [FAQ](#faq)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+### Glossary
+In this process, there are 2 parties involved:
+
+ - **Adyen** - the payment provider which will send notifications
+ - **Notification module** - hosted service that receives notifications from Adyen,
+processes and stores them on a commercetools platform project.
+
+### Requirements 
+Node.js version 8 LTS or higher is supported.
+
+## Deployment
+
+##### Environment variables to configure the notification module:
+Name | Content | Required | Default value
+------------ | ------------- | ------------- | -------------
+CTP_PROJECT_KEY | commercetools project key (you can get in the commercetools Merchant Center) | **YES** |
+CTP_CLIENT_ID | commercetools client ID (you can get in the commercetools Merchant Center) | **YES** |
+CTP_CLIENT_SECRET | commercetools client secret (you can get in the commercetools Merchant Center) | **YES** |
+LOG_LEVEL | bunyan log level (`trace`, `debug`, `info`, `warn`, `error`, `fatal`)| NO | `info`
+PORT | port on which the application will run | NO | 443
+
+Check out the deployment [Best Practices documentation](../../docs/BEST_PRACTICES.md)
+
+
+### Deployment using Docker image
+For easy deployment you can use the [Notification module docker image](https://hub.docker.com/r/commercetools/commercetools-adyen-integration-notification/tags).
+
+##### Pull the image 
+```
+docker pull commercetools/commercetools-adyen-integration-notification:X.X.X
+```
+(replace X.X.X with a image tag)
+
+##### Run the container
+
+Replace all `XXX` values and execute:
+```
+docker run -e CTP_PROJECT_KEY=XXX -e CTP_CLIENT_ID=XXX -e CTP_CLIENT_SECRET=XXX ctp-adyen-integration-notification:XXX
+```
+
+## Configuration
+
+After deployment you have to register the Notification module public URL in the Adyen Customer Area in order to receive notifications.
+
+#### Register the endpoint
+ 1. Go to your [Adyen Customer Area](https://ca-live.adyen.com/ca/ca/login.shtml)
+ 1. Hover **Account** in the menu and select **Server communication**
+![image](https://user-images.githubusercontent.com/9251453/55414133-e5b13100-556a-11e9-89ac-a9ebbf72bfdf.png)
+ 1. You will see the list of available notifications. Click on **add** button of the
+"Standard notification"
+ 1. In the opened form change the **URL** under the **Transport** section to the one
+ which exposes the notification module
+ 1. Select the **Active** checkbox under the same section
+ 1. Click on **Save Configuration** button below to complete subscription
+
+Check out the Adyen documentation on how to set up notifications for more information: [Set up notifications](https://docs.adyen.com/developers/development-resources/notifications/set-up-notifications)
+
+## FAQ
+
+Can I remove a subscription I created?
+
+- If you accidentally created a subscription you can edit it and uncheck the **Active** checkbox so Adyen doesn't
+send there notifications. Then you can contact the Adyen support and ask them to remove the subscription
+
+Will we lose a notification if it was not processed for some reason?
+- Adyen will queue notifications when the notification service was not reachable or it didn't return a success message
+  and will try to send it later