{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["img","admonition"]},"type":"markdown"},"seo":{"title":"commercetools Integration","description":"Integrate Finix with commercetools to accept card transactions via our Cybersource Gateway integration.","siteUrl":"https://docs.finix.com/","llmstxt":{"hide":false,"sections":[{"title":"Getting Started","includeFiles":["guides/getting-started/**/*.md"],"excludeFiles":[]},{"title":"Online Payments","includeFiles":["guides/online-payments/**/*.md"],"excludeFiles":["guides/online-payments/payment-features/fsa-hsa-non-healthcare-mcc.md"]},{"title":"In-Person Payments","includeFiles":["guides/in-person-payments/**/*.md"],"excludeFiles":[]},{"title":"Subscriptions","includeFiles":["guides/subscriptions/**/*.md"],"excludeFiles":[]},{"title":"After the Payment","includeFiles":["guides/subscriptions/after-the-payment/**/*.md"],"excludeFiles":[]},{"title":"Managing Operations","includeFiles":["guides/managing-operations/**/*.md"],"excludeFiles":[]},{"title":"Platform Payments","includeFiles":["guides/platform-payments/**/*.md"],"excludeFiles":[]},{"title":"Payouts","includeFiles":["guides/payouts/**/*.md"],"excludeFiles":[]},{"title":"Developers","includeFiles":["additional-resources/developers/**/*.md"],"excludeFiles":[]},{"title":"Plugins","includeFiles":["additional-resources/plugins/**/*.md"],"excludeFiles":[]},{"title":"Industry Considerations","includeFiles":["guides/industry-considerations/**/*.md"],"excludeFiles":[]},{"title":"Regional Considerations","includeFiles":["guides/regional-considerations/**/*.md"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"commercetools","__idx":0},"children":["commercetools"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Accept payments with Finix on ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://commercetools.com"},"children":["commercetools"]},"."]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/commercetools-logo.0b906990dec93b157679703d3dcf63af9734a4adf8b242f23480eee8180ca403.a7b6f700.svg","alt":"commercetools","withLightbox":false,"style":"width: 800px; height: auto"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"commercetools-overview","__idx":1},"children":["commercetools Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"finix-requirements","__idx":2},"children":["Finix Requirements"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Finix Live Account"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Active commercetools account"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"integration","__idx":3},"children":["Integration"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-1-sign-up-for-a-finix-account","__idx":4},"children":["Step 1: Sign up for a Finix Account"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To create a Finix account, you can follow our step-by-step ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/getting-started/finix-sign-up"},"children":["guide"]}," or ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://finix.payments-dashboard.com"},"children":["sign up"]}," directly for a live or sandbox account."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":""},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We recommend choosing Direct Merchant as your Customer Type."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-2-create-a-cybersource-gateway-integration","__idx":5},"children":["Step 2: Create a Cybersource Gateway Integration"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Cybersource Integration"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Finix supports commercetools via our Cybersource Gateway integration. Please note that there is an additional fee for using our Cybersource integration."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, please reach out to your Finix point of contact."]}]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["To create a Cybersource integration, navigate to the Integrations page on your Finix Dashboard."]}]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/company-integrations-tab-direct-merchant.122c2c1c825f4eae56179fbbab7dccd64e2a27d406350be889d295ab1b71122a.08ff7529.png","alt":"Cybersource Merchant Integrations","withLightbox":false,"style":"width: 100%; box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15); border-radius: 8px"},"children":[]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":2},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sign up for Cybersource. You can view detailed instructions in our guide, ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/online-payments/gateway-integration/cybersource#creating-a-cybersource-integration-using-the-dashboard"},"children":["here"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["After accepting the Cybersource invitation email, retrieve the following credentials from the Cybersource Business Center under ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payment Configuration → Key Management"]}," — you'll need these to configure commercetools:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Merchant ID"]}," (also called Organization ID)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REST API Key"]}]}]}]}]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/cybersource-key-management.8ca4ad79eaed0ff8320a9a6c38bac88625381127fb749b31f80a4ec6c4f5b99b.08ff7529.png","alt":"Cybersource Key Management","withLightbox":false,"style":"width: 100%; box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15); border-radius: 8px"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-3-set-up-your-commercetools-environment","__idx":6},"children":["Step 3: Set Up Your commercetools Environment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before proceeding, ensure your commercetools environment is ready:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Active commercetools ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"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"},"children":["Merchant Center account"]}," with a configured project"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["API Client with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Manage"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["View"]}," scopes for: Customers, Extensions, Orders, Payments, and Types"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Node.js v16.3.0 or later"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["256MB minimum memory allocation for the plugin service"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-4-install-and-configure-the-cybersource-plugin","__idx":7},"children":["Step 4: Install and Configure the Cybersource Plugin"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before you proceed, ensure you have:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Approved Finix Merchant Account"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cybersource Gateway Integration linked to your Finix Merchant Account"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["commercetools project with API Client configured"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Install the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cybersource-plugins-commercetools"]}," package from the Cybersource GitHub repository. For full installation details, refer to the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.cybersource.com/technology-partners/commercetools.html"},"children":["Cybersource commercetools developer documentation"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once installed, populate the following environment variables in your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env"]}," file:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Cybersource credentials:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYMENT_GATEWAY_MERCHANT_ID"]}," — your Cybersource Merchant ID from Step 2"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYMENT_GATEWAY_MERCHANT_KEY_ID"]}," — your REST API Key ID from Step 2"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYMENT_GATEWAY_MERCHANT_SECRET_KEY"]}," — your REST API Shared Secret from Step 2"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYMENT_GATEWAY_RUN_ENVIRONMENT"]}," — set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TEST"]}," for sandbox or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PRODUCTION"]}," for live"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYMENT_GATEWAY_TARGET_ORIGIN"]}," — your frontend base URL"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["commercetools credentials:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CT_PROJECT_KEY"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CT_CLIENT_ID"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CT_CLIENT_SECRET"]}," — from your commercetools API Client"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CT_AUTH_HOST"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CT_API_HOST"]}," — your commercetools server URLs"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Optional feature flags:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYMENT_GATEWAY_DECISION_MANAGER"]}," — enable Cybersource Decision Manager for fraud prevention"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYMENT_GATEWAY_SCA_CHALLENGE"]}," — enforce 3D Secure for SCA-compliant transactions"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYMENT_GATEWAY_3DS_RETURN_URL"]}," — redirect URL for 3D Secure authentication flow"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYMENT_GATEWAY_ENABLE_RATE_LIMITER"]}," — restrict saved card usage"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-5-deploy-and-activate-the-plugin","__idx":8},"children":["Step 5: Deploy and Activate the Plugin"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once your environment variables are configured, start the plugin service:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"npm run start\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Then call the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/configurePlugin"]}," endpoint to register the API extensions within your commercetools project. This establishes the payment extension hooks that route transactions through Cybersource."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After completing configuration, you can now take payments through Finix via our Cybersource Gateway Integration."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To learn more about our Cybersource Gateway Integration, you can read our ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/online-payments/gateway-integration/cybersource"},"children":["guide"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you need additional assistance contact ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"mailto:support@finix.com"},"children":["support@finix.com"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"commercetools-transactions","__idx":9},"children":["commercetools Transactions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you run a transaction on commercetools, you'll see it:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In your commercetools Merchant Center under ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Orders"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In the Cybersource Business Center."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In your Finix Dashboard under ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Transactions"]}," → ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payments"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These transactions will be ingested by Finix and added to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Settlements"]},". To track transfers between Finix and Cybersource, please refer to our guide, ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/online-payments/gateway-integration/cybersource#locating-cybersource-transactions"},"children":["here"]},"."]}]},"headings":[{"value":"commercetools","id":"commercetools","depth":1},{"value":"commercetools Overview","id":"commercetools-overview","depth":2},{"value":"Finix Requirements","id":"finix-requirements","depth":3},{"value":"Integration","id":"integration","depth":2},{"value":"Step 1: Sign up for a Finix Account","id":"step-1-sign-up-for-a-finix-account","depth":3},{"value":"Step 2: Create a Cybersource Gateway Integration","id":"step-2-create-a-cybersource-gateway-integration","depth":3},{"value":"Step 3: Set Up Your commercetools Environment","id":"step-3-set-up-your-commercetools-environment","depth":3},{"value":"Step 4: Install and Configure the Cybersource Plugin","id":"step-4-install-and-configure-the-cybersource-plugin","depth":3},{"value":"Step 5: Deploy and Activate the Plugin","id":"step-5-deploy-and-activate-the-plugin","depth":3},{"value":"commercetools Transactions","id":"commercetools-transactions","depth":2}],"frontmatter":{"seo":{"title":"commercetools Integration","description":"Integrate Finix with commercetools to accept card transactions via our Cybersource Gateway integration."},"keywords":{"includes":["commercetools"]}},"lastModified":"2026-06-17T22:42:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/additional-resources/plugins/commercetools-integration","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}