Add In-Person Payments Integration - TerminalApi /sync (#191)

* Added In-Person Payments cloud /terminal-api/sync integration-demo
  * Make a payment with specified amount and currency
  * Make referenced refund requests (reversals)
  * Making abort requests to cancel initiated transaction on the terminal
  * Make transaction status requests
  * Receive webhooks for reversals asynchronously
* Added paths ignore to prevent us from running tests again when modifying a README

.github/dependabot.yml

@@ -24,3 +24,7 @@ updates:
     directory: "/giving-example"
     schedule:
       interval: "daily"
+  - package-ecosystem: "gradle"
+    directory: "/in-person-payments-example"
+    schedule:
+      interval: "daily"

.github/workflows/build.yml

@@ -3,8 +3,20 @@ name: Java CI with Gradle
 on:
   push:
     branches: [ main ]
+    paths-ignore:
+      - '**/README.md'
+      - README.md
+      - .gitignore
+      - .gitpod.yml
+      - LICENSE
   pull_request:
     branches: [ main ]
+    paths-ignore:
+      - '**/README.md'
+      - README.md
+      - .gitignore
+      - .gitpod.yml
+      - LICENSE
 
 jobs:
   build-checkout:

.github/workflows/e2e.yml

@@ -4,8 +4,20 @@ on:
   workflow_dispatch:
   push:
     branches: [ main ]
+    paths-ignore:
+      - '**/README.md'
+      - README.md
+      - .gitignore
+      - .gitpod.yml
+      - LICENSE
   pull_request:
     branches: [ main ]
+    paths-ignore:
+      - '**/README.md'
+      - README.md
+      - .gitignore
+      - .gitpod.yml
+      - LICENSE
 
 jobs:
   checkout:

.gitpod.yml

@@ -27,6 +27,10 @@ tasks:
           echo "Build giftcard-example application"
           cd giftcard-example && ./gradlew bootJar
         ;;
+        "in-person-payments-example")
+          echo "Build in-person-payments-example application"
+          cd in-person-payments-example && ./gradlew bootJar
+        ;;
         "subscription-example")
           echo "Build subscription-example application"
           cd subscription-example && ./gradlew bootJar

README.md

