Custom Metadata

Contents

• What is custom metadata?
• How to include custom metadata
  • Example request
  • Limits and restrictions
• Retrieving custom metadata
• Using custom metadata with Smart Routing
• Account switching
  • Configuration of account switching
  • Using custom metadata with Card-on-File
  • PayPal orders
  • Account switching error codes
• Support

What is custom metadata?

Custom metadata is an optional feature of the BR-DGE routing engine that enables you to add your own labels to transactions as key-value pairs. You can use it to:

• Route transactions with Smart Routing: create rules that send a transaction to a specific provider based on its metadata.
• Switch accounts: choose which of your accounts with a PSP processes a transaction.

How to include custom metadata

To add custom metadata, include a customMetadata object in the body of your API requests when creating payments using the /v1/payments endpoint, initiating payouts with the /v1/payouts endpoint, creating a PayPal order, or creating Cards-on-File using the endpoint /v1/payment-instruments.

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.

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, go to our API documentation for the relevant endpoint:

• Payments
• Payouts
• Card-on-File

Limits and restrictions

• Don’t include PCI-sensitive or confidential data in customMetadata.
• BR-DGE only uses metadata from the initial payment request. Refunds, voids, captures and later 3-D Secure requests don’t use it, and any metadata sent during a 3-D Secure flow is ignored.

Retrieving custom metadata

The status endpoints return custom metadata for any transaction that included it in the initial request, so you can use it for reporting and analysis. BR-DGE stores it whatever the transaction outcome.

{
  "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, make a GET request to any of these endpoints:

• /v1/payments/{paymentId}/status endpoint
• /v1/payouts/{payoutId}/status endpoint
• /v1/payment-instruments

Using custom metadata with Smart Routing

Within the Smart Routing feature, the Merchant Metadata fragment allows you to create routing rules based on custom data sent with your transaction requests.

Account switching

If you have more than one account with the same PSP, account switching lets you choose which account processes each transaction. To set it up for payments, payouts, or Card-on-File, contact Customer Support. You’ll agree which metadata keys and values select each account. You then include those keys and values in customMetadata on each request.

Using custom metadata with Card-on-File

You can use account switching when creating Cards-on-File. BR-DGE matches the customMetadata on the request to select the correct PSP account for token provisioning, in the same way as for payments.

If a card is saved during a payment, BR-DGE stores the payment’s customMetadata on the Card-on-File and reuses it for PSP token provisioning, including retries, so you don’t need to resupply it.

To use this feature, ensure that account switching is enabled, and supply customMetadata to select the correct account.

{
    "type": "card",
    "nameOnCard": "John Smith",
    "pan": "4242424242424242",
    "expiryDate": "03-30",
    "cv2": "737",
    "customerId": "1234567890",
    "address": {
        "buildingNumberOrName": "10a",
        "address1": "Flat 1",
        "address2": "Victoria House",
        "address3": "15 Apple Street",
        "town": "Edinburgh",
        "county": "Lothian",
        "country": "GB",
        "postcode": "BH23 6AA",
        "countrySubdivisionCode": "SCT"
    },
  "customMetadata": {
    "region": "GB"
  }
}

This feature works for any PSP when account switching is enabled.

PayPal orders

For PayPal orders created with customMetadata, the selected switchAccountId is returned in the responses from the following endpoints:

1. Authorize or Capture a payment for a PayPal Order.
2. Get the details of a PayPal Order.

Account switching error codes

If you receive one of these errors and need help, contact Customer Support and quote the error code.

Support

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