Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Revise readme - checkout example #171

Merged
merged 13 commits into from
Sep 29, 2023
Merged

Revise readme - checkout example #171

Changes from 5 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
353ff34
Simplify intro and description
gcatanese Sep 4, 2023
a490851
Update README.md
gcatanese Sep 4, 2023
1b0849f
Update README.md
gcatanese Sep 4, 2023
2bd0319
Add webhooks testing
gcatanese Sep 5, 2023
c22c091
Update README.md
gcatanese Sep 5, 2023
7801d48
Revise readme.md with suggestions
Kwok-he-Chu Sep 14, 2023
27a307d
Add checkout-example-advanced
Kwok-he-Chu Sep 14, 2023
5c0d3ac
Update readme
Kwok-he-Chu Sep 14, 2023
61da199
Minor corrections
gcatanese Sep 18, 2023
b85c3fe
Remove contributing (already in the root README)
gcatanese Sep 18, 2023
93d1c5b
Shorten text
gcatanese Sep 18, 2023
e2a30b0
Align with Checkout example README
gcatanese Sep 18, 2023
005f817
Bold text
gcatanese Sep 18, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
177 changes: 45 additions & 132 deletions checkout-example/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,44 +1,23 @@
# Adyen [online payment](https://docs.adyen.com/online-payments) integration demo - Sessions Flow

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

* 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!

