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.

Adyen capture and auto-capture in Norce Checkout

The Adyen Checkout Adapter does not capture payments and has no capture setting. The adapter does not send captureDelayHours or manualCapture in the Adyen payment request, so the capture setting on the Adyen merchant account decides when Adyen captures a payment. Configure the capture setting (immediate automatic capture, delayed automatic capture, or manual capture) in the Adyen Customer Area.

The Adyen Checkout Adapter sets the Norce Checkout payment to reserved when the payment is authorized. The Adyen Checkout Adapter sets the payment to captured only when Adyen sends a CAPTURE webhook. Adyen sends the CAPTURE webhook in the following cases:

• Manual capture in the Adyen Customer Area or via Adyen's API: Adyen sends the CAPTURE webhook, and the Norce Checkout payment is updated to captured.
• Delayed automatic capture (a capture delay set in the Adyen Customer Area): Adyen sends the CAPTURE webhook only if the CAPTURE event code is enabled on the Adyen webhook. Then the Norce Checkout payment is updated to captured.
• Immediate automatic capture (the Adyen default): Adyen does not send a CAPTURE webhook. Adyen captures the funds, but the Norce Checkout payment stays reserved.

For more information, see Adyen's documentation on capture and webhook types.

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:

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

Adyen does not send CAPTURE webhooks for immediate automatic capture, which is the Adyen default. With immediate automatic capture, the Norce Checkout payment stays reserved after Adyen has captured the funds. To have Norce Checkout set the payment to captured, use delayed automatic capture or manual capture in Adyen, and enable the CAPTURE event code on the Adyen webhook.

The Adyen Checkout Adapter does not check the success field of a CAPTURE webhook. The adapter sets the Norce Checkout payment to captured for every CAPTURE webhook it receives, including a CAPTURE webhook with success set to false, which Adyen sends when a capture fails. A Norce Checkout payment in the captured state is therefore not proof that Adyen captured the funds. To confirm that a capture succeeded, check the payment in the Adyen Customer Area.

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.

Links and References

• Adyen Checkout Adapter OpenAPI Specification
• Adyen Checkout Adapter (Business Overview)
• Adyen Checkout Documentation (External)
• Adyen Drop-in Integration Guide (External)