> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/cloud/payments/integrations/providers/adyen.md).

# Adyen

Connect Adyen to Payments — keys, webhook URL and signing secret.

Adyen takes card and local payments for larger businesses. Norbix gets its standard webhook notifications (authorisation, capture, refund, cancellation, chargeback).

## Get your credentials

1. Sign in to the Adyen [Customer Area](https://ca-test.adyen.com/) (test) and note your **merchant account** code, for example `AcmeECOM`.
2. Open **Developers → API credentials**, choose (or create) a web service user, and generate an **API key** (see [API credentials](https://docs.adyen.com/development-resources/api-credentials)).
3. Save the integration in Cloud once (below) to get its **Webhook URL**.
4. Open **Developers → Webhooks → + Webhook → Standard webhook**, paste the webhook URL as **Server configuration → URL**, and generate an **HMAC key** (see [Webhooks](https://docs.adyen.com/development-resources/webhooks) and [Verify HMAC signatures](https://docs.adyen.com/development-resources/webhooks/secure-webhooks/verify-hmac-signatures)). Copy the HMAC key and the webhook id into Cloud, type the API key again, and **Save**.

## Connect it in Cloud

**Where:** Payments → Integrations → **Add New Integration** → Adyen → **Connect** · `/projects/<project>/payments/integrations/new/adyen`

| Field            | Required | What it does                                                                                                                                               | Example             |
| ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| Merchant Account | yes      | Your Adyen merchant account code.                                                                                                                          | `AcmeECOM`          |
| API Key          | yes      | Lets Norbix call Adyen. Secret; encrypted on save and never shown again — type it again whenever you press **Save**.                                       | `AQE…`              |
| Environment      | yes      | `test` or `live` — type the word.                                                                                                                          | `test`              |
| Webhook ID       | no       | The id of your standard webhook, for your reference.                                                                                                       | `WBHK…`             |
| Webhook HMAC Key | no       | Checks the `hmacSignature` of each notification — needed for payment triggers. It is shown as plain text while you type and is not shown again after save. | `44782DEF547AAA06…` |
| Integration Name | yes      | The name in your integrations list.                                                                                                                        | `Adyen test`        |

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-34f65c0881cf26092e02964d7d4c70922d6d34bb%2Fadyen-form-1.png?alt=media" alt="New Adyen Integration form filled with example values"><figcaption><p>The filled form (placeholder values).</p></figcaption></figure>

Press **Save**. The page turns into **Editing Adyen integration** with the badges **ENABLED**, **NOT TESTED**, **NOT CONFIRMED**, the integration id (`int_5AwX9TRQbxzK0DWHW0EiAC`) and the **Webhook URL** — `<Hub address>/v3/payments/webhooks/<account id>/<project id>/adyen/<integration id>`; outside PROD it ends with `?env=<ENV>`. Copy it with its copy button and paste it at Adyen (see **Get your credentials**). **Received webhooks** at the bottom lists every call Adyen makes to it.

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-f9ad7887fd545d40141db10f6f11a4bef739f438%2Fadyen-saved-2.png?alt=media" alt="Editing Adyen integration after Save: ENABLED, NOT TESTED, NOT CONFIRMED, the integration id and the Webhook URL"><figcaption><p>After save: the webhook URL to paste at Adyen.</p></figcaption></figure>

Events Norbix accepts from Adyen (pick them at Adyen and in your [trigger](/codemash/cloud/payments/triggers/new.md)): `AUTHORISATION`, `CAPTURE`, `REFUND`, `CANCELLATION`, `CHARGEBACK`.

## Test and set as default

**Test integration** signs in to Adyen with the API key. With the made-up key of this example it failed: *Adyen authentication failed for integration int\_5AwX9TRQbxzK0DWHW0EiAC: HTTP 401 Unauthorized*. See [Test an integration](/codemash/cloud/payments/integrations/test.md). Payments has no default integration — every enabled integration gets its own calls ([Default integration](/codemash/cloud/payments/integrations/set-default.md)).

## Common errors

| Message                                             | Cause                                                        | Fix                                                      |
| --------------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------- |
| Adyen authentication failed … HTTP 401 Unauthorized | Wrong API key, or a test key with **Environment** `live`.    | Generate the key again, type it, **Save**, test again.   |
| **Received webhooks** shows **400**                 | The HMAC key in Cloud is not the one of the webhook.         | Copy the HMAC key again and **Save**.                    |
| Required                                            | A required field is empty — secrets count too on every save. | Fill the field; type every secret again before **Save**. |

## Do it from code

```ts
const { id } = await norbix.hub.payments.savePaymentsIntegration({
  integration: {
    provider: 'Adyen',
    integrationName: 'Adyen live',
    isEnabled: true,
    merchantAccount: 'YourCompanyECOM',
    apiKey: 'AQE-your-api-key',
    environment: 'live',
    webhookHmacKey: '44782DEF547AAA06C910C43932B1EB0C71FC68D9D0C057550C48EC2ACF6BA056',
  } as any, // the TS type knows only the shared fields
});
console.log(id); // int_…
```

```sh
norbix hub payments integration save --integration '{"provider":"Adyen","integrationName":"Adyen live","isEnabled":true,"merchantAccount":"YourCompanyECOM","apiKey":"AQE-your-api-key","environment":"live","webhookHmacKey":"44782DEF547AAA06C910C43932B1EB0C71FC68D9D0C057550C48EC2ACF6BA056"}'
```

The client setup is on the [Payments page](/codemash/cloud/payments.md#use-it-from-code). API: [Save Payments Integration](/codemash/api-reference/payments/integrations/save-payments-integration.md)