Skip to content

TailoredApps.Shared.Payments.Provider.Adyen

NuGet License: MIT

Integration with the Adyen Checkout API. Supports card payments, BLIK (PLN) and other methods available in Adyen, with full webhook handling and HMAC verification.


Installation

dotnet add package TailoredApps.Shared.Payments.Provider.Adyen

DI registration

using TailoredApps.Shared.Payments.Provider.Adyen;

builder.Services
    .AddPayments()
    .RegisterAdyenProvider();

Configuration appsettings.json

{
  "Payments": {
    "Providers": {
      "Adyen": {
        "ApiKey": "AQEyhmf...",
        "MerchantAccount": "MyCompanyECOM",
        "ClientKey": "test_...",
        "ReturnUrl": "https://myapp.com/payment/return",
        "NotificationHmacKey": "446a32...hex...",
        "Environment": "test"
      }
    }
  }
}
Option Required Description
ApiKey yes Adyen API key (X-API-Key header)
MerchantAccount yes Merchant account identifier
NotificationHmacKey yes HMAC key (hex) for webhook verification
ReturnUrl no Return URL after payment
Environment no "test" (default) calls https://checkout-test.adyen.com/v71; any other value, for example "live", calls https://checkout-live.adyen.com/v71
CheckoutUrl no Full base URL of the Checkout API; when set it replaces the address derived from Environment
ClientKey no Drop-in/Components client key - bound from configuration, but not used by the provider

Required options are checked when the host starts (OptionsValidationException); the others are not validated.


Supported payment channels

The list is fixed in the provider:

Currency Channels
PLN scheme (payment card: Visa, Mastercard), blik, onlineBanking_PL (online transfer)
EUR scheme, ideal, sepadirectdebit
Other scheme

Payment and reading the outcome

The provider creates a Hosted Checkout session (POST /sessions with mode: hosted): RegisterPayment returns the session id in PaymentUniqueId and the address of Adyen's payment page in RedirectUrl.

// 1. create the payment and send the shopper to the Adyen page
var response = await _payments.RegisterPayment(new PaymentRequest("Adyen", 49.99m, "PLN")
{
    AdditionalData = orderNumber,   // comes back as merchantReference in the webhook
}, cancellationToken);
await _orders.SavePaymentSessionAsync(orderNumber, response.PaymentUniqueId, cancellationToken);
return Redirect(response.RedirectUrl);

// 2. the shopper returns to ReturnUrl; Adyen appends sessionId and sessionResult to the address
[HttpGet("payment/return")]
public async Task<IActionResult> Return(string sessionId, string sessionResult, CancellationToken cancellationToken)
{
    var payment = await _payments.GetStatus("Adyen", AdyenProvider.SessionResultId(sessionId, sessionResult), cancellationToken);
    return payment.PaymentStatus == PaymentStatusEnum.Finished ? View("Paid") : View("Pending");
}
Adyen session status PaymentStatus
completed Finished
paymentPending Processing
refused, canceled, expired Rejected
active (the shopper has not paid yet) Created
  • Adyen reports the outcome of a session only together with the sessionResult value it appends to the return address. GetStatus with a bare session id fails with ArgumentException - apart from the shopper's return, the webhook is the only source of the outcome.
  • The outcome read on return is for showing a thank-you page; settle the order on the webhook.
  • What was verified: the request and the response follow the Checkout OpenAPI v71 specification (the mode and url fields, GET /sessions/{sessionId}?sessionResult=); the names of the parameters appended to the return address come from the Hosted Checkout documentation and - like the whole provider - have not been exercised in the Adyen test environment.

Webhook

A standard Adyen webhook is JSON with a notificationItems array; each NotificationRequestItem carries its own signature in additionalData.hmacSignature - there is no signature header. The signature is HMAC-SHA256 (key: NotificationHmacKey decoded from hex, output in Base64) over eight fields of the item joined with a colon; an absent field is an empty string:

pspReference:originalReference:merchantAccountCode:merchantReference:amount.value:amount.currency:eventCode:success

In the Adyen Customer Area (Developers → Webhooks) enable HMAC signing for the webhook and copy the generated key into NotificationHmacKey.

[HttpPost("webhooks/adyen")]
public async Task<IActionResult> AdyenWebhook(CancellationToken cancellationToken)
{
    using var reader = new StreamReader(Request.Body, Encoding.UTF8);
    var body = await reader.ReadToEndAsync(cancellationToken);

    var result = await _payments.HandleWebhookAsync("Adyen", new PaymentWebhookRequest
    {
        Body = body,
        ContentType = Request.ContentType,
        Headers = Request.Headers.ToDictionary(h => h.Key, h => h.Value),
    }, cancellationToken);

    // Adyen repeats the notification until it gets a 2xx response.
    return result is PaymentWebhookRejected ? Unauthorized() : Content(AdyenProvider.Acknowledgement, "text/plain");
}
eventCode success Result
AUTHORISATION, REFUND true PaymentWebhookProcessed, status Finished
AUTHORISATION, REFUND anything else / absent PaymentWebhookProcessed, status Rejected
CANCELLATION, AUTHORISATION_FAILED any PaymentWebhookProcessed, status Rejected
another event any PaymentWebhookIgnored (status Processing) - still acknowledge it

🔒 Security

  • Verification fails closed: an empty or non-hex NotificationHmacKey, a missing additionalData.hmacSignature or a signature that does not match → PaymentWebhookRejection.InvalidSignature; a body that is not JSON or has no NotificationRequestItem → MalformedPayload. Constant-time comparison.
  • The signature covers eight fields, not the whole body: the other fields of the item (for example paymentMethod, reason) are not authenticated - do not base decisions on them.
  • A missing success field is treated as failure.
  • The webhook result carries PaymentUniqueId (merchantReference, falling back to pspReference) and ResponseObject = [accepted].
  • The first item of notificationItems is handled (Adyen sends one item per request).
  • What was verified: the implementation reproduces the example in Adyen's documentation (the key, the signed text and the expected signature are in the tests); send a test notification from the Adyen Customer Area before going live.

🤖 AI Agent Prompt

## Adyen Provider - instructions for an AI agent

Provider key: "Adyen"

Configuration section: "Payments:Providers:Adyen"

Required fields: ApiKey, MerchantAccount, NotificationHmacKey

Webhook: HMAC-SHA256 over eight fields of the item (pspReference:originalReference:merchantAccountCode:merchantReference:amount.value:amount.currency:eventCode:success), key NotificationHmacKey (hex), signature in additionalData.hmacSignature

Registration: builder.Services.AddPayments().RegisterAdyenProvider();

Test environment: Environment = "test" (checkout-test.adyen.com)

Rules:
- RegisterPayment returns RedirectUrl (the Hosted Checkout page) and PaymentUniqueId (the session id)
- Status after the shopper returns: GetStatus("Adyen", AdyenProvider.SessionResultId(sessionId, sessionResult)) - both parameters are in the return address; the session id alone is not enough
- Pass the raw JSON body in PaymentWebhookRequest.Body; the signature is in additionalData.hmacSignature, not in a header
- Answer HTTP 200 with the body "[accepted]" (AdyenProvider.Acknowledgement), for ignored events too
- Base decisions on the signed fields (references, amount, eventCode, success)
- Do not replace VerifyNotificationHmac with a stub returning true