# Register Submerchants and Descriptors for Ethoca Alerts
source: https://developer.mastercard.com/merchant-self-services/documentation/tutorials-and-guides/register-alerts-submerchants/index.md

## Overview {#overview}

Use this guide if you are a payment facilitator, acquirer, or merchant partner
that manages many submerchants for Ethoca Alerts for Merchants. You register
each submerchant and the identifiers that issuers see in transaction data. The
Alerts platform uses these identifiers to match dispute alerts to the right
submerchant.

The Merchant Self Services API supplies merchant details. It does not send or
resolve alerts. Alerts are delivered through the Alerts for Merchants APIs.

## Prerequisites {#prerequisites}

* A Mastercard Developers project with Sandbox credentials. See the [Quick Start Guide](https://developer.mastercard.com/merchant-self-services/documentation/tutorials-and-guides/quick-start-guide/index.md).
* An OAuth 1.0a signing setup. See [API Basics](https://developer.mastercard.com/merchant-self-services/documentation/api-basics/index.md).
* The values for the `User-Id`, `Submitter-First-Name`, and `Submitter-Last-Name` headers required by every request.
* For each submerchant: its name, its 4-digit Merchant Category Code (MCC), and the descriptors or acquirer identifiers that appear in its transactions.

## Register a Submerchant Step by Step {#register-a-submerchant-step-by-step}

### Step 1: Get Your Member ID {#step-1-get-your-member-id}

Send a request to the **getAlertsOrgProfiles** operation. Save the `memberId`
from the response. You use it as the `{member_id}` path parameter in every
later request.

See [Get organization profile details](https://developer.mastercard.com/merchant-self-services/documentation/use-cases/alerts-use-cases/index.md#get-organization-profile-details).

### Step 2: Register Acquirer Reference IDs {#step-2-register-acquirer-reference-ids}

Send a request to the **createAlertsAcquirerReferenceIdConfig** operation for
each acquirer that processes the submerchant's transactions. The required
fields are `acquirerReferenceId` and `cardScheme`. The optional
`binOnlyMatch` field controls matching behavior.

```json
{
  "acquirerReferenceId": "123456",
  "cardScheme": "MASTERCARD"
}
```

See [Create an acquirer reference ID configuration](https://developer.mastercard.com/merchant-self-services/documentation/use-cases/alerts-use-cases/index.md#create-an-acquirer-reference-id-configuration).

### Step 3: Create the Submerchant {#step-3-create-the-submerchant}

Send a request to the **createAlertsSubMerchant** operation. The required
fields are `name` and `merchantCategoryCode`. You can also send
`phoneNumber`, `country`, and `website`.

```json
{
  "name": "Merchant 1",
  "merchantCategoryCode": "3002"
}
```

Save the `subMerchantId` from the response. You use it as the
`{sub_merchant_id}` path parameter for this submerchant.

See [Create a submerchant](https://developer.mastercard.com/merchant-self-services/documentation/use-cases/alerts-use-cases/index.md#create-a-submerchant).

### Step 4: Add Card Acceptor Identifiers {#step-4-add-card-acceptor-identifiers}

Add one or both identifier types, depending on what is available for the
submerchant:

* **Card Acceptor ID (CAID):** Send a request to the **createAlertsCardAcceptorIdConfig** operation with the required `acquirerReferenceId` and `cardAcceptorId` fields. Use a CAID when you know the exact ARID and CAID pair.
* **Card Acceptor Name (CAN):** Send a request to the **createAlertsCardAcceptorNameConfig** operation with the required `cardAcceptorName` field. You can also send `cardAcceptorCity`, `cardAcceptorRegion`, and `cardAcceptorCountry`. Use a CAN when exact payment identifiers are unavailable.

```json
{
  "cardAcceptorName": "card_acceptor1",
  "cardAcceptorCity": "Toronto",
  "cardAcceptorRegion": "019",
  "cardAcceptorCountry": "CAN"
}
```

See [Add submerchant merchant identifiers](https://developer.mastercard.com/merchant-self-services/documentation/use-cases/alerts-use-cases/index.md#add-submerchant-merchant-identifiers).

### Step 5: Add Descriptor Match Criteria {#step-5-add-descriptor-match-criteria}

When the submerchant's statement descriptors vary across acquirers, channels,
or regions, send a request to the
**createAlertsMerchantDescriptorMatchCriteria** operation. Each criterion
requires `matchType` and `matchInput`. Use `EXACT_MATCH` for a full string
match or `STARTS_WITH_MATCH` for a prefix match of at least 3 characters. You
can send up to 100 criteria in one request. Check the response for both
successful and failed items.

```json
{
  "descriptorMatchCriteria": [
    {
      "matchType": "STARTS_WITH_MATCH",
      "matchInput": "MERCHANT 1"
    }
  ]
}
```

See [Create merchant descriptor match criteria](https://developer.mastercard.com/merchant-self-services/documentation/use-cases/alerts-use-cases/index.md#create-merchant-descriptor-match-criteria).

### Step 6: Verify the Registration {#step-6-verify-the-registration}

Retrieve what you registered and compare it with what you sent:

* **getAlertsSubMerchantByGuid** returns the submerchant.
* **getAlertsCardAcceptorIdConfigs** and **getAlertsCardAcceptorNameConfigs** return its identifiers.
* **getAlertsMerchantDescriptorMatchCriteria** returns the descriptor criteria.

## Register Many Submerchants {#register-many-submerchants}

Repeat Steps 3 to 6 for each submerchant. Step 1 is needed only once. Repeat
Step 2 only when a submerchant uses an acquirer that you have not registered
yet. Use **getAlertsSubMerchants** with the merchant name and status filters to
audit your submerchants after a bulk registration.

## Next Steps {#next-steps}

* Run the [Alerts Test Cases](https://developer.mastercard.com/merchant-self-services/documentation/testing/alerts-test-cases/index.md) in Sandbox.
* Review [Code and Formats](https://developer.mastercard.com/merchant-self-services/documentation/code-and-formats/index.md) for error recovery.
* See the [API Reference](https://developer.mastercard.com/merchant-self-services/documentation/api-reference/index.md) for every field and response.