Create a credit card extension

Extensions let you add functionality to your store or settings to your administration interface.

For example, you can use extensions to upload custom widgets and widget elements to your store, or to add settings for a custom payment gateway to the Payment Processing page’s Payment Gateways tab.

Before you develop an extension, you must generate an ID that you will include in your extension file. After you develop the extension, you install it by uploading it to Oracle Commerce as a ZIP file. For a payment gateway, the directory structure of the ZIP file looks like this:

<extension-name>
   ext.json
   gateway/
      <gateway ID>/
         gateway.json
         config/
            config.json
            locales/
               <locale>.json

The JSON files in this structure are used to set various properties that configure the behavior of the extension. These files are discussed below, using a sample credit card payment gateway extension to illustrate their contents. You can find additional information about extensions in Create an Extension.

ext.json

The ext.json file contains metadata for the extension. For example:

{
  "extensionID": "c2e6a60e-579a-4190-af3e-5edc0cd8a725",
  "developerID": "999999",
  "createdBy": "Demo Corp.",
  "name": "DemoPaymentGateway",
  "version": 1,
  "timeCreated": "2016-01-01",
  "description": "Demo Payment Gateway"
}

Note that the extension ID must match the value generated on the Extensions page in the administration interface. See Install the extension and configure the gateway for more information.

gateway.json

The gateway.json file configures the following gateway settings:

• provider – A label describing the payment provider.
• paymentMethodTypes -- A list of the payment method types supported for the gateway.
• transactionTypes -- A list of supported transaction types for each supported payment type. For a credit card payment gateway, valid values are authorization, void, and refund.

In the following example, the Demo Payment Provider is configured to permit only credit card transactions, and to support authorization, void, and refund transactions:

{
  "provider": "Demo Payment Provider",
  "paymentMethodTypes": ["card"],
  "transactionTypes": {
    "card": ["authorization", "void", "refund"]
  }
}

config.json

The config.json file creates user interface elements in the administration interface for configuring gateway settings. For example:

{
  "configType": "payment",
  "titleResourceId": "title",
  "descriptionResourceId": "description",
  "instances" : [
    {
      "id": "agent",
      "instanceName": "agent",
      "labelResourceId": "agentInstanceLabel"
    },
    {
      "id": "preview",
      "instanceName": "preview",
      "labelResourceId": "previewInstanceLabel"
    },
    {
      "id": "storefront",
      "instanceName": "storefront",
      "labelResourceId": "storefrontInstanceLabel"
    }
  ],
  "properties": [
    {
      "id": "merchantId",
      "type": "stringType",
      "name": "merchantId",
      "helpTextResourceId": "merchantIdHelpText",
      "labelResourceId": "merchantIdLabel",
      "defaultValue": "merchant id",
      "required": true
    },
    {
      "id": "paymentMethodTypes",
      "type": "multiSelectOptionType",
      "name": "paymentMethodTypes",
      "required": true,
      "helpTextResourceId": "paymentMethodsHelpText",
      "labelResourceId": "paymentMethodsLabel",
      "defaultValue": "card",
      "options": [
         {
           "id": "card",
           "value": "card",
           "labelResourceId": "cardLabel"
         }
       ]
    },
    {
      "id": "includeOrderInWebhookPayload",
      "type": "booleanType",
      "name": "includeOrderInWebhookPayload",
      "helpTextResourceId": "includeOrderHelpText",
      "labelResourceId": "includeOrderLabel",
      "defaultValue": true,
      "public": true
    }
  ]
}

Notice the following settings in the example above:

• The configType property specifies the type of configuration the file contains. For a payment gateway, the value of this property should be payment.
• The instances property specifies an array of different instances of the resource being configured, which makes it possible to have multiple groups of the same settings in the administration interface. In the example above, there are separate settings created for the storefront, the Agent Console, and preview.
• The includeOrderInWebhookPayload property creates a checkbox for specifying whether or not to include the order data in the webhook call.
• The file specifies a number of resource properties. The labels used in the user interface are mapped to the resource IDs in the <locale>.json files, as described below.

<locale>.json

You create a separate <locale>.json file for each language supported in your administration interface. For example, you might have an en.json file for English, fr.json for French, and de.json for German. These files contain labels that appear in the administration interface when you select the Payment Gateways tab. For example:

{
  "resources": {
    "paymentMethodsLabel": "Payment Methods",
    "merchantIdLabel": "Merchant ID",
    "cardLabel": "Credit/Debit Card",
    "title": "Demo Payment Gateway Config",
    "description":"Demo Payment Gateway configuration",
    "agentInstanceLabel": "Agent Configuration",
    "previewInstanceLabel": "Preview Configuration",
    "storefrontInstanceLabel": "Storefront Configuration"
    "merchantIdHelpText": "Enter your Merchant ID",
    "paymentMethodsHelpText": "Select your payment method"
    "includeOrderLabel": "Include order data in webhook call?"
    }
}

The values of the properties in the file are applied to the corresponding resource ID in the config.json file. For example, the value of the paymentMethodsLabel property is used to set the value of the labelResourceID property of the JSON object in config.json that specifies the user interface controls.