Merchants

Overview

Custodia exposes three merchant-related concepts partners use in different ways:

• Master Merchant (GET /md/api/MasterMerchants/search) is the network-wide parent merchant identity in Custodia’s catalog. For example, many locations can share one master record. Use Master Merchant when you are setting an activity merchant restriction by parent brand.
• Merchant Group (POST /md/api/MerchantGroups) is a tenant-defined group you create in your program. Use it to bundle merchants under a stable code, then reference the group in merchant restrictions with keyword type MerchantGroup when your program supports it.
• Merchant (GET /md/api/Merchants) is the individual merchant record, such as a specific location or processor merchant id. Use Merchant when you need the exact merchant record for transaction simulation.

Master Merchant Search

Search for the parent merchant identity by name. Use this result when building merchant restriction allowlists for an activity.

Headers

Query Parameters

Example Request

Search for master merchants whose name matches LinkedIn Ireland Unlim:

Using cURL:

curl -X GET 'https://sandbox.custodia-tech.com/md/api/MasterMerchants/search' \
  -G \
  --data-urlencode 'term=LinkedIn Ireland Unlim' \
  --data-urlencode 'filter={"where":{"cardIssuerId":"your-card-issuer-id"}}' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID"

Using JavaScript (fetch):

const term = 'LinkedIn Ireland Unlim';
const filter = {
  where: {
    cardIssuerId: 'your-card-issuer-id'
  }
};

const params = new URLSearchParams({
  term,
  filter: JSON.stringify(filter)
});

const response = await fetch(
  `https://sandbox.custodia-tech.com/md/api/MasterMerchants/search?${params}`,
  {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'x-appid': clientId
    }
  }
);

const masterMerchants = await response.json();

Response

On success the API returns a JSON array of master merchant objects.

[
  {
    "id": "98398b66-82c4-499c-84e4-f9e060dbf628",
    "commonId": "dadcfff2-df59-4e7c-922d-c8abed3b1600",
    "category": "7311",
    "name": "LINKEDIN IRELAND UNLIM",
    "cleanName": "LINKEDIN IRELAND UNLIM",
    "costType": null,
    "website": null,
    "active": true,
    "extra": null,
    "createdOn": "2021-01-11T07:45:34.000Z",
    "isMultiLineMerchantOverride": null,
    "companyId": "default",
    "profileId": null,
    "userId": null,
    "avsOverride": null,
    "taxId": null,
    "taxIdSet": null,
    "taxIdSetById": null,
    "microPayments": null,
    "_address": {
      "city": "Dublin",
      "country": "IRL",
      "address1": " ",
      "asText": "Dublin "
    },
    "cardIssuerId": "your-card-issuer-id"
  }
]

Master Merchant Response Fields

Merchant Search

Search for individual merchant records. Use this when you need the exact merchant id for sandbox transaction simulation.

Headers

Common where conditions

Name like patterns

Use SQL-style wildcards in the like string:

• % matches any sequence of characters (including none). %bal% finds names that contain bal (for example Balkan Flame).
• %bal: name ends with bal.
• bal%: name starts with bal.
• "options": "i": case-insensitive matching.

{
  "where": {
    "active": true,
    "cardIssuerId": "your-card-issuer-id",
    "name": {
      "like": "%bal%",
      "options": "i"
    }
  },
  "limit": 50
}

Example Request

Active merchants whose name contains bal, limited to 50 results:

Using cURL:

curl --location --request GET 'https://sandbox.custodia-tech.com/md/api/Merchants' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'x-appid: YOUR_CLIENT_ID' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'filter={"where":{"active":true,"cardIssuerId":"your-card-issuer-id","name":{"like":"%bal%","options":"i"}},"limit":50}'

Using JavaScript (fetch):

const filter = {
  where: {
    active: true,
    cardIssuerId: 'your-card-issuer-id',
    name: {
      like: '%bal%',
      options: 'i'
    }
  },
  limit: 50
};

const filterParam = encodeURIComponent(JSON.stringify(filter));
const response = await fetch(
  `https://sandbox.custodia-tech.com/md/api/Merchants?filter=${filterParam}`,
  {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'x-appid': clientId
    }
  }
);

const merchants = await response.json();

Response

On success the API returns a JSON array of merchant objects.

[
  {
    "id": "c8926bca-7894-4d0d-8502-708d643567c2",
    "commonId": "de4e3a1e-7d61-4f2a-8c0a-1f0000000013",
    "vendor": "issuer",
    "vendorId": "DIPRO-000013",
    "categories": [
      "5812"
    ],
    "name": "Balkan Flame",
    "cleanName": "balkan flame",
    "costType": null,
    "website": null,
    "active": true,
    "masterId": "uwFyXyckSRn_XNJh9wiW4",
    "extra": null,
    "createdOn": "2026-05-27T01:12:17.000Z",
    "isMultiLineMerchantOverride": null,
    "masterIdSet": true,
    "taxId": null,
    "taxIdSet": null,
    "taxIdSetById": null,
    "cleanNameScore": null,
    "phoneticNameScore": null,
    "_address": {
      "city": "Craiova",
      "country": "ROU",
      "address1": " ",
      "asText": "Craiova "
    },
    "mcc": 5812,
    "merchantId": "DIPRO000013",
    "merchantName": "Balkan Flame",
    "street": null,
    "city": null,
    "region": null,
    "postcode": null,
    "country": null,
    "phoneticName": "balkan flame",
    "cardIssuerId": "issuer"
  }
]

