# commercetools

Accept payments with Finix on [commercetools](https://commercetools.com).

commercetools
## commercetools Overview

commercetools is a headless, cloud-native commerce platform built on MACH principles (Microservices, API-first, Cloud-native, Headless). It enables global enterprises to build composable commerce experiences by providing modular services for product catalogs, cart and checkout, order management, and customer data — all exposed via APIs. Finix integrates with commercetools through the Cybersource payment gateway, enabling merchants to process payments and reconcile transaction data within their commercetools storefront.

### Finix Requirements

- Finix Live Account
- Active commercetools account


## Integration

### Step 1: Sign up for a Finix Account

To create a Finix account, you can follow our step-by-step [guide](/guides/getting-started/finix-sign-up) or [sign up](https://finix.payments-dashboard.com) directly for a live or sandbox account.

We recommend choosing Direct Merchant as your Customer Type.

### Step 2: Create a Cybersource Gateway Integration

Cybersource Integration
Finix supports commercetools via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration.

For more information, please reach out to your Finix point of contact.

1. To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard.


Cybersource Merchant Integrations
1. Sign up for Cybersource. You can view detailed instructions in our guide, [here](/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard).
2. After accepting the Cybersource invitation email, retrieve the following credentials from the Cybersource Business Center under **Payment Configuration → Key Management** — you'll need these to configure commercetools:
  - **Merchant ID** (also called Organization ID)
  - **REST API Key**


Cybersource Key Management
### Step 3: Set Up Your commercetools Environment

Before proceeding, ensure your commercetools environment is ready:

- Active commercetools [Merchant Center account](https://identity.commercetools.com/login?returnTo=https%3A%2F%2Fmc-api.europe-west1.gcp.commercetools.com%2Fcallbacks%2Flogin%3FreturnTo%3Dhttps%253A%252F%252Fmc.europe-west1.gcp.commercetools.com%252Flogin%252Fchoose) with a configured project
- API Client with **Manage** and **View** scopes for: Customers, Extensions, Orders, Payments, and Types
- Node.js v16.3.0 or later
- 256MB minimum memory allocation for the plugin service


### Step 4: Install and Configure the Cybersource Plugin

Before you proceed, ensure you have:

- Approved Finix Merchant Account
- Cybersource Gateway Integration linked to your Finix Merchant Account
- commercetools project with API Client configured


Install the `cybersource-plugins-commercetools` package from the Cybersource GitHub repository. For full installation details, refer to the [Cybersource commercetools developer documentation](https://developer.cybersource.com/technology-partners/commercetools.html).

Once installed, populate the following environment variables in your `.env` file:

**Cybersource credentials:**

- `PAYMENT_GATEWAY_MERCHANT_ID` — your Cybersource Merchant ID from Step 2
- `PAYMENT_GATEWAY_MERCHANT_KEY_ID` — your REST API Key ID from Step 2
- `PAYMENT_GATEWAY_MERCHANT_SECRET_KEY` — your REST API Shared Secret from Step 2
- `PAYMENT_GATEWAY_RUN_ENVIRONMENT` — set to `TEST` for sandbox or `PRODUCTION` for live
- `PAYMENT_GATEWAY_TARGET_ORIGIN` — your frontend base URL


**commercetools credentials:**

- `CT_PROJECT_KEY`, `CT_CLIENT_ID`, `CT_CLIENT_SECRET` — from your commercetools API Client
- `CT_AUTH_HOST`, `CT_API_HOST` — your commercetools server URLs


**Optional feature flags:**

- `PAYMENT_GATEWAY_DECISION_MANAGER` — enable Cybersource Decision Manager for fraud prevention
- `PAYMENT_GATEWAY_SCA_CHALLENGE` — enforce 3D Secure for SCA-compliant transactions
- `PAYMENT_GATEWAY_3DS_RETURN_URL` — redirect URL for 3D Secure authentication flow
- `PAYMENT_GATEWAY_ENABLE_RATE_LIMITER` — restrict saved card usage


### Step 5: Deploy and Activate the Plugin

Once your environment variables are configured, start the plugin service:


```bash
npm run start
```

Then call the `/configurePlugin` endpoint to register the API extensions within your commercetools project. This establishes the payment extension hooks that route transactions through Cybersource.

After completing configuration, you can now take payments through Finix via our Cybersource Gateway Integration.

To learn more about our Cybersource Gateway Integration, you can read our [guide](/guides/online-payments/gateway-integration/cybersource).

If you need additional assistance contact [support@finix.com](mailto:support@finix.com).

## commercetools Transactions

When you run a transaction on commercetools, you'll see it:

- In your commercetools Merchant Center under **Orders**.
- In the Cybersource Business Center.
- In your Finix Dashboard under **Transactions** → **Payments**.


These transactions will be ingested by Finix and added to `Settlements`. To track transfers between Finix and Cybersource, please refer to our guide, [here](/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions).