Skip to main content
All CollectionsDeveloper Hub
Plugin Development Documentation
Plugin Development Documentation

For developers building payment plugins for businesses powered by Billgang

Updated over a week ago

This document provides a comprehensive guide for developers creating payment plugins for Billgang. It details each step of the process, from configuring user input parameters to handling webhook responses, complete with code examples and practical use cases.

Creating a payment plugin for Billgang involves interfacing with a payment gateway, processing user inputs, and handling transaction updates.

This guide aims to provide a thorough understanding of each step involved in the plugin development process.

Step 1: Configuring setupParameters

The setupParameters field specifies the required information from users for the integration. This is similar to Custom Fields but includes isMain and variableName fields.

Fields

  • name: The display name of the parameter (string).

  • variableName: The internal name used to reference this parameter in the code (string).

  • required: Indicates whether the parameter is required (boolean).

  • placeholder: Placeholder text for the input field (string).

  • defaultValue: Default value for the parameter (can be null if no default value is provided).

  • type: The type of the input field (e.g., TEXT, NUMBER, EMAIL).

Special Fields

  • isMain: Used to differentiate unique account identifiers (boolean). For example, the email for PayPal accounts.

  • variableName: Allows you to access these saved variables in the code (string).

Example

"setupParameters": [
  {
    "name": "Api Key",
    "variableName": "ApiKey",
    "required": true,
    "placeholder": "Hoodpay Api Key",
    "defaultValue": null,
    "type": "TEXT"
  },
  {
    "name": "Business Id",
    "variableName": "BusinessId",
    "required": true,
    "placeholder": "Hoodpay Business Id",
    "defaultValue": null,
    "type": "NUMBER"
  }
]

This configuration will prompt the user to enter an API Key and Business ID.

Step 2: Accessing Saved Variables

To access the saved variables, use the placeholder syntax {{settings.GatewayAccount.$variableName}}. This placeholder will be automatically replaced with the actual values.

Example

"Authorization": "Bearer {{settings.GatewayAccount.ApiKey}}"

This will be replaced with Authorization: Bearer EXAMPLE_API_KEY_FROM_SAVED_SETTINGS.

Step 3: Setting Up External Flow

The setupExternalFlow executes a list of SendRequestActionManifest immediately after the user saves settings. This step is useful for validating seller input data or creating webhooks for the seller's payment provider account.

Available Variables

  • Shop Info

    • context.Shop.Id: The Shop ID.

    • context.Shop.Name: The Shop Name.

    • context.Shop.LogoUrl: The Shop Logo URL.

    • context.Shop.Domain: The Shop Domain.

  • GatewayAccount Variables

    • settings.GatewayAccount.$custom_value: The value saved in the gateway account settings.

  • Global Variable

    • settings.Gateway.WebhookCallbackUrl: The URL for receiving webhooks about payment statuses.

  • Saved Variables

    • {{context.SavedVariables.$variableName}}: The value saved from a previous step.

Potential Use Cases

  1. Validate seller's input data, e.g., sending a test request to the payment provider with the API key.

  2. Create a webhook for the seller's payment provider account.

Step 4: Creating SendRequestActionManifest

A SendRequestActionManifest includes send, save, and validate steps.

Fields

Send

  • url: The endpoint URL for the request (string).

  • method: The HTTP method to use (GET, POST, PUT, DELETE) (string).

  • body: The JSON body for POST and PUT requests (object).

  • headers: Additional headers (e.g., Authorization) (object).

Save

  • variableName: The name of the variable to save data (string).

  • responseBodySelectorJson: JSON path to the data in the response body (string).

  • responseStatusCode: Save the response status code (boolean).

Validate

  • firstValue: The first value to compare (string).

  • operation: The comparison operation (EQUALS, GREATER_THAN, LESS_THAN, CONTAINS, NOT_CONTAINS, NOT_EQUALS) (string).

  • secondValue: The second value to compare (string).

Example

{
  "url": "https://api.hoodpay.io/v1/businesses/{{settings.GatewayAccount.BusinessId}}/payments",
  "method": "POST",
  "body": {
    "currency": "{{context.Charge.Price.Currency}}",
    "amount": "{{context.Charge.Price.Amount}}",
    "metadata": {
      "processToken": "{{context.Charge.ProcessToken}}"
    },
    "notifyUrl": "{{settings.Gateway.WebhookCallbackUrl}}"
  },
  "headers": {
    "Authorization": "Bearer {{settings.GatewayAccount.ApiKey}}"
  },
  "save": [
    {
      "variableName": "PaymentId",
      "responseBodySelectorJson": "['data']['id']"
    },
    {
      "variableName": "StatusCode",
      "responseStatusCode": true
    }
  ],
  "validate": [
    {
      "firstValue": "{{StatusCode}}",
      "secondValue": "200",
      "operation": "EQUALS"
    }
  ]
}

