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 Cloud Service 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 the Developing Widgets guide.
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 areauthorization,void, andrefund.
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",
"name": "paymentMethodTypes",
"required": true,
"helpTextResourceId": "paymentMethodsHelpText",
"labelResourceId": "paymentMethodsLabel",
"defaultValue": "card",
"options": [
{
"id": "card",
"value": "card",
"labelResourceId": "cardLabel"
}
]
}
]
}Notice the following settings in the example above:
The
configTypeproperty specifies the type of configuration the file contains. For a payment gateway, the value of this property should bepayment.The
instancesproperty 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 file specifies a number of resource properties. The labels used in the user interface are mapped to the resource IDs in the
<locale>.jsonfiles, 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",
"cardLabel": "Credit/Debit Card",
"title": "Demo Payment Gateway Config",
"description":"Demo Payment Gateway configuration.",
"agentInstanceLabel": "Agent Configuration",
"previewInstanceLabel": "Preview Configuration",
"storefrontInstanceLabel": "Storefront Configuration"
}
}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.
The following illustration shows how the extension appears in the administration interface. Notice that the user interface controls and labels reflect the values from the JSON files.
