Setup of the extension module

The first part of the setup is the installation and deployment of the extension module for commercetools. It will communicate with Stripe from the level of commercetools.

Getting an extension module

You can find a Docker image of the extension module in our private registry. We recommend creating your own Dockerfile from our image. The extension configuration object should be injected as a build argument and turned into an environment variable. For example:

FROM registry.vuestorefront.cloud/vsf-enterprise/commercetools-stripe-integration-extension:2.0.1

ARG STRIPE_INTEGRATION_CONFIG

ENV STRIPE_INTEGRATION_CONFIG=$STRIPE_INTEGRATION_CONFIG

If you are a client of Alokai Cloud, then you can follow the steps below to deploy the extension module.

Adding a "Build commercetools Stripe integration extension" action below "Build middleware"

build-commercetools-stripe-integration-extension:
  runs-on: ubuntu-latest
  needs: configure-deployment
  steps:
    - name: Checkout code
      uses: actions/checkout@v1
    - name: Setup node
      uses: actions/setup-node@v1
      with:
        node-version: "16.x"
    - name: Build and publish docker image
      uses: elgohr/Publish-Docker-Github-Action@master
      with:
        name: ${{ secrets.PROJECT_NAME }}-storefrontcloud-io/commercetools-stripe-integration-extension:${{ github.sha }}
        registry: ${{ secrets.DOCKER_REGISTRY_URL || 'registry.vuestorefront.cloud' }}
        username: ${{ secrets.CLOUD_USERNAME }}
        password: ${{ secrets.CLOUD_PASSWORD }}
        dockerfile: .vuestorefrontcloud/docker/commercetools-stripe-integration-extension.Dockerfile
        buildoptions: "--compress"
        buildargs: STRIPE_INTEGRATION_CONFIG
      env:
        STRIPE_INTEGRATION_CONFIG: ${{ secrets.STRIPE_INTEGRATION_CONFIG }}

Where dockerfile: .vuestorefrontcloud/docker/commercetools-stripe-integration-extension.Dockerfile specifies a path to the Dockerfile example presented above.

Extend "Deploy middleware..." step in "deploy" job

Add a new object to the apps array inside payload of your request to the Farmer. This makes Farmer deploy the given image under the dedicated path. Modify:

- name: Deploy middleware on ${{ secrets.PROJECT_NAME }}.${{ secrets.CLOUD_REGION }}.gcp.storefrontcloud.io/api/
  run: |
    if curl -f -s -H 'X-User-Id: ${{ secrets.CLOUD_USERNAME }}' -H 'X-Api-Key: ${{ secrets.CLOUD_PASSWORD }}' -H 'Content-Type: application/json' -X PATCH -d '{
      "front_version":"${{ github.sha }}",
      "additional_apps": {
        "apps":[
          {
            "name":"middleware",
            "tag":"${{ github.sha }}",
            "image":"${{ secrets.DOCKER_REGISTRY_URL || 'registry.vuestorefront.cloud' }}/${{ secrets.PROJECT_NAME }}-storefrontcloud-io/vue-storefront-middleware",
            "path":"/api/",
            "port":"8181",
            "has_base_path":false
          }
        ],
        "enabled": true
      }
    }' ${{ secrets.CLOUD_API_BASE_URL || 'https://farmer.vuestorefront.cloud' }}/instance/${{ secrets.PROJECT_NAME }}-${{ secrets.CLOUD_REGION }}-gcp-storefrontcloud-io; then
      echo "Instance updated"
    else
      echo "Something went wrong during the update process..."
      exit 1
    fi

To the:

- name: Deploy middleware on ${{ secrets.PROJECT_NAME }}.${{ secrets.CLOUD_REGION }}.gcp.storefrontcloud.io/api/
  run: |
    if curl -f -s -H 'X-User-Id: ${{ secrets.CLOUD_USERNAME }}' -H 'X-Api-Key: ${{ secrets.CLOUD_PASSWORD }}' -H 'Content-Type: application/json' -X PATCH -d '{
      "front_version":"${{ github.sha }}",
      "additional_apps": {
        "apps":[
          {
            "name":"middleware",
            "tag":"${{ github.sha }}",
            "image":"${{ secrets.DOCKER_REGISTRY_URL || 'registry.vuestorefront.cloud' }}/${{ secrets.PROJECT_NAME }}-storefrontcloud-io/vue-storefront-middleware",
            "path":"/api/",
            "port":"8181",
            "has_base_path":false
          },
          {
            "name":"commercetools-stripe-integration-extension",
            "tag":"${{ github.sha }}",
            "image":"${{ secrets.DOCKER_REGISTRY_URL || 'registry.vuestorefront.cloud' }}/${{ secrets.PROJECT_NAME }}-storefrontcloud-io/commercetools-stripe-integration-extension",
            "path":"/commercetools-stripe-integration-extension/",
            "port":"8080",
            "has_base_path":false
          }
        ],
        "enabled": true
      }
    }' ${{ secrets.CLOUD_API_BASE_URL || 'https://farmer.vuestorefront.cloud' }}/instance/${{ secrets.PROJECT_NAME }}-${{ secrets.CLOUD_REGION }}-gcp-storefrontcloud-io; then
      echo "Instance updated"
    else
      echo "Something went wrong during the update process..."
      exit 1
    fi