Step 5: Creating a Charge

Use SendRequestActionManifests to create charges with the payment provider.

Available Variables

  • Shop Info

    • context.Shop.Id

    • context.Shop.Name

    • context.Shop.LogoUrl

    • context.Shop.Domain

  • GatewayAccount Variables

    • settings.GatewayAccount.$custom_value

  • Global Variable

    • settings.Gateway.WebhookCallbackUrl

  • Charge Info

    • context.Charge.Id

    • context.Charge.Price.Amount

    • context.Charge.Price.Currency

    • context.Charge.Price.AmountInCents

    • context.Charge.PriceUSD

    • context.Charge.PriceUSDInCents

    • context.Charge.ProcessToken

Step 6: Webhook Handling

Handle webhooks when the payment status changes on the provider's side. This step is similar to SendRequestActionManifest but excludes the send step.

Save Step

Save data from the response.

  • variableName: The variable to save data (string).

  • requestQueryParamName: Parse the info from the response JSON body (string).

  • requestHeaderName: Parse the header value by name (string).

You should pass only one of requestQueryParamName or requestHeaderName. You must save a variable with the name "ProcessToken" to identify the charge/order.

Example

{
  "save": [
    {
      "variableName": "ProcessToken",
      "requestQueryParamName": "['data']['processToken']"
    }
  ]
}

Validate Step

Match the Billgang charge status based on different conditions.

Example

"validate": {
  "PAID": [
    {
      "firstValue": "{{context.Variables.PaymentStatus}}",
      "secondValue": "COMPLETED",
      "operation": "EQUALS"
    }
  ],
  "PENDING": [
    {
      "firstValue": "{{context.Variables.PaymentStatus}}",
      "secondValue": "PENDING",
      "operation": "EQUALS"
    }
  ]
}

Webhook Handling Manifest

​This example saves the ProcessToken and PaymentStatus from the webhook response and validates the payment status to update the charge status in Billgang.

Example

{
  "save": [
    {
      "variableName": "ProcessToken",
      "requestQueryParamName": "['data']['processToken']"
    },
    {
      "variableName": "PaymentStatus",
      "requestQueryParamName": "['data']['status']"
    }
  ],
  "validate": {
    "PAID": [
      {
        "firstValue": "{{context.Variables.PaymentStatus}}",
        "secondValue": "COMPLETED",
        "operation": "EQUALS"
      }
    ],
    "PENDING": [
      {
        "firstValue": "{{context.Variables.PaymentStatus}}",
        "secondValue": "PENDING",
        "operation": "EQUALS"
      }
    ]
  }
}

Live Payment Platform Example

The following JSON manifest example integrates a payment gateway, covering all the steps from configuring setup parameters to handling webhooks.

