Create a gift card extension and configure the webhook

To create a custom integration with a gift card payment gateway, you perform the following steps:

1. Create the gateway extension. See Gift card extension details for information specific to this extension.
2. Upload the extension to the administration interface.
3. Enable the gateway for the sites that require it. Be sure to disable any other gift card payment gateways for those sites.
4. Configure the Generic Payment webhook by specifying the gateway URL and the username and password. Note that webhook settings are not site-specific. The configuration you supply applies to all sites that use this webhook.

Gift card extension details

The format of a payment gateway extension is described in the Create a Credit Card Payment Gateway Integration chapter. For a gift card gateway, the gateway.json file should be similar to the following:

{
  "provider": "Custom Gift Card",
  "paymentMethodTypes": ["physicalGiftCard"],
  "transactionTypes": {

    "physicalGiftCard": ["balanceInquiry", "authorize", "void", "refund"]
  },
  "processors" : {
    "physicalGiftCard": "genericGiftCard"
  }
}

The config.json file should be similar to the following:

{
  "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": "paymentMethodTypes",
      "type": "multiSelectOptionType",
      "name": "paymentMethodTypes",
      "required": false,
      "helpTextResourceId": "paymentMethodsHelpText",
      "labelResourceId": "paymentMethodsLabel",
      "defaultValue": "physicalGiftCard",
      "displayAsCheckboxes": true,
      "public": true,
      "options": [
          {
           "id": "physicalGiftCard",
           "value": "physicalGiftCard",
           "labelResourceId": "physicalGiftCardPayLabel"
         }
       ]
    },
    {
      "id": "giftCardMaxLength",
      "type": "stringType",
      "name": "giftCardMaxLength",
      "helpTextResourceId": "giftCardMaxLengthHelpText",
      "labelResourceId": "giftCardMaxLengthLabel",
      "required": true,
      "defaultValue": "19",
      "public": true
    },
    {
      "id": "giftCardPinRequired",
      "type": "booleanType",
      "name": "giftCardPinRequired",
      "helpTextResourceId": "giftCardPinRequiredHelpText",
      "labelResourceId": "giftCardPinRequiredLabel",
      "defaultValue": true,
      "public": true
    },
    {
      "id": "giftCardPinMaxLength",
      "type": "stringType",
      "name": "giftCardPinMaxLength",
      "required": false,
      "helpTextResourceId": "giftCardPinMaxLengthHelpText",
      "labelResourceId": "giftCardPinMaxLengthLabel",
      "defaultValue": "4",
      "public": true
    }
    {
      "id": "includeOrderInWebhookPayload",
      "type": "booleanType",
      "name": "includeOrderInWebhookPayload",
      "helpTextResourceId": "includeOrderHelpText",
      "labelResourceId": "includeOrderLabel",
      "defaultValue": true,
      "public": true
    }
  ]
}

The properties in the config.json file shown above create controls that appear in the Payment Processing settings in the administration interface. These controls allow the merchant to specify whether a shopper using a gift card is required to supply a PIN, as well as the maximum length of the gift card number and the PIN. The includeOrderInWebhookPayload property creates a checkbox for specifying whether or not to include the order data in the webhook call.