Custom Label Now Available in Merchant Identifiers

📘
Labeling existing merchants
Once you've shared how you'd like your custom label configured, our team will set it up for you. From that point forward, newly boarded merchants are labeled automatically.
If you have a use case where a backfill to label existing merchants is needed, reach out to us on the Customer Support Portal and we will open a project to address this for you.

What's new?

Submerchants can now carry a custom label, an optional name/value pair assigned during boarding that lets you identify merchants according to criteria you define such as a Subscription Tier, Internal Account ID, or Sales Region. The label is returned as a CustomLabel entry within merchantIdentifiers on both submerchant and transaction responses.

In Backoffice, the label appears on the Submerchant Profile and in the Transaction export. See Tag Your Merchants with a Custom Label for details on configuring the label at boarding and where it appears in the web interface.

The CustomLabel identifier

CustomLabel is a single merchant identifier whose value is a small JSON document containing both halves of the pair, name and value, stored as a string:

{"name":"Subscription Tier","value":"Gold"}

Not every merchant carries a label. Expect the CustomLabel key to be missing on merchants that never had one, and present with an empty value on merchants whose label was cleared. Treat an empty value as no label rather than expecting the key to disappear.

The shape differs between the two responses. A submerchant response returns merchantIdentifiers as an object, with CustomLabel as a keyed property. See Review Submerchant Information (Launchpay API Reference link coming soon) for the full submerchant response.

"merchantIdentifiers": {
    "MID": "70944180506",
    "CoBrand": "examplepayfac",
    "CustomLabel": "{\"name\":\"Subscription Tier\",\"value\":\"Gold\"}"
}

A transaction response returns it as an array of key/value entries:

"merchantIdentifiers": [
    { "key": "MID", "value": "70944180506" },
    { "key": "CoBrand", "value": "examplepayfac" },
    { "key": "CustomLabel", "value": "{\"name\":\"Subscription Tier\",\"value\":\"Gold\"}" }
]