Using CustomFields to parse data from your Software / App

This article is intended for developers who would want to redirect users from their application or software to a Hosted Checkout / Overlay Checkout - and recognize the User's ID.

Custom Fields for Products, Subscriptions, and Overlays

Define Custom Fields for products, subscriptions, and overlays to add flexibility in handling custom metadata for each resource. This document provides instructions on configuring these Custom Fields effectively, including examples and screenshots for better understanding.

Finding and editing CustomFields for your Subscription products

Custom Fields Overview

Custom Fields allow you to add additional metadata to products, subscriptions, or overlays. This metadata can include internal IDs, customer notes, or any other information that helps streamline transaction management.

Custom Fields can be defined at both the project level and the individual product level. Product-level Custom Fields take precedence over project-level Custom Fields, allowing more specific data, such as a user's internal ID, to be passed throughout the transaction process and returned via webhook notifications.

Where to Use Custom Fields

• Products: Define Custom Fields for individual products in addition to existing project-level Custom Fields.

• Subscriptions: Use Custom Fields to manage subscription-specific information for users.

• Overlays: Add Custom Fields to overlays, which can be validated using regular expressions (regex) or a validation API.

Redirecting Customers with Custom Fields (Hosted Checkout Example)

Attach Custom Fields as query parameters when redirecting customers to the platform for transactions. This allows custom data (e.g., a user ID) to be included in the checkout process and sent back via webhook upon completion. NOTE: All defined custom fields are required and must pass validation.

Custom Fields will be parsed from your app by URL parameter and be visible to the end-user

Custom Field Validation Failure

If custom field validation fails during checkout, the user will be informed, and they will not be able to proceed further until the validation passes.

Example URL with Custom Fields:

https://my-fungies-store.com/subscribe/9813eb2e-2305-4fa1-8096-9646bd8e63e8?user_id=sbs000001&server_name=sbs_europe

This data will be included in the webhook payload, making it easy to track and manage transactions in your app.

Embedding Overlays with Custom Fields

Custom Fields can be used when embedding overlays. These fields can be validated according to predefined rules using either regex validation or a custom validation API.

Process Overview:

1. Define Custom Fields and choose a validation method.

2. Add these fields when embedding an overlay.

3. The fields will be validated before the overlay is displayed, based on your configuration.

Overlay button with parsed URL parameters for user_id

Receiving Custom Fields in Webhook Notifications

Upon transaction or subscription completion, the Custom Fields are sent to your server through webhook notifications. This allows for seamless integration of user tracking or other metadata without requiring extra lookups.

Sample Webhook response with customFields parsed from your app

Webhook Payload: This is an example of a webhook payload that demonstrates the structure of Custom Fields. It illustrates how data such as user IDs and server names can be passed through the transaction process and returned via the webhook for tracking and integration.

Custom Fields Validation Options

When defining Custom Fields for products, subscriptions, or overlays, you have two main validation options:

• Regex Validation: Define a regular expression to ensure the data format is correct (e.g., a phone number or email address).

• Validation API: Provide an API endpoint to validate the customField values in real-time. You can also set a secret key to prevent unauthorized access to your validation API. Validation passes when the endpoint returns a code 200; any other code is recognized as a validation failure.

These options help you control the data being submitted, preventing invalid information from causing issues.

Defining custom fields

Summary

• Custom Fields can now be defined for products, subscriptions, and overlays individually, in addition to project-level configurations. Product-level custom fields are prioritized over project-level custom fields.

• Attach Custom Fields as query parameters for user redirects involving transactions or embedded overlays.

• The Custom Fields are included in webhook responses for easy integration with your systems.

• Use regex or API validation to ensure the data integrity of Custom Fields.

• Remember the custom fields should be in JSON Format, like e.g.

data-fungies-custom-fields='{"user_id":"123"}'

Next Steps

To configure Custom Fields, navigate to the product, subscription, or overlay settings and define the necessary fields. Ensure that appropriate validation rules are set up, and test webhook payloads to verify accuracy and completeness.

If you have any questions, check out our developer documentation or reach out to our support team for assistance.