Merchant Response Fields

Merchant Groups

A merchant group is a tenant-defined collection of merchants that your program creates and manages. It has a display name, a stable unique code, and an optional description. Individual merchants are linked to the group through merchant group members: not stored directly on the group record.

Use merchant groups when you want to maintain a reusable list of approved vendors: for example all hotel chains or all meal-delivery platforms: and apply that list to spend permissions without naming every merchant separately.

Purpose

• Bundle merchants under one rule: create a group such as Hotels, add merchants as members, and reference the group once on a spend permission.
• Merchant restrictions: on an allocation’s merchants[] allowlist, use keyword type MerchantGroup with the group’s id as value. At authorization time, Custodia checks whether the transaction merchant belongs to that group. See Merchant restriction.
• Stable integration identifier: the code is the durable handle for API lookups and bulk imports; the name is what users see in the UI.

Merchant group vs other merchant types

Create Merchant Group

Creates a new merchant group for the company associated with your access token. After creation, use the returned id when referencing the group in merchant restrictions or when adding merchants to the group.

Headers

Request Body: mandatory fields

Optional fields

Example Request

Create a merchant group for hotel vendors:

Using cURL:

curl --location 'https://sandbox.custodia-tech.com/md/api/MerchantGroups' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'x-appid: YOUR_CLIENT_ID' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Hotels",
    "code": "MG-V4N8Q2JT",
    "description": "Approved hotel chains"
  }'

Using JavaScript (fetch):

const response = await fetch('https://sandbox.custodia-tech.com/md/api/MerchantGroups', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Hotels',
    code: 'MG-V4N8Q2JT',
    description: 'Approved hotel chains'
  })
});

const merchantGroup = await response.json();

Response

On success the API returns the created merchant group object (root JSON).

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "scope": "default",
  "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "partnerId": null,
  "name": "Hotels",
  "code": "MG-V4N8Q2JT",
  "description": "Approved hotel chains"
}

Get Merchant Groups

Returns merchant groups for the company associated with your access token. Pass a LoopBack filter query parameter to narrow results.

Headers

Query Parameters

Common where conditions

Example Request

Find merchant groups where code matches a known value:

Using cURL:

curl --location --request GET 'https://sandbox.custodia-tech.com/md/api/MerchantGroups' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'x-appid: YOUR_CLIENT_ID' \
  --data-urlencode 'filter={"where":{"code":"MG-V4N8Q2JT"}}'

Using JavaScript (fetch):

const filter = {
  where: {
    code: 'MG-V4N8Q2JT'
  }
};

const filterParam = encodeURIComponent(JSON.stringify(filter));
const response = await fetch(
  `https://sandbox.custodia-tech.com/md/api/MerchantGroups?filter=${filterParam}`,
  {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'x-appid': clientId
    }
  }
);

const merchantGroups = await response.json();

Response

On success the API returns a JSON array of merchant group objects.

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "scope": "default",
    "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "partnerId": null,
    "name": "Hotels",
    "code": "MG-V4N8Q2JT",
    "description": "Approved hotel chains"
  }
]

Get Merchant Group by ID

Retrieves a single merchant group by its id. Use the id returned from create merchant group or from get merchant groups.

Path Parameters

Example Request

Using cURL:

curl --location --request GET 'https://sandbox.custodia-tech.com/md/api/MerchantGroups/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'x-appid: YOUR_CLIENT_ID'

Using JavaScript (fetch):

const merchantGroupId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';

const response = await fetch(
  `https://sandbox.custodia-tech.com/md/api/MerchantGroups/${merchantGroupId}`,
  {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'x-appid': clientId
    }
  }
);

const merchantGroup = await response.json();

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "scope": "default",
  "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "partnerId": null,
  "name": "Hotels",
  "code": "MG-V4N8Q2JT",
  "description": "Approved hotel chains"
}

Update Merchant Group

Partially updates an existing merchant group. Only include fields you want to change. Do not send id, companyId, scope, or partnerId: they cannot be changed via this endpoint.

Path Parameters

Request Body

All fields are optional on update. Send only the properties you want to change:

Example Request

Update the display name and description:

Using cURL:

curl --location --request PATCH 'https://sandbox.custodia-tech.com/md/api/MerchantGroups/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'x-appid: YOUR_CLIENT_ID' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Hotels and Lodging",
    "description": "Approved hotel chains for travel"
  }'

Using JavaScript (fetch):

const merchantGroupId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';

const response = await fetch(
  `https://sandbox.custodia-tech.com/md/api/MerchantGroups/${merchantGroupId}`,
  {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'x-appid': clientId,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Hotels and Lodging',
      description: 'Approved hotel chains for travel'
    })
  }
);

