Setting up Adyen examples with GitHub Codespaces

September 28, 2025 · View on GitHub

This guide will walk you through the steps to run any Adyen examples in a GitHub Codespaces environment.

Step 0: Choose Your Codespaces Setup

You have two options for setting up Codespaces with this repository:

Option 1: Fork the Repository (Recommended for Personal Use)

Forking the repository allows you to manage your own Codespaces environment and secrets securely within your personal GitHub account.

Navigate to the Adyen example repository you want to use (e.g., adyen-node-online-payments, adyen-java-spring-online-payments, etc.).
Click the "Fork" button in the top-right corner.
Choose where you want to fork the repository (usually your personal account).

Once forked, you will be working from your own copy of the repository.

Option 2: Use the Original Repository Directly (Secrets Configured in Your Account)

You can launch Codespaces directly from the original public repository without forking. In this case, you will configure the necessary Codespaces secrets within your own GitHub account, scoped to this repository.

Important: Ensure that the necessary Adyen secrets are configured in your personal GitHub account's Codespaces secrets, with the repository path (e.g. adyen-examples/adyen-node-online-payments) as the scope.

Step 1: Adyen Account Setup

Before launching the Codespace, you need to configure a few things in your Adyen Customer Area.

API Credentials:
- If you don't have one, create a set of API credentials for your test environment.
- You will need the following values:
  - API Key
  - Client Key
  - Merchant Account
Allowed Origins:
- To allow the Adyen UI components to load in the Codespace, you need to add the Codespace URL to your list of allowed origins.
- Navigate to your API credentials, and in the Client settings, add the following URL to the Allowed origins list:
```
https://*.github.dev
```
Webhook HMAC Key:
- In your Customer Area, go to Developers > Webhooks.
- Create a new Standard webhook.
- Generate an HMAC Key. You will need this for the next step.

Step 2: Configure GitHub Codespaces Secrets

To securely use your Adyen credentials in the Codespace, you should set them as repository secrets. The dev container is configured to automatically pick them up.

Depending on your chosen setup in Step 0:
- If you forked the repository: Navigate to your forked repository on GitHub and go to Settings > Secrets and variables > Codespaces.
- If you are using the original repository directly: Navigate to your personal GitHub account settings and go to Settings > Codespaces > Secrets. Create the secrets there, ensuring you set the Repository access to "Selected repositories" and add the specific Adyen example repository (e.g., adyen-examples/adyen-node-online-payments) as a selected repository.
Create the following secrets:
- ADYEN_API_KEY: Your Adyen API Key.
- ADYEN_CLIENT_KEY: Your Adyen Client Key.
- ADYEN_MERCHANT_ACCOUNT: Your Adyen Merchant Account.
- ADYEN_HMAC_KEY: The HMAC key you generated during webhook setup.

Step 3: Launching the Codespace

Navigate to the README.md file of the example you want to run (e.g., checkout-example/README.md).
Click the Open in GitHub Codespaces badge.
This will create and launch a new Codespace. The project will be built automatically, and the application will start.
The application will typically run on port 8080 (or as configured in the specific example's devcontainer)
Use the Drop-in and try out payments on TEST

Step 4: Configure the Webhook URL

Once the Codespace is running, you need to update your Adyen webhook with the public URL of the running application.

In the Codespace, a terminal will open, and the application will be running on the configured port (typically 8080).
Go to the Ports tab in the VS Code interface within your Codespace.
Find the entry for the application port and copy the Forwarded Address (it will look something like https://my-codespace-name-8080.preview.app.github.dev).
Go back to your Adyen Customer Area and navigate to Developers > Webhooks.
Select the webhook you created earlier and paste the copied URL into the Server configuration URL field, appending the webhook endpoint:
```
<your_forwarded_address>/api/webhooks/notifications
```
For example:
```
https://my-codespace-name-8080.preview.app.github.dev/api/webhooks/notifications
```
Ensure the webhook is enabled and save your changes.
Make sure to change visibility of your port to public to make the Webhook endpoint reachable by Adyen

You are now ready to test the integration within GitHub Codespaces!

Available Examples

Adyen provides example projects in multiple programming languages, each with similar functionality:

Programming Languages Supported

Node.js - adyen-node-online-payments
Java Spring - adyen-java-spring-online-payments
Python - adyen-python-online-payments
.NET - adyen-dotnet-online-payments
PHP - adyen-php-online-payments

Common Example Types

Most Adyen example repositories include these payment integration examples:

Checkout Example - Basic e-commerce checkout flow with different payment methods
Advanced Checkout Example - Advanced 3-step checkout flow using the Checkout API
3DS2 Example - 3D Secure 2 authentication with Native and Redirect flows
Authorisation Adjustment Example - Payment adjustments, captures, and reversals
In-person Payments Example - POS terminal payments using the Terminal API
Gift Card Example - Gift card payments with partial orders
Pay by Link Example - Pay by link flow for creating payment links
Subscription Example - Subscription payments using Adyen tokenization
Giving Example - Donation flow using Adyen Giving

Note: The specific examples available may vary by programming language. Check the individual repository's README for the complete list of examples.

Usage Tips

Updating Secrets: After updating a secret, it's best to delete the existing Codespace and create a new one to ensure the changes are applied.
Port Forwarding: Make sure the application port (typically 8080) has its visibility set to Public in the Ports tab.
Testing Webhooks: Use the Webhook Test Configuration option from your Customer Area to send test events directly to your Codespace.
Viewing Logs: Monitor the application logs in the Terminal panel for debugging and status updates.
Managing Codespaces: You can view and manage all your Codespaces at github.com/codespaces.