Custom Metadata

What is Custom Metadata?

Custom metadata is an optional feature of the BR-DGE routing engine that lets you add unique labels or tags to your transactions.

This extra information can then be used in BR-DGE smart routing, giving you more control over how your payments are routed. It allows you to include business-specific details with each transaction, enabling dynamic payment routing rules driven by this metadata.

How does Custom Metadata work?

When you include a "customMetadata"object to your transaction request, BR-DGE will evaluate the provided fields, matching them to a relevant smart routing ruleset in your retail channel configuration. BR-DGE then route your transaction to the provider you have specified in the smart routing rule, based on the custom metadata provided.

How to Include Custom Metadata

To add custom metadata, you'll include a "customMetadata" object in the body of your API requests when creating payments using the /v1/payments endpoint or initiating payouts with the /v1/payouts endpoint.

The "customMetadata" object contains key-value pairs, where the key is the name of your custom data field, and the value is the information you want to associate with that field.

Limitations of Custom Metadata

You can send a maximum of 25 name-value pairs per transaction. Where each key and value can be no longer than 200 characters each.

Keys and values can only contain alphanumeric characters, hyphens, underscores, commas, and spaces. Leading and trailing spaces are not allowed in keys.

Example Request

{
  "amount": "2500",
  "currencyCode": "GBP",
  "customerOrderCode": "7716251",
  "paymentInstrument": {
    "type": "card",
    "nameOnCard": "John Smith",
    "pan": "4444 3333 2222 1111",
    "expiryDate": "01-99",
    "cv2": "123"
  },
// ... other transaction details ...
  "customMetadata": {
    "customer_tier": "gold",
    "shipping_region": "europe"
  }
}

To see the full API reference please visit our API documentation for the relevant endpoint:

Retrieving Custom Metadata

Custom Metadata can be retrieved for any transaction where it was originally provided as part of the initial request.

You can easily retrieve this information using our API's status retrieval endpoints. This allows you to access the contextual data you associated with each transaction for your reporting, analysis, and operational purposes.

{
  "code": "1000",
  "message": "Approved",
  "paymentId": "c2fcf424-d7df-4b8b-aa98-3a60ce990d7c",
  "status": "CAPTURED",
  "reference": "7716251",
  "psp": {
    "name": "Checkout.com",
    "transactionId": "pay_ahnjkwiuba7178ajnayb1"
  },
// ... other transaction details ...
  "customMetadata": {
    "customer_tier": "gold",
    "shipping_region": "europe"
  }
}

To fetch custom metadata for a specific transaction, you'll make a GET request to either the

💡
BR-DGE will store your custom metadata with the transaction details, regardless of the outcome of the transaction.

Additional Information

Custom Metadata should not be used pass PCI sensitive, or confidential data to BR-DGE. Please do not include this type of data in the "customMetadata" object

Metadata is only considered during the initial payment request. Some transaction operations, and flows will not respect any custom metadata you provide. Refunds, Voids, Captures, and subsequent 3-D Secure requests do not use the metadata.

📘
Custom metadata is still used during the initial payment request for all transactions. If you do not provide metadata in the initial payment request, BR-DGE will ignore any metadata you provide during an ongoing 3-D Secure payment flow.

Support

If you require additional support with custom metadata please contact our support team.