Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@Kwok-he-Chu
Kwok-he-Chu committed Jan 8, 2024
1 parent b98be47 commit 2929f8e
Showing 1 changed file with 36 additions and 69 deletions.
105 changes: 36 additions & 69 deletions authorisation-adjustment-example/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,21 +1,18 @@
# Adyen [Authorisation Adjustment](https://docs.adyen.com/online-payments/classic-integrations/modify-payments/adjust-authorisation) Integration Demo

This repository includes an adjust authorisation example for the following three use cases after a pre-authorised payment: incremental, decremental adjustments. Within this demo app, you'll find a simplified version of a hotel booking, where the shopper perform a booking and administrators can **[1] adjust** (increase/decrease) the payment amount, **[2] extend** the authorisation expiry date, **[3] capture** the final amount and **[4] reverse** (cancel or refund) an authorised payment.
## 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/authorisation-adjustment-example)

> **Note:** We've included a technical [blog post](https://www.adyen.com/knowledge-hub/pre-authorizations-and-authorization-adjustments-for-developers) that explains every step of this demo.
[First time with Gitpod?](https://github.com/adyen-examples/.github/blob/main/pages/gitpod-get-started.md)

![Authorisation Adjustment Card Demo](src/main/resources/static/images/cardauthorisationadjustment.gif)

## Run this integration in seconds using [Gitpod](https://gitpod.io/)
## Description

* Open your [Adyen Test Account](https://ca-test.adyen.com/ca/ca/overview/default.shtml) and create a set of [API keys](https://docs.adyen.com/user-management/how-to-get-the-api-key).
* Go to [gitpod account variables](https://gitpod.io/variables).
* Set the `ADYEN_API_KEY`, `ADYEN_CLIENT_KEY`, `ADYEN_HMAC_KEY` and `ADYEN_MERCHANT_ACCOUNT` variables.
* Click the button below!
This repository includes an adjust authorisation example for the following three use cases after a pre-authorised payment: incremental, decremental adjustments. Within this demo app, you'll find a simplified version of a hotel booking, where the shopper perform a booking and administrators can **[1] adjust** (increase/decrease) the payment amount, **[2] extend** the authorisation expiry date, **[3] capture** the final amount and **[4] reverse** (cancel or refund) an authorised payment.

[![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/authorisation-adjustment-example)
> **Note:** We've included a technical [blog post](https://www.adyen.com/knowledge-hub/pre-authorizations-and-authorization-adjustments-for-developers) that explains every step of this demo.
_NOTE: To allow the Adyen Drop-In and Components to load, you have to add `https://*.gitpod.io` as allowed origin for your chosen set of [API Credentials](https://ca-test.adyen.com/ca/ca/config/api_credentials_new.shtml)_
![Authorisation Adjustment Card Demo](src/main/resources/static/images/cardauthorisationadjustment.gif)


This demo leverages Adyen's API Library for Java ([GitHub](https://github.com/Adyen/adyen-java-api-library) | [Docs](https://docs.adyen.com/development-resources/libraries#java)).
Expand All @@ -24,7 +21,7 @@ This demo leverages Adyen's API Library for Java ([GitHub](https://github.com/Ad
- [Adyen API Credentials](https://docs.adyen.com/development-resources/api-credentials/)
- Java 17

## Installation
## 1. Installation

Clone this repository:

Expand All @@ -33,15 +30,14 @@ git clone https://github.com/adyen-examples/adyen-java-spring-online-payments.gi
```


## Usage

1. Create a `./.env` file with all required configuration
- [API key](https://docs.adyen.com/user-management/how-to-get-the-api-key)
- [Client Key](https://docs.adyen.com/user-management/client-side-authentication)
- [Merchant Account](https://docs.adyen.com/account/account-structure)
- [HMAC Key](https://docs.adyen.com/development-resources/webhooks/verify-hmac-signatures)
## 2. Set the environment variables
Create a `./.env` file with all required configuration
- [Adyen API key](https://docs.adyen.com/user-management/how-to-get-the-api-key)
- [Adyen Client Key](https://docs.adyen.com/user-management/client-side-authentication)
- [Adyen Merchant Account](https://docs.adyen.com/account/account-structure)
- [Adyen HMAC Key](https://docs.adyen.com/development-resources/webhooks/verify-hmac-signatures)

In your Customer Area, remember to include `http://localhost:8080` in the list of `Allowed Origins`.
In your Customer Area, remember to include `http://localhost:8080` in the list of `Allowed Origins` to allow the Adyen.Component to load.

```
PORT=8080
Expand All @@ -51,20 +47,19 @@ ADYEN_CLIENT_KEY="your_client_key_here"
ADYEN_HMAC_KEY="your_hmac_key_here"
```

2. Start the application:
3. Run the application

```
./gradlew bootRun
```

3. Visit [http://localhost:8080/](http://localhost:8080/).
4. Usage

To try out this application with test card numbers, visit [Test card numbers](https://docs.adyen.com/development-resources/test-cards/test-card-numbers). We recommend saving multiple test cards in your browser so you can test your integration faster in the future.

1. Make a booking in the `Booking View`
2. Visit the `Admin Panel` to see the incoming webhooks and perform operations on the initial preauthorisation.


A success scenario for a payment followed by two adjustments, a capture and a reversal looks like:

`AUTHORISATION` (preauthorisation) → `AUTHORISATION_ADJUSTMENT` (adjust) → `AUTHORISATION_ADJUSTMENT` (adjust) → `CAPTURE` (capture) → `CANCEL_OR_REFUND` (reversal)
Expand All @@ -74,64 +69,36 @@ The `EXTEND` operation in this sample is used to extend the expiry date manually

When CAPTURE is executed, it will perform the operation on the latest amount. You'll have to wait for the `AUTHORISATION_ADJUSTMENT` response, before making the capture once it's final.

# Webhooks

## Testing webhooks

Webhooks deliver asynchronous notifications and it is important to test them during the setup of your integration. You can find more information about webhooks in [this detailed blog post](https://www.adyen.com/blog/Integrating-webhooks-notifications-with-Adyen-Checkout).
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).

This sample application provides a simple webhook integration exposed at `/api/webhooks/notifications`. For it to work, you need to:
### Webhook setup

1. Provide a way for the Adyen platform to reach your running application
2. Add a Standard webhook in your Customer Area
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`.

### Making your server reachable
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/).

Your endpoint that will consume the incoming webhook must be publicly accessible.
Make sure the webhook is **enabled**, so it can receive notifications.

There are typically 3 options:
* deploy on your own cloud provider
* deploy on Gitpod
* expose your localhost with tunneling software (i.e. ngrok)

#### Option 1: cloud deployment
If you deploy on your cloud provider (or your own public server) the webhook URL will be the URL of the server
```
https://{cloud-provider}/api/webhooks/notifications
```
### Expose an endpoint

#### Option 2: Gitpod
If you use Gitpod the webhook URL will be the host assigned by Gitpod
```
https://myorg-myrepo-y8ad7pso0w5.ws-eu75.gitpod.io/api/webhooks/notifications
```
**Note:** when starting a new Gitpod workspace the host changes, make sure to **update the Webhook URL** in the Customer Area

#### Option 3: localhost via tunneling software
If you use a tunneling service like [ngrok](ngrok) the webhook URL will be the generated URL (ie `https://c991-80-113-16-28.ngrok.io`)

```bash
$ ngrok http 8080

Session Status online
Account ############
Version #########
Region United States (us)
Forwarding http://c991-80-113-16-28.ngrok.io -> http://localhost:8080
Forwarding https://c991-80-113-16-28.ngrok.io -> http://localhost:8080
```
This demo provides a simple webhook implementation exposed at `/api/webhooks/notifications` that shows you how to receive, validate and consume the webhook payload.

**Note:** when restarting ngrok a new URL is generated, make sure to **update the Webhook URL** in the Customer Area
### Test your webhook

### Set up a webhook
The following webhooks `events` should be enabled:
* **AUTHORISATION**
* **AUTHORISATION_ADJUSTMENT**
* **CAPTURE**
* **CANCEL_OR_REFUND**
* **REFUND_FAILED**
* **REFUNDED_REVERSED**

* In the Customer Area go to Developers -> Webhooks and create a new 'Standard notification' webhook.
* Enter the URL of your application/endpoint (see options [above](#making-your-server-reachable))
* Define username and password for Basic Authentication
* Generate the HMAC Key
* Optionally, in Additional Settings, add the data you want to receive. A good example is 'Payment Account Reference'.
* Make sure the webhook is **Enabled** (therefore it can receive the notifications)
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).

That's it! Every time you perform a new payment, your application will receive a notification from the Adyen platform.

## Contributing

Expand Down

0 comments on commit 2929f8e

Please sign in to comment.