Skip to main content
Sign in

Configure Custom Payment Metadata for Supported Payment Gateways

Jansi Hendry
  • Updated

Contents

Overview

You can send selected Payment custom field values to supported payment gateways as metadata during payment processing, so your business-specific information — such as a Site ID, customer reference, or sales agent code — is available for reporting, reconciliation, and operational tracking directly in your gateway's transaction records.

Administrators configure which Payment custom fields are sent, and to which gateway account, using the Send Custom metadata setting in General Settings. Once configured, Ordway automatically includes the selected field values in future payment requests sent to that gateway account.

Supported Gateways

Custom metadata is supported for: 

Supported Use Cases

  • Send payment custom field values to supported payment gateways.
  • Include business-specific identifiers in payment transactions.
  • Transmit payment metadata for supported gateway integrations.

Prerequisites

Before configuring custom payment metadata:

  • At least one supported payment gateway account must already be configured in Ordway.
  • One or more custom fields must exist on the Payments object.
  • You must have permissions to manage Company Settings.
  • For Braintree, the corresponding custom fields must already exist in your Braintree merchant account.

How It Works

The Custom Metadata setting allows administrators to select Payment custom fields that should be transmitted during payment processing.

When a payment is created:

  1. Ordway retrieves the Payment custom fields configured for that gateway account.
  2. Ordway collects the current values of those fields.
  3. Ordway sends the selected field values to the configured gateway account as part of the payment request.
  4. The gateway stores the values in its transaction metadata, based on that gateway's own implementation.

Note: Only custom fields created on the Payments object are available for selection. Custom metadata configuration is maintained separately for each gateway account, so you can select different fields for different accounts — even accounts on the same gateway. 

Supported Custom Field Types

The Send Custom metadata setting supports Payment custom fields, including: 

  • Text fields
  • Picklist fields
  • Formula fields
  • Inherited fields
  • Other supported Payment custom field types

Important: If no Payment custom fields exist, no fields are available for selection.

Configure Custom Payment Metadata

Step 1: Navigate to General Settings

  1. Navigate to Setup > Settings. The Company Settings page is displayed.
  2. Scroll to the Payments section.
  3. The Send Custom Metadata option is displayed.

Step 2: Add and Select a Gateway Account 

  1. Click + Add Gateway. 
  2. select the configured gateway account you want to set up (for example, a specific Braintree, Adyen, Heartland, or Ordway Payments account) from the Select Gateway dropdown. 

Note: If your business uses more than one account for the same gateway (for example, two separate Braintree accounts), each account appears as its own entry and can have its own custom metadata configuration. 

Step 3: Select Custom Fields

  1. In Send Custom Metadata, next to the gateway account click Select Fields.
  2. Select one or more Payment custom fields to send as metadata for that gateway account.
  3. Click Save.

The selected fields are associated with the selected gateway account.

Step 4: Save Configuration

  • Click Save.
  • Future payments processed through the configured gateway account will include the selected metadata fields. 

Remove a Gateway's Metadata Configuration

To stop sending custom metadata to a gateway account, select the delete (trash) icon next to that gateway account's row. This removes the custom metadata configuration for that account only; other configured gateway accounts aren't affected.

Field Details

Attribute Value
Label Send Custom Metadata
Tooltip Select payment custom fields to send as metadata for each gateway during payment processing.
Default State No fields selected
Selection Type Multi-select
Available Fields Payment custom fields
Configuration Scope Per gateway

Example Configuration

Assume a business wants to pass a Site ID to the payment gateway.

Step 1: Create a Payment Custom Field

Create a Payment custom field:

Field Label API Name
Site ID site_id

The field may:

  • Store values directly on the Payment record.
  • Inherit values from another object such as Customer.
  • Use a formula to populate values dynamically.

Step 2: Select the Field

Add the Site ID Payment custom field to the Send Custom metadata configuration for the relevant gateway account. 

Step 3: Process a Payment

When a payment is processed, the Site ID value is transmitted to the gateway.

Example payload representation (actual structure varies by gateway): 

{

  "custom_fields": {

    "site_id": "USA Florida"

  }

}

Gateway-Specific Behavior

Braintree

Selected custom fields are mapped to Braintree's customFields object. 

Note: Custom fields must be pre-configured in your Braintree merchant account before they can be used in payment transactions, and the field's API name in Ordway must exactly match the API name defined in Braintree. 

Example

{

  "customFields": {

    "Ordway Site ID": "ABC-11"

  }

}

Requirements

  • Custom fields must be configured in both Ordway and Braintree.
  • API names must match exactly between systems.
  • Metadata transmission should not fail payment processing if the field does not exist in Braintree.

Adyen

Selected custom fields are transmitted within the metadata object. 

Note: You can send up to 20 metadata fields via Adyen. Metadata is visible on the Adyen transaction details page under Metadata. 

Example

{

  "metadata": {

    "site_id": "USA Florida"

  }

}

The metadata is visible in the Adyen transaction details page.

Ordway Payments

Selected custom fields are included in the processor metadata payload and are available through the payment API response, under custom_fields. 

Example

{

  "custom_fields": {

    "site_id": "USA Florida"

  }

}

Heartland

For Heartland, selected custom fields are included in the payment request sent to the payment processor. 

The configured metadata values are transmitted as part of the payment request sent to Heartland.

Verify Metadata Transmission

After processing a payment:

  1. Open the payment transaction in the payment gateway.
  2. Locate the metadata or custom fields section.
  3. Verify that the selected custom fields and values were transmitted successfully.

Verify Metadata in the Payment Gateway

Gateway Verification Location
Adyen Payment Details > Metadata
Braintree Transaction Details > Custom Fields
Ordway Payments Payment API Response

Behavior

When Custom Metadata Is Configured

  • Selected fields are transmitted during payment processing.
  • Values are sent using the field's API name.
  • Multiple fields can be transmitted at the same time.
  • Gateway-specific mappings are applied automatically.

When No Fields Are Selected

No custom metadata is transmitted to the payment gateway. 

When a Field Value Is Empty

The payment continues processing successfully.

When a Field Is Missing in the Gateway

Payment processing continues successfully. The missing metadata field does not cause payment failures.

Important Notes

  • Only Payment custom fields can be selected.
  • Metadata configuration is maintained separately for each gateway.
  • Multiple custom fields can be selected for a gateway.
  • Mandatory custom fields must not block payment processing.
  • Payment runs continue successfully even when configured metadata fields contain empty values.
  • The Send Custom Metadata setting does not create custom fields automatically. Create the required Payment custom fields before configuring metadata transmission.

Related Topics

Was this article helpful?
0 out of 0 found this helpful
Please sign in to submit a request.
Return to top

Related articles

Comments

0 comments

Please sign in to leave a comment.