readme.md

Adyen In-person Payment Demo Integration Demo

Run demo in one-click

First time with Gitpod?

Description

This demo shows developers how to use the Adyen Cloud Terminal API /terminal-api/sync to make requests to your connected terminal.

The following implementations are included:

• Payment requests
• Referenced refund requests
• Cancel/abort requests
• Transaction status requests

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.

This demo leverages Adyen's API Library for .NET (GitHub | Docs). You can find the Terminal API documentation here.

Requirements

• A terminal device and a test card from Adyen
• An Adyen account, learn how an Adyen account is structured in our documentation
• .NET Core SDK 6.0+

1. Installation

git clone https://github.com/adyen-examples/adyen-dotnet-online-payments.git

2. Set the environment variables

• Adyen API Key
• Adyen HMAC Key
• 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.

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 appsettings.Development.json.

{
  "ADYEN_API_KEY": "yourAdyenApiKey",
  "ADYEN_HMAC_KEY": "yourHmacKey",
  "ADYEN_POS_POI_ID": "v400m-123456789"
}

3. Run the application

dotnet run --project in-person-payments-example 

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 take a while to receive).

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.

Webhook setup

In the Customer Area under the Developers → Webhooks section, create 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.

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_REVERSED

To make sure that the Adyen platform can reach your application, we have written a Webhooks Testing Guide that explores several options on how you can easily achieve this (e.g. running on localhost or cloud).

Flowchart