Meta fields for payment payload

How to use meta fields with your payment payload.


Meta fields play a crucial role in payment processing, providing essential data points that facilitate secure and efficient transactions. In this documentation, we'll delve into what meta fields are, why they're important, and how you can effectively utilize them to streamline their payment operations.

What are Meta Fields?

Meta fields are additional data parameters included in the payload when processing a payment transaction. They provide detailed information beyond the basic transaction details, enabling better tracking, analysis, and customization of the payment process.

Importance of Meta Fields

Meta fields are essential for several reasons:

  • Enhanced Transaction Management: Meta fields allow merchants to capture specific details about each transaction, facilitating better order management and tracking.
  • Improved Risk Assessment: Meta fields provide valuable data for assessing the risk associated with each transaction, enabling fraud prevention measures and authentication processes.
  • Customization and Personalization: Meta fields offer flexibility for merchants to customize the payment experience for their customers, enhancing user satisfaction and loyalty.
  • Compliance and Reporting: Meta fields help ensure compliance with regulatory requirements by capturing necessary information for reporting and auditing purposes.

Difference Between Required and Optional Meta Fields

Meta fields can be categorized as required or optional:

  • Required Meta Fields: These are essential data points that must be included in the payment payload for successful transaction processing. They typically include critical information such as customer contact details, order specifics, and risk assessment parameters.
  • Optional Meta Fields: Optional meta fields provide additional context or customization options for merchants but are not necessary for every transaction. They offer flexibility for merchants to tailor the payment process to their specific needs and preferences.

Different Categories of Meta Fields

Meta fields can belong to various categories, including:

  • Client Context: Browser and device information, screen dimensions, language settings, etc.
  • Customer Details: Personal and contact information, identity verification, etc.
  • Risk Assessment: Authentication, fraud prevention, risk scores, etc.
  • Order Information: Order amount, billing and delivery details, order description, etc.
  • Subscription Details: Subscription frequency, expiration date, etc.
  • Vendor Information: Vendor details, address information, etc.

How Meta Fields Fit Into Provider-Specific Requirements

Different payment providers may have specific requirements regarding meta fields. You can refer to Payrails Portal to understand which meta fields are required, optional, or supported by each provider. This ensures compliance and seamless integration with chosen payment partners.


To view all meta fields and there categories, login into your portal and navigate to /meta-fields page.

How To Use Meta Fields

Merchants should follow these best practices when using meta fields:

  • Understand Provider Requirements: Review integration requirements with the payment service provider to understand meta field requirements for each provider.
  • Include Required Meta Fields: Ensure that required meta fields are included in the payment payload to facilitate successful transaction processing.
  • Leverage Optional Meta Fields: Use optional meta fields to enhance transaction management, risk assessment, and customer experience as needed.
  • Regularly Update and Review: Stay informed about any updates or changes to meta field requirements and adjust integration accordingly.

Viewing Meta Field Requirements and Example Payload

You can access meta field requirements and example payloads through the merchant portal provided by their Payrails. The merchant portal includes documentation that outlines which meta fields are needed for each provider and provides examples of how to structure the payment payload.

Viewing Meta Field Requirements through Merchant Portal

Step 1: Log in to your merchant account.

Step 2: Navigate to the "Meta Fields" page within the merchant portal.

Step 3: Select the payment provider you're interested in and review the list of meta fields. Identify which meta fields are marked as optional or required for that provider. Additionally, examine the example payload provided.

Step 4: Ensure that you include all required meta fields in your payment payload when making transactions via the Payrails API. Test the results of your integration by initiating payments and verifying the outcomes.