Adyen Checkout Adapter

Overview Document: Payment Adapters Overview

Overview and Unique Capabilities

The Adyen Checkout Adapter integrates Adyen's payment platform with Norce Checkout using Adyen's Advanced Flow with the Drop-in component. This page focuses on the unique technical details and configuration for Adyen.

Supported payment methods and other features: Features Overview

Limitations

Only Drop-in component is supported (individual payment components are not supported).
Refund operations are handled through Adyen's Customer Area, not directly through this adapter.
Partial capture is not supported through this adapter. If partial capture is required, perform it directly in Adyen's Customer Area or via Adyen's API.

Configuration in Norce Admin

The adapter is configured using the following unique details obtained from Adyen:

Field	Description	Example Value
`ApiUrl`	Adyen Checkout API URL (test or production).	`https://checkout-test.adyen.com`
`AdyenApiKey`	Your Adyen API key from the Customer Area.	`AQEyhmfxK...`
`AdyenClientKey`	Your Adyen Client key for frontend integration.	`test_XXXX...`
`MerchantAccount`	Your Adyen merchant account name.	`YourMerchantAccount`
`IsLiveEnvironment`	Set to `true` for production, `false` for test.	`false`

Optional Configuration

Field	Description
`WebhookHmacKey`	HMAC key for webhook signature verification.
`UseRecurringPayment`	Enable recurring payment token generation.
`ReturnUrl`	URL to redirect after payment completion.
`PaymentMethodsConfiguration`	Custom configuration object for Adyen payment methods.

Adyen API Environments

In addition to the generic Norce Adapter URLs (see Payment Adapters Overview), Adyen uses the following external API environments:

Environment	Adyen API Base URL
Production	`https://checkout-live.adyen.com` (or your live endpoint)
Test	`https://checkout-test.adyen.com`

Creating a Recurring Payment

To complete an order using a previously stored recurring token:

    POST /api/checkout/v1/orders/{order_id}/payments/recurring/subscription/complete
    Host: {slug}.api-se.stage.norce.tech
    x-merchant: {merchant}
    x-channel: {channel}
    Authorization: Bearer {token}
    Content-Type: application/json

    {
      "recurringPaymentToken": "J65XNM8BMWHGQER6",
      "recurringShopperReference": "shopper@example.com"
    }

Subscription Use Only

This endpoint is designed for subscription payments (recurring transactions at regular intervals). One-off payments, automatic top-ups, and non-fixed schedule contracts are not supported through this endpoint.

Webhook Requirement

To use recurring payments, you must enable the RECURRING_CONTRACT webhook in your Adyen account settings. Without this webhook, recurring tokens will not be stored.

Webhook Configuration

Configure webhooks in Adyen Customer Area to receive payment status updates:

Navigate to Developers > Webhooks in the Adyen Customer Area
Create a new Standard webhook
Set the URL to: https://{slug}.api-se.{env}.norce.tech/checkout/adyen-adapter/api/checkout/v1/callback/orders/webhook?merchant={merchant}&channel={channel}
Enable HMAC signature verification
Enable event types: AUTHORISATION, CAPTURE, RECURRING_CONTRACT

Troubleshooting (Adyen Specific)

In addition to the generic troubleshooting steps:

Review the order status directly in Adyen's Customer Area.
If payment fails, verify API credentials are valid and have required permissions.
For webhook issues, check that the WebhookHmacKey matches the HMAC key in Adyen.
Ensure the correct environment (test/live) is configured in both Norce and Adyen.