const merchantGroup = await response.json();

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "scope": "default",
  "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "partnerId": null,
  "name": "Hotels and Lodging",
  "code": "MG-V4N8Q2JT",
  "description": "Approved hotel chains for travel"
}

Merchant Group Response Fields

Merchant Group Members

A merchant group member links an individual merchant record to a merchant group. After you create a group, add members so transactions at those merchants match the group on spend permissions.

Create Merchant Group Member

Adds a merchant to an existing merchant group for the company associated with your access token.

Headers

Request Body: mandatory fields

Optional fields

Example Request

Add a merchant to the Hotels merchant group:

Using cURL:

curl --location 'https://sandbox.custodia-tech.com/md/api/MerchantGroupMembers' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'x-appid: YOUR_CLIENT_ID' \
  --header 'Content-Type: application/json' \
  --data '{
    "merchantGroupId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "merchantId": "c8926bca-7894-4d0d-8502-708d643567c2"
  }'

Using JavaScript (fetch):

const response = await fetch('https://sandbox.custodia-tech.com/md/api/MerchantGroupMembers', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    merchantGroupId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    merchantId: 'c8926bca-7894-4d0d-8502-708d643567c2'
  })
});

const merchantGroupMember = await response.json();

Response

On success the API returns the created merchant group member object (root JSON).

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "scope": "default",
  "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "partnerId": null,
  "merchantGroupId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "merchantId": "c8926bca-7894-4d0d-8502-708d643567c2",
  "active": true
}

Get Merchant Group Members

Returns merchant group members for the company associated with your access token. Pass a LoopBack filter query parameter to narrow results: for example all merchants in a specific group.

Headers

Query Parameters

Common where conditions

Example Request

List active members of the Hotels merchant group:

Using cURL:

curl --location --request GET 'https://sandbox.custodia-tech.com/md/api/MerchantGroupMembers' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'x-appid: YOUR_CLIENT_ID' \
  --data-urlencode 'filter={"where":{"merchantGroupId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","active":true}}'

Using JavaScript (fetch):

const filter = {
  where: {
    merchantGroupId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    active: true
  }
};

const filterParam = encodeURIComponent(JSON.stringify(filter));
const response = await fetch(
  `https://sandbox.custodia-tech.com/md/api/MerchantGroupMembers?filter=${filterParam}`,
  {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'x-appid': clientId
    }
  }
);

const merchantGroupMembers = await response.json();

Response

On success the API returns a JSON array of merchant group member objects.

[
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "scope": "default",
    "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "partnerId": null,
    "merchantGroupId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "merchantId": "c8926bca-7894-4d0d-8502-708d643567c2",
    "active": true
  }
]

Get Merchant Group Member by ID

Retrieves a single merchant group member by its id. Use the id returned from create merchant group member or from get merchant group members.

Path Parameters

Example Request

Using cURL:

curl --location --request GET 'https://sandbox.custodia-tech.com/md/api/MerchantGroupMembers/b2c3d4e5-f6a7-8901-bcde-f12345678901' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'x-appid: YOUR_CLIENT_ID'

Using JavaScript (fetch):

const merchantGroupMemberId = 'b2c3d4e5-f6a7-8901-bcde-f12345678901';

const response = await fetch(
  `https://sandbox.custodia-tech.com/md/api/MerchantGroupMembers/${merchantGroupMemberId}`,
  {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'x-appid': clientId
    }
  }
);

const merchantGroupMember = await response.json();

Response

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "scope": "default",
  "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "partnerId": null,
  "merchantGroupId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "merchantId": "c8926bca-7894-4d0d-8502-708d643567c2",
  "active": true
}

Update Merchant Group Member

Partially updates an existing merchant group member. The most common use is setting active to false to remove a merchant from a group without deleting the record, or back to true to reactivate an existing membership. Do not send id, companyId, scope, or partnerId.

Path Parameters

Request Body

All fields are optional on update. Send only the properties you want to change:

Example Request

Deactivate a merchant group member:

Using cURL:

curl --location --request PATCH 'https://sandbox.custodia-tech.com/md/api/MerchantGroupMembers/b2c3d4e5-f6a7-8901-bcde-f12345678901' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'x-appid: YOUR_CLIENT_ID' \
  --header 'Content-Type: application/json' \
  --data '{
    "active": false
  }'

Using JavaScript (fetch):

const merchantGroupMemberId = 'b2c3d4e5-f6a7-8901-bcde-f12345678901';

const response = await fetch(
  `https://sandbox.custodia-tech.com/md/api/MerchantGroupMembers/${merchantGroupMemberId}`,
  {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'x-appid': clientId,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      active: false
    })
  }
);

const merchantGroupMember = await response.json();

Response

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "scope": "default",
  "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "partnerId": null,
  "merchantGroupId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "merchantId": "c8926bca-7894-4d0d-8502-708d643567c2",
  "active": false
}

Merchant Group Member Response Fields

Related documentation

• Create merchant group: create the group before adding members
• Merchant search: find the merchantId to add
• Merchant restriction: apply merchant groups to a spend permission
• Authentication: obtain access tokens