adyen-test-mode

Overview

Adyen's test environment is fully API-compatible with prod. Per docs.adyen.com/development-resources/testing (opens in new window), test API keys + test merchant accounts produce deterministic results based on input.

The notable difference from Stripe: Adyen separates the synchronous payment API from the asynchronous notification webhook more explicitly. Both surfaces need tests.

When to use

• Tests for code using Adyen's Payments / Checkout / Recurring API.
• Webhook handling tests.
• 3DS flow tests per 3ds-test-flow-reference.

Authoring

Install

npm install @adyen/api-library
pip install Adyen

Initialize

import { Client, CheckoutAPI } from '@adyen/api-library';

const client = new Client({
  apiKey: process.env.ADYEN_TEST_API_KEY!,
  environment: 'TEST',                  // vs 'LIVE'
});
const checkout = new CheckoutAPI(client);

Test cards

Per docs.adyen.com/development-resources/test-cards-and-credentials/test-card-numbers (opens in new window):

Test expiry: any future date. Test CVC: 737 (special "3DS") or any 3-digit.

Payment

const paymentResponse = await checkout.payments({
  amount: { currency: 'EUR', value: 1000 },
  paymentMethod: {
    type: 'scheme',
    encryptedCardNumber: 'test_4111111111111111',
    encryptedExpiryMonth: 'test_03',
    encryptedExpiryYear: 'test_2030',
    encryptedSecurityCode: 'test_737',
  },
  reference: 'order-' + uuidv4(),
  merchantAccount: process.env.ADYEN_MERCHANT_ACCOUNT!,
});

expect(paymentResponse.resultCode).toBe('Authorised');

Result codes per docs.adyen.com/online-payments/build-your-integration/payment-result-codes (opens in new window):

Webhook (notification) handling

Adyen sends webhooks ("notifications") for every state change. Per docs.adyen.com/development-resources/webhooks/secure-webhooks/verify-hmac-signatures (opens in new window): validate via HMAC-SHA256 over a canonical-string of the payload.

import { hmacValidator } from '@adyen/api-library';
const validator = new hmacValidator();

test('webhook signature valid', () => {
  const notification = { /* notification payload */ };
  const hmacSignature = notification.additionalData.hmacSignature;
  const isValid = validator.validateHMAC(notification, process.env.ADYEN_HMAC_KEY!);
  expect(isValid).toBe(true);
});

Notification idempotency

Adyen redelivers notifications until acknowledged with HTTP 200

• [accepted] body. Tests should verify the handler is idempotent under redelivery:

test('redelivered notification handled idempotently', async () => {
  const notif = makeTestNotification();
  await handler(notif);
  const before = await db.payments.count();
  await handler(notif);  // re-delivered
  const after = await db.payments.count();
  expect(after).toBe(before);
});

Notifications test mode

Per Adyen docs: in Customer Area, you can re-send notifications on demand for testing. Also exposes a webhook-events endpoint for replay.

Running

npm test

CI integration

jobs:
  adyen-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v4
      - run: npm ci && npm test
        env:
          ADYEN_TEST_API_KEY: ${{ secrets.ADYEN_TEST_API_KEY }}
          ADYEN_MERCHANT_ACCOUNT: ${{ secrets.ADYEN_TEST_MERCHANT_ACCOUNT }}
          ADYEN_HMAC_KEY: ${{ secrets.ADYEN_TEST_HMAC_KEY }}

Anti-patterns

Limitations

• Adyen test mode uses encrypted data placeholders. Real encryption uses Adyen Web SDK; tests use test_* placeholders.
• Notification SLA varies. Real-time webhooks but retried-on-failure can be hours later.
• Recurring API has separate test cards. Tokenisation scenarios need their own surface.
• Region-specific payment methods. iDEAL / Sofort / etc. have separate test flows.

References

• Adyen testing: docs.adyen.com/development-resources/testing (opens in new window).
• Test card numbers: docs.adyen.com/development-resources/test-cards-and-credentials/test-card-numbers (opens in new window).
• Result codes: docs.adyen.com/online-payments/build-your-integration/payment-result-codes (opens in new window).
• Webhook HMAC verification: docs.adyen.com/development-resources/webhooks/secure-webhooks/verify-hmac-signatures (opens in new window).
• Companion catalogs: payment-flow-states-reference, 3ds-test-flow-reference, pci-dss-scope-reference.
• Sibling SDKs: stripe-test-cards-and-webhooks, paypal-sandbox, braintree-test-cards.