Merchant External IDs

An External ID is your own identifier for a merchant, such as the account ID from your CRM or your platform. Preczn stores it on the merchant record so you can match Preczn merchants, API responses, and webhooks back to your system.

An External ID follows these rules:

It's optional. A merchant doesn't need one.
It's unique. Each External ID belongs to one merchant in your platform. Live and Test mode are checked separately, so one Live merchant and one Test merchant can share a value.
It's up to 50 characters.

Set an External ID in the Dashboard

In the left navigation, select Merchant Vault and open the merchant.
In the merchant header, next to External ID, select the edit icon.
In Edit Merchant's External ID, enter the value.
Select Save.

To remove an External ID, clear the field and select Save.

Preczn records the change, with the old and new values, in the merchant's activity log and sends a merchant.updated webhook.

Set an External ID with the API

Include externalId when you create a merchant with POST /v1/merchants or update one with PATCH /v1/merchants/{merchantId}:

{
  "externalId": "crm-account-10482"
}

To keep the current External ID, omit externalId from the request. The API doesn't remove an External ID: an empty value leaves the current one in place. To remove one, use the Dashboard.

If another merchant in the same mode already holds the value, the API returns 409 Conflict:

A merchant already exists with this external ID (MID: mid_2zyd88xrnr90xskmjmqpd0x1vj)

Set External IDs in a CSV import

The merchant CSV import has an optional externalId column. Each value must be unique within the file. See Import merchants from a CSV file.

Find a merchant by External ID

In the search bar at the top of the Dashboard, set the search type to External ID and enter the value. The search matches the whole value exactly, including any prefix, in the mode you're in.

The Merchant Vault shows each merchant's External ID as EID, under its MID.

GET /v1/merchants doesn't filter by External ID. To look up a merchant through the API, store the Preczn merchant ID (mid_) next to your External ID and call GET /v1/merchants/{merchantId}.

Where the External ID appears

Merchant API responses and merchant webhooks. externalId is on the merchant record, so every merchant.created, merchant.updated, and merchant.deleted webhook carries it. See Merchant Webhook Payloads.
Adyen for Platforms. Preczn sends it as the reference on the account holder and balance account it creates.
Ramp. Preczn sends it as the application's partner_reference.

For Adyen for Platforms and Ramp, Preczn uses the merchant ID when there's no External ID. No other connection receives the External ID.

Cloning a merchant

When you clone a merchant, you can transfer its External ID to the new merchant. The External ID moves: Preczn removes it from the original merchant. See Cloning Merchants.

FAQ

Can two merchants share an External ID?

No. Each External ID belongs to one merchant per mode, and a second merchant with the same value is rejected with 409 Conflict. If one business in your system needs two Preczn merchants, give each a distinct value, for example by adding a suffix. See Merchants and Connections.

Why doesn't the External ID search find my merchant?

The search matches the whole value exactly. Enter the complete External ID, including any prefix your system adds, and check that you're in the same mode, Live or Test, as the merchant.

How do I match a webhook to the merchant in my system?

Read data.externalId from the merchant webhook. If you didn't set an External ID on the merchant, match on data.id, the Preczn merchant ID, instead.

Does changing an External ID update the processor?

No. Adyen for Platforms and Ramp receive the External ID when Preczn creates the merchant's account or application. A later change updates Preczn and your webhooks, but not the record at the processor.

Can I use my platform's own account ID as the External ID?

Yes. That's what the field is for. Any value up to 50 characters works, as long as it's unique in the mode.