[![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/checkout-example)

_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)_
[![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/checkout-example)
 [First time with Gitpod?](https://github.com/adyen-examples/.github/blob/main/pages/gitpod-get-started.md)

## Details

This repository showcases a PCI-compliant integration of the **Session Flow**, the default integration that we recommend for merchants. Explore this simplified e-commerce demo to discover the code, libraries and configuration you need to enable various payment options in your checkout experience.

**If you want to integrate a more complex flow, see [here](https://docs.adyen.com/online-payments/web-drop-in/additional-use-cases?tab=sessions_flow_advanced_flow_1) for more information and have a look at the `../checkout-example-advanced` folder**

It includes a **Java + Spring Boot + Thymeleaf** application that supports [Adyen Drop-in and Components](https://docs.adyen.com/online-payments/build-your-integration)
(ACH, Alipay, Cards, Dotpay, iDEAL, Klarna, PayPal, etc..) using the Adyen's API Library for Java ([GitHub](https://github.com/Adyen/adyen-java-api-library)).

This repository includes examples of PCI-compliant UI integrations for online payments with Adyen. Within this demo app, you'll find a simplified version of an e-commerce website, complete with commented code to highlight key features and concepts of Adyen's API. Check out the underlying code to see how you can integrate Adyen to give your shoppers the option to pay with their preferred payment methods, all in a seamless checkout experience.
<br/>

> **Note**
For more [advanced use cases](https://docs.adyen.com/online-payments/build-your-integration/additional-use-cases/) check out the **Advanced Flow** demo in the `../checkout-example-advanced` folder.
>

![Card checkout demo](src/main/resources/static/images/cardcheckout.gif)

## Supported Integrations


[Online payments](https://docs.adyen.com/online-payments) **Java + Spring Boot + Thymeleaf** demos of the following client-side integrations are currently available in this repository:

- Drop-in
- Components
- ACH
- Alipay
- Card (3DS2)
- Dotpay
- giropay
- iDEAL
- Klarna (Pay now, Pay later, Slice it)
- SOFORT
- PayPal

The 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)).

## Requirements

Expand All @@ -55,23 +34,23 @@ git clone https://github.com/adyen-examples/adyen-java-spring-online-payments.gi

## Usage

1. Set environment variables for the 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)
### Set the environment variables
Set environment variables for the 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)

Remember to include `http://localhost:8080` in the list of Allowed Origins

On Linux/Mac export env variables
On Linux/Mac export the env variables
```shell
export ADYEN_API_KEY=yourAdyenApiKey
export ADYEN_MERCHANT_ACCOUNT=yourAdyenMerchantAccount
export ADYEN_CLIENT_KEY=yourAdyenClientKey
export ADYEN_HMAC_KEY=yourHmacKey
```

On Windows CMD you can use below commands instead
On Windows CMD you can set the env variables
```shell
set ADYEN_API_KEY=yourAdyenApiKey
set ADYEN_MERCHANT_ACCOUNT=yourAdyenMerchantAccount
Expand All @@ -86,120 +65,54 @@ ADYEN_MERCHANT_ACCOUNT=yourAdyenMerchantAccount
ADYEN_CLIENT_KEY=yourAdyenClientKey
ADYEN_HMAC_KEY=yourHmacKey
```
2. Start the server:

```
./gradlew bootRun
```

3. Visit [http://localhost:8080/](http://localhost:8080/) to select an integration type.

To try out integrations with test card numbers and payment method details, see [Test card numbers](https://docs.adyen.com/development-resources/test-cards/test-card-numbers).

## 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).

This sample application provides a simple webhook integration exposed at `/api/webhooks/notifications`. For it to work, you need to:
### Configure allowed origins (CORS)

1. Provide a way for the Adyen platform to reach your running application
2. Add a Standard webhook in your Customer Area
It is required to specify the domain or URL of the web applications that will make requests to Adyen.

### Making your server reachable
In the Customer Area add `http://localhost:8080` in the list of Allowed Origins associated to the Client Key (API credential).

Your endpoint that will consume the incoming webhook must be publicly accessible.
### Run the demo

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

#### 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
```

#### 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
cd checkout-example

./gradlew bootRun
```

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

### Set up a webhook

* 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)

That's it! Every time you perform a new payment, your application will receive a notification from the Adyen platform.
Visit [http://localhost:8080/](http://localhost:8080/) to choose an integration type.

## Deploying this example to the cloud
Try out the different payment methods with our [Test card numbers](https://docs.adyen.com/development-resources/test-cards/test-card-numbers) and other payment method details.

As part of this example, we are providing a [Terraform](https://www.terraform.io/) configuration file that can be used to deploy this demo to the Amazon cloud on a [Beanstalk](https://aws.amazon.com/elasticbeanstalk/) environment.
## Webhooks

⚠️ This part will deploy (AWS) cloud resources and can incur charges ⚠️.
Webhooks deliver asynchronous notifications obout payment status (like authorisation) 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 requires the following webhook(s):
* **Standard webhook** to receive the final payment authorisation

### Extra prerequisites
Read below how to setup, consume and test the webhook(s).

* The [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html), with a configured profile (and an AWS account).
* The [Terraform](https://www.terraform.io/) CLI, with the `terraform` executable in your PATH.
* Ready to use Adyen API and client keys.
### Setup a webhook

### Usage
In the Customer Area in the "Developers" section [create](https://docs.adyen.com/development-resources/webhooks/#set-up-webhooks-in-your-customer-area) a new Standard webhook

* Compile the project: `./gradlew build`
* Create a `terraform.tfvars` file in the root directory of this repository. Here is a example :

```
adyen_api_key = "testApiKey"
adyen_merchant_account = "testMerchantAccount"
adyen_client_key = "testClientKey"
adyen_hmac_key = "testHMACKey"
```

* Run the `terraform init` command to initialize the Terraform configuration, and `terraform apply` to deploy the environment.
* At the end of the deployment, Terraform will output several URLs :

```
adyen_url = "https://ca-test.adyen.com/ca/ca/config/showthirdparty.shtml"
demo_url = "http://adyen-spring-development-cc66dd5f.eu-west-1.elasticbeanstalk.com"
environment_url = "https://eu-west-1.console.aws.amazon.com/elasticbeanstalk/home?region=eu-west-1#/applications"
```
Copy the generated HMAC Key and set it as an environment variable (as explained above).

* You can access the demo using the `demo_url`.
* The `adyen_url` can be used to create a [notification webhook](https://docs.adyen.com/development-resources/webhooks) in the Adyen customer area.
* Use `terraform destroy` to remove the environment and avoid being charged for the resources more than necessary.
* The `environment_url` can be used to access the AWS Beanstalk environment and possibly update the configuration.
Make sure the webhook is **enabled** (therefore it can receive the notifications).

## Contributing
### Expose an endpoint

We commit all our new features directly into our GitHub repository. Feel free to request or suggest new features or code changes yourself as well!
The demo provides a simple webhook implementation exposed at `/api/webhooks/notifications` that will show you how to
receive, validate and consume the webhook payload.

Find out more in our [Contributing](https://github.com/adyen-examples/.github/blob/main/CONTRIBUTING.md) guidelines.
### Test your webhook

## License
Testing webhooks is not trivial: the application runs on your `localhost` or on a different server/cloud, and the Adyen
platform must be able to reach it.

MIT license. For more information, see the **LICENSE** file in the root directory.
Check out our [Webhooks Testing guide](https://github.com/adyen-examples/.github/blob/main/pages/webhooks-testing.md).