Make sure to set STRIPE_INTEGRATION_CONFIG secret in your repository if you follow the workflow setup. You can learn about its content in the environment variables section.

Make sure your Fusion Auth user has permissions to vsf-enterprise namespace (instances array). Otherwise, you will get a HTTP 401 Code.

Environment variables

It's a good practice to setup a Basic authentication for extension module. If you are interested, the process is described in Protecting extension module with basic auth document. It requires changes in this step.

The image configured in the previous steps has one mandatory environment variable called STRIPE_INTEGRATION_CONFIG. It contains settings as attributes in a JSON structure:

{
  "stripe": {
    "stripeProfile1": {
      "secretKey": "sk_test_xxx"
    }
  },
  "logLevel": 20
}

STRIPE_INTEGRATION_CONFIG JSON structure contains different attribute groups as described below:

stripe attribute group: Multiple child attributes can be provided in the stripe attribute. Each direct child attribute must representant a Stripe merchant account,
authentication attribute group: To setup required Basic authentication,
other attribute group: Attributes in this group can be set as direct child attributes in the root of the JSON.

Preparing the credentials

For test environment create a test account, then you will be able to find them here.
For live environment follow the official Stripe documentation.

Required attributes

Group	Name	Content
`stripe`	`secretKey`	Stripe secret key.

Optional attributes

Group	Name	Content	Default value
`authentication`	`enabled`	Whether Basic authentication should be enabled or not.	`false`
`authentication`	`username`	Username for Basic authentication.	`undefined`
`authentication`	`password`	Password for Basic authentication.	`undefined`
other	`logLevel`	The log level. Here you can find list of available options.	`"info"`

Optional environment variables

PORT - tells on what port application will listen. By default, it equals 8080.

Commercetools project requirements

The resources below are required for the extension module to operate correctly.

Commercetools HTTP API Extension

In order to point the commercetools project to the listening extension module:

Open API Playground,
Make sure you've selected your desired project in the select input placed inside the page's header,
Set:

Endpoint as Extensions,
Command as Create,
Payload as:

{
  "key": "ctp-stripe-integration-payment-extension",
  "destination": {
    "type": "HTTP",
    "url": "URL_TO_YOUR_EXTENSION_MODULE_INSTANCE"
  },
  "triggers": [
    {
      "resourceTypeId": "payment",
      "actions": ["Create", "Update"],
      "condition": "paymentMethodInfo is defined AND paymentMethodInfo(paymentInterface is defined) AND paymentMethodInfo(paymentInterface=\"ctp-stripe-integration\")"
    }
  ],
  "timeoutInMs": 10000
}

As destination.url you have to set URL address where Extension module is available.

Click Go!!! button.

Custom payment type

In order to add Stripe payment type to the commercetools project:

Open API Playground,
Make sure you've selected your desired project in the select input placed inside the page's header,
Set:

Endpoint as Types,
Command as Create,
Payload as:

{
  "key": "ctp-stripe-payment-elements-payment-type",
  "name": {
    "en": "commercetools Stripe integration payment custom type based on Payment elements"
  },
  "resourceTypeIds": ["payment"],
  "fieldDefinitions": [
    {
      "name": "stripeProfile",
      "label": {
        "en": "stripeProfile"
      },
      "required": true,
      "type": {
        "name": "String"
      },
      "inputHint": "SingleLine"
    },
    {
      "name": "createPaymentIntentRequest",
      "label": {
        "en": "createPaymentIntentRequest"
      },
      "type": {
        "name": "String"
      },
      "inputHint": "MultiLine",
      "required": true
    },
    {
      "name": "createPaymentIntentResponse",
      "label": {
        "en": "createPaymentIntentResponse"
      },
      "type": {
        "name": "String"
      },
      "inputHint": "MultiLine",
      "required": false
    }
  ]
}

Click Go!!! button.

Running

If you want to run it locally, you can use the sample Dockerfile created in the "Getting an extension module" guide.

Make sure to provide the required STRIPE_INTEGRATION_CONFIG environment variable.

How to point commercetools to extension module that running locally

In order to do that, we recommend using tunneling software, like ngrok or localtunnel. It should give you an URL with TLS for development purpose.

Make sure to remove pointer to your local instance of extension module from commercetools before you finish development. Otherwise, commercetools won't be able create and update payments as it will wait for the response from URL provided in Commercetools HTTP API Extension step.