@@ -11,7 +11,8 @@ Get started by navigating to one of the supported demos below.
 |                                                    Demos | Description                                                                      | Details                                 |
 |---------------------------------------------------------:|:---------------------------------------------------------------------------------|:----------------------------------------|
 |                   [`Checkout Example`](checkout-example) | E-commerce checkout flow with different payment methods.                         | [See below](#checkout-example)          | 
-| [`Advanced Checkout Example`](checkout-example-advanced) | E-commerce checkout flow with different payment methods, using the 3 steps flow. | [See below](#advanced-checkout-example) | 
+| [`Advanced Checkout Example`](checkout-example-advanced) | E-commerce checkout flow with different payment methods, using the 3 steps flow. | [See below](#advanced-checkout-example) |
+| [`In-person Payments Example`](in-person-payments-example) | In-person payments using a POS terminal and the terminal-api/sync endpoint.    | [See below](#in-person-payments-example) |
 |                  [`Gift Card Example`](giftcard-example) | Gift Cards checkout flow using partial orders.                                   | [See below](#gift-card-example)         | 
 |               [`Pay By Link Example`](paybylink-example) | Create payment links in seconds.                                                 | [See below](#paybylink-example)         | 
 |           [`Subscription Example`](subscription-example) | Subscription flow using Adyen tokenization.                                      | [See below](#subscription-example)      | 
@@ -40,6 +41,15 @@ See the [advanced integration flow](https://docs.adyen.com/online-payments/web-d
 
 ![Card Checkout Demo](checkout-example/src/main/resources/static/images/cardcheckout.gif)
 
+## [In-person Payments Example](in-person-payments-example)
+[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/adyen-examples/adyen-dotnet-online-payments/tree/main/in-person-payments-example)
+
+[First time with Gitpod?](https://github.com/adyen-examples/.github/blob/main/pages/gitpod-get-started.md)
+
+The [in-person payments example](in-person-payments-example) features an in-person payment [cloud terminal API](https://docs.adyen.com/point-of-sale/design-your-integration/choose-your-architecture/cloud/) integration. Within this demo app, you can make in-person payments using a terminal, initiate reversals (refunds) and check transaction statuses.
+
+![Card In-person Payments Demo](in-person-payments-example/wwwroot/images/cardinpersonpayments.gif)
+
 ## [Gift Card Example](giftcard-example)
 
 [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/adyen-examples/adyen-java-spring-online-payments/tree/main/giftcard-example)  

in-person-payments-example/Dockerfile

@@ -0,0 +1,3 @@
+FROM amazoncorretto:17-alpine-jdk
+COPY build/libs/in-person-payments-example-0.0.1-SNAPSHOT.jar adyen-java-spring-in-person-payments-example-0.0.1-SNAPSHOT.jar
+ENTRYPOINT ["java","-jar","/adyen-java-spring-in-person-payments-example-0.0.1-SNAPSHOT.jar"]

in-person-payments-example/README.md

@@ -0,0 +1,103 @@
+# Adyen [In-person Payment Demo](https://docs.adyen.com/point-of-sale/) Integration Demo
+
+## Run demo in one-click
+[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/adyen-examples/adyen-java-spring-online-payments/tree/main/in-person-payments-example)
+ [First time with Gitpod?](https://github.com/adyen-examples/.github/blob/main/pages/gitpod-get-started.md)
+
+## Description
+This demo shows developers how to use the Adyen [Cloud Terminal API](https://docs.adyen.com/point-of-sale/design-your-integration/choose-your-architecture/cloud/) `/terminal-api/sync` to make requests to your connected terminal.
+
+The following implementations are included:
+- [Payment requests](https://docs.adyen.com/point-of-sale/basic-tapi-integration/make-a-payment/)
+- [Referenced refund requests](https://docs.adyen.com/point-of-sale/basic-tapi-integration/refund-payment/referenced/)
+- [Cancel/abort requests](https://docs.adyen.com/point-of-sale/basic-tapi-integration/cancel-a-transaction/)
+- [Transaction status requests](https://docs.adyen.com/point-of-sale/basic-tapi-integration/verify-transaction-status/)
+
+There are typically two ways to integrate in-person payments: local or cloud communications.
+To find out which solution (or hybrid) suits your needs, visit the following [documentation page](https://docs.adyen.com/point-of-sale/design-your-integration/choose-your-architecture/#choosing-between-cloud-and-local).
+
+You can find the [Terminal API documentation](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/terminal-api-reference/) here.
+
+This demo integrates the Adyen API Library for Java ([GitHub](https://github.com/Adyen/adyen-java-api-library) | [Docs](https://docs.adyen.com/development-resources/libraries/?tab=java_1)).
+You can find the [Terminal API documentation](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/terminal-api-reference/) here.
+
+![In-person Payments Demo](wwwroot/images/cardinpersonpayments.gif)
+
+
+## Requirements
+- A [terminal device](https://docs.adyen.com/point-of-sale/user-manuals/) and a [test card](https://docs.adyen.com/point-of-sale/testing-pos-payments/) from Adyen
+- [Adyen API Credentials](https://docs.adyen.com/development-resources/api-credentials/)
+- Java 17
+
+
+## 1. Installation
+```
+git clone https://github.com/adyen-examples/adyen-java-spring-online-payments.git
+```
+
+## 2. Set the environment variables
+* [API key](https://docs.adyen.com/user-management/how-to-get-the-api-key)
+* [HMAC Key](https://docs.adyen.com/development-resources/webhooks/verify-hmac-signatures)
+* `ADYEN_POS_POI_ID`: the unique ID of your payment terminal for the NEXO Sale to POI protocol.
+  - **Format:** `[device model]-[serial number]` **Example:** `V400m-123456789`
+
+
+On Linux/Mac/Windows export/set the environment variables.
+```shell
+export ADYEN_API_KEY=yourAdyenApiKey
+export ADYEN_HMAC_KEY=yourHmacKey
+export ADYEN_POS_POI_ID=v400m-123456789
+```
+
+Alternatively, it's possible to define the variables in the `application.properties`.
+```txt
+ADYEN_API_KEY=yourAdyenApiKey
+ADYEN_HMAC_KEY=yourHmacKey
+ADYEN_POS_POI_ID=v400m-123456789
+```
+
+## 4. Run the application
+
+```
+cd in-person-payments-example
+
+./gradlew bootRun
+```
+
+# Webhooks
+
+Webhooks deliver asynchronous notifications about the payment status and other events that are important to receive and process.
+You can find more information about webhooks in [this blog post](https://www.adyen.com/knowledge-hub/consuming-webhooks).
+
+### Webhook setup
+
+In the Customer Area under the `Developers → Webhooks` section, [create](https://docs.adyen.com/development-resources/webhooks/#set-up-webhooks-in-your-customer-area) a new `Standard webhook`.
+
+A good practice is to set up basic authentication, copy the generated HMAC Key and set it as an environment variable. The application will use this to verify the [HMAC signatures](https://docs.adyen.com/development-resources/webhooks/verify-hmac-signatures/).
+
+Make sure the webhook is **enabled**, so it can receive notifications.
+
+### Expose an endpoint
+
+This demo provides a simple webhook implementation exposed at `/api/webhooks/notifications` that shows you how to receive, validate and consume the webhook payload.
+
+### Test your webhook
+
+The following webhooks `events` should be enabled:
+* **AUTHORISATION**
+* **CANCEL_OR_REFUND**
+* **REFUND_FAILED**
+* **REFUNDED_REVERSE**
+
+
+To make sure that the Adyen platform can reach your application, we have written a [Webhooks Testing Guide](https://github.com/adyen-examples/.github/blob/main/pages/webhooks-testing.md)
+that explores several options on how you can easily achieve this (e.g. running on localhost or cloud).
+
+
+## Usage
+1. Select the cloud terminal api integration.
+2. Select a table.
+3. Select pay to perform a payment.
+4. Complete the instructions on your terminal.
+5. Select reversal to refund the payment.
+6. If webhooks are set up, listen for the notifications to update the payment status (reversals/refunds happen asynchronously and may take some time to receive).

in-person-payments-example/build.gradle

@@ -0,0 +1,29 @@
+plugins {
+    alias(libs.plugins.spring.framework)
+    alias(libs.plugins.spring.dependency)
+
+    id 'java'
+}
+
+group = 'com.adyen'
+version = '0.0.1-SNAPSHOT'
+
+sourceCompatibility = 17
+targetCompatibility = 17
+
+repositories {
+	mavenCentral()
+}
+
+dependencies {
+    implementation libs.adyen.java
+    implementation libs.bundles.spring
+
+    testImplementation(libs.bundles.spring.test){
+        exclude (group: 'org.junit.vintage', module: 'junit-vintage-engine')
+    }
+}
+
+test {
+	useJUnitPlatform()
+}

in-person-payments-example/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,5 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-7.6-bin.zip
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists