# commercetools

To accept payments through MONEI in your commercetools Composable Commerce project, install the MONEI payment connector from the [Connect marketplace](https://docs.commercetools.com/connect/connectors). The connector supports Bizum, card payments, Apple Pay, Google Pay, and SEPA Direct Debit.

## Before you begin[​](#before-you-begin "Direct link to Before you begin")

To test your integration:

* Use your [test mode](https://docs.monei.com/testing/.md) API Key. You can find it in [MONEI Dashboard → Settings → API Access](https://dashboard.monei.com/settings/api).
* You can check the status of a test payment in your [MONEI Dashboard → Payments](https://dashboard.monei.com/payments) (in test mode).

You will also need:

* A [commercetools Composable Commerce](https://commercetools.com) project
* An [API Client](https://docs.commercetools.com/merchant-center/developer-settings#api-clients) with the following scopes: `manage_payments`, `manage_orders`, `view_sessions`, `view_api_clients`, `manage_checkout_payment_intents`, `introspect_oauth_tokens`, `manage_types`, `view_types`

## Install[​](#install "Direct link to Install")

1. In the [commercetools Merchant Center](https://mc.commercetools.com), go to **Connect → Marketplace**
2. Search for **MONEI**
3. Click **Install** on the MONEI Payment Connector
4. Select the **Region** where your commercetools project is hosted (e.g., `europe-west1.gcp`)

Alternatively, you can deploy the connector directly from the [GitHub repository](https://github.com/MONEI/connect-payment-integration-monei) using the commercetools [Connect CLI](https://docs.commercetools.com/connect/cli).

## Configure[​](#configure "Direct link to Configure")

After installing the connector, configure it with your MONEI credentials:

| Variable                             | Description                                                                                              | Required |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------- | -------- |
| **MONEI\_API\_KEY**                  | Your MONEI API Key from [Dashboard → Settings → API Access](https://dashboard.monei.com/settings/api)    | Yes      |
| **MONEI\_ACCOUNT\_ID**               | Your MONEI Account ID from [Dashboard → Settings → API Access](https://dashboard.monei.com/settings/api) | Yes      |
| **MONEI\_WEBHOOK\_SECRET**           | Webhook signing secret for verifying notifications                                                       | Yes      |
| **MONEI\_ENVIRONMENT**               | `test` or `live`                                                                                         | Yes      |
| **MONEI\_PAYMENT\_METHODS\_ENABLED** | Comma-separated list of payment methods to enable (e.g., `bizum,card,applePay,googlePay`)                | No       |

tip

Start with `MONEI_ENVIRONMENT=test` and switch to `live` only after you have verified your integration.

### Configure webhooks[​](#configure-webhooks "Direct link to Configure webhooks")

The connector automatically handles webhook notifications from MONEI. To set up webhooks:

1. Go to [MONEI Dashboard → Settings → Webhooks](https://dashboard.monei.com/settings/webhooks)
2. Add a new webhook endpoint with the URL provided after deploying the connector
3. Copy the generated HMAC signing key and set it as `MONEI_WEBHOOK_SECRET` in your connector configuration

## Supported payment methods[​](#supported-payment-methods "Direct link to Supported payment methods")

| Method                | Description                                                          |
| --------------------- | -------------------------------------------------------------------- |
| **Card**              | Visa, Mastercard, and other card networks via multi-acquirer routing |
| **Bizum**             | Spain's mobile payment method with 28M+ users                        |
| **Apple Pay**         | Digital wallet payments on Safari and iOS devices                    |
| **Google Pay**        | Digital wallet payments on supported browsers                        |
| **SEPA Direct Debit** | Bank direct debit payments across the SEPA zone                      |

To enable payment methods, configure them in your [MONEI Dashboard → Settings → Payment Methods](https://dashboard.monei.com/settings/payment-methods) and include them in the `MONEI_PAYMENT_METHODS_ENABLED` connector variable.

## Using with commercetools Checkout[​](#using-with-commercetools-checkout "Direct link to Using with commercetools Checkout")

The MONEI connector is fully compatible with [commercetools Checkout](https://docs.commercetools.com/checkout). Once installed:

1. Go to **Merchant Center → Checkout → Applications**
2. Add a new application or edit an existing one
3. Select the **MONEI** connector for your payment integrations
4. Choose which payment methods to display and configure their order

The connector supports both **web components** (individual payment method UI) and **drop-in** (all methods in one component) integration types.

## Before you go live[​](#before-you-go-live "Direct link to Before you go live")

* Make sure that you are using [live (production) mode](https://docs.monei.com/testing/.md) API Key
* Make sure that you have at least one active [payment method](https://dashboard.monei.com/settings/payment-methods)
* Update the `MONEI_ENVIRONMENT` connector variable to `live`
* Verify that webhooks are correctly configured and receiving notifications
* Test the full payment flow including capture, refund, and cancellation