{
  "setupParameters": [
    {
      "name": "Api Key",
      "variableName": "ApiKey",
      "required": true,
      "placeholder": "Hoodpay Api Key",
      "defaultValue": null,
      "type": "TEXT"
    },
    {
      "name": "Business Id",
      "variableName": "BusinessId",
      "required": true,
      "placeholder": "Hoodpay Business Id",
      "defaultValue": null,
      "type": "NUMBER"
    }
  ],
  "setupExternalFlow": [
    {
      "url": "https://api.hoodpay.io/v1/test",
      "method": "POST",
      "body": {
        "apiKey": "{{settings.GatewayAccount.ApiKey}}",
        "businessId": "{{settings.GatewayAccount.BusinessId}}"
      },
      "headers": {
        "Authorization": "Bearer {{settings.GatewayAccount.ApiKey}}"
      },
      "save": [
        {
          "variableName": "TestResponse",
          "responseBodySelectorJson": "['data']['response']"
        },
        {
          "variableName": "StatusCode",
          "responseStatusCode": true
        }
      ],
      "validate": [
        {
          "firstValue": "{{StatusCode}}",
          "secondValue": "200",
          "operation": "EQUALS"
        }
      ]
    },
    {
      "url": "https://api.hoodpay.io/v1/webhooks",
      "method": "POST",
      "body": {
        "url": "{{settings.Gateway.WebhookCallbackUrl}}",
        "event": "payment_status_changed"
      },
      "headers": {
        "Authorization": "Bearer {{settings.GatewayAccount.ApiKey}}"
      },
      "save": [
        {
          "variableName": "WebhookId",
          "responseBodySelectorJson": "['data']['id']"
        }
      ]
    }
  ],
  "createChargeFlow": [
    {
      "url": "https://api.hoodpay.io/v1/businesses/{{settings.GatewayAccount.BusinessId}}/payments",
      "method": "POST",
      "body": {
        "currency": "{{context.Charge.Price.Currency}}",
        "amount": "{{context.Charge.Price.Amount}}",
        "metadata": {
          "processToken": "{{context.Charge.ProcessToken}}"
        },
        "notifyUrl": "{{settings.Gateway.WebhookCallbackUrl}}"
      },
      "headers": {
        "Authorization": "Bearer {{settings.GatewayAccount.ApiKey}}"
      },
      "save": [
        {
          "variableName": "PaymentId",
          "responseBodySelectorJson": "['data']['id']"
        },
        {
          "variableName": "StatusCode",
          "responseStatusCode": true
        }
      ],
      "validate": [
        {
          "firstValue": "{{StatusCode}}",
          "secondValue": "200",
          "operation": "EQUALS"
        }
      ]
    }
  ],
  "webhookHandlingFlow": {
    "save": [
      {
        "variableName": "ProcessToken",
        "requestQueryParamName": "['data']['processToken']"
      },
      {
        "variableName": "PaymentStatus",
        "requestQueryParamName": "['data']['status']"
      }
    ],
    "validate": {
      "PAID": [
        {
          "firstValue": "{{context.Variables.PaymentStatus}}",
          "secondValue": "COMPLETED",
          "operation": "EQUALS"
        }
      ],
      "PENDING": [
        {
          "firstValue": "{{context.Variables.PaymentStatus}}",
          "secondValue": "PENDING",
          "operation": "EQUALS"
        }
      ]
    }
  }
}

Breakdown of Each Section

1. setupParameters

Defines the required input fields for the plugin setup. In this example, it asks for an API key and Business ID.

2. setupExternalFlow

Executes actions after the user saves their settings. This example includes:

  • Test Request: Validates the API key and Business ID by sending a test request.

  • Webhook Creation: Sets up a webhook on the payment provider to notify Billgang of payment status changes.

3. createChargeFlow

Handles the creation of charges. This involves:

  • Sending a request to the payment provider to create a payment.

  • Saving the payment ID and response status code.

  • Validating the response to ensure it was successful.

4. webhookHandlingFlow

Processes webhooks sent by the payment provider. This section:

  • Saves the ProcessToken and PaymentStatus from the webhook response.

  • Validates the payment status to update the charge status in Billgang.

Detailed Explanation of JSON Fields

setupParameters

  • name: Display name of the input field.

  • variableName: Internal reference name for the input field.

  • required: Boolean indicating if the field is mandatory.

  • placeholder: Placeholder text displayed in the input field.

  • defaultValue: Default value for the input field (can be null).

  • type: Type of input (e.g., TEXT, NUMBER, EMAIL).

setupExternalFlow

  • url: URL to send the request.

  • method: HTTP method (GET, POST, PUT, DELETE).

  • body: JSON body for POST and PUT requests.

  • headers: Additional headers (e.g., Authorization).

  • save: Steps to save data from the response.

    • variableName: Name of the variable to save data.

    • responseBodySelectorJson: JSON path to extract data from the response.

    • responseStatusCode: Save the response status code (boolean).

  • validate: Steps to validate the saved data.

    • firstValue: First value for comparison.

    • operation: Comparison operation (EQUALS, GREATER_THAN, LESS_THAN, etc.).

    • secondValue: Second value for comparison.

createChargeFlow

Similar structure to setupExternalFlow, but focused on creating a payment charge.

webhookHandlingFlow

  • save: Steps to save data from the webhook response.

    • variableName: Name of the variable to save data.

    • requestQueryParamName: JSON path to extract data from the response body.

  • validate: Steps to validate the payment status.

    • firstValue: First value for comparison.

    • operation: Comparison operation.

    • secondValue: Second value for comparison.

Implementation Notes

  • Dynamic Placeholders: Use {{settings.GatewayAccount.$variableName}} and {{context.Variables.$variableName}} to dynamically replace placeholders with actual values.

  • Error Handling: Ensure to handle errors gracefully by validating responses and logging any issues.

  • Security: Secure sensitive information such as API keys and tokens by storing them securely and using HTTPS for all requests.

  • Testing: Thoroughly test each step to ensure the integration works correctly with the payment provider.

By following this detailed guide, developers can create a robust JSON manifest for integrating a payment gateway with Billgang, ensuring a seamless payment processing experience.

Did this answer your question?