--- updatedAt: 2026-08-31T14:23:57.000Z agentTools: projectIndex: https://docs.preczn.com/llms.txt --- # Creating Merchants Add merchants one at a time in the Dashboard or over the API, or in bulk from a CSV file or a processor connection you've already configured. Every merchant in Preczn is one record — business details, owners, bank accounts, and the credentials that tie it to each processor connection — identified by a merchant ID prefixed `mid_`. All four methods below produce that same record. Which one you want depends on how many merchants you're adding and whether they already exist somewhere else. | Method | Use it when | | ----------------- | -------------------------------------------------------------- | | Dashboard | Adding a merchant or two by hand | | Merchant API | Your platform creates merchants as part of its own signup flow | | CSV import | Moving an existing book of business into Preczn | | Connection import | The merchants already exist at a processor you've connected | # Create one merchant *** ## Create a merchant in the Dashboard The quickest way to add a single merchant is through the Merchant Vault. 1. Select **Merchant Vault** in the left navigation. 2. Select **+ New Merchant** in the toolbar above the merchant table. 3. In the **Create New Merchant** drawer, enter the **Merchant DBA Name**. This is the only required field — we suggest the merchant's legal business name. 4. Optionally add **Labels**. A merchant can carry up to three, they're stored in capitals, and they may contain letters, numbers, and spaces. Labels are your own organizing scheme, so pick names that will still make sense across your whole portfolio. See [Labeling Merchants](https://docs.preczn.com/docs/labeling-merchants). 5. Under **Merchant Credentials**, select a connection and enter this merchant's credentials, then save them to run verification. Preczn checks the credentials against the connection before the merchant is created. 6. Select **Create Merchant**. > 📘 Merchant credentials aren't always needed here > > Some processor connections require credentials at the merchant level; others provide them at the connection level and cover every merchant beneath. If your selected connection supplies connection-level credentials, you won't be asked for individual merchant credentials at this stage. > > A few connections board merchants through Preczn rather than accepting credentials for a merchant that already exists at the processor. For those, no credential fields appear — the connection is created with the merchant and activates once boarding completes. See [Merchant Onboarding](https://docs.preczn.com/docs/merchant-onboarding). ## Create a merchant with the API If your platform is already integrated with Preczn, creating merchants over the API lets you onboard them as part of your own signup flow rather than as a separate manual step. Start from the Merchant API endpoints — they carry the current fields and capabilities: * [Create Merchant](https://docs.preczn.com/reference/createmerchant) * [Add Merchant Owner](https://docs.preczn.com/reference/addmerchantowner) * [Add Merchant Bank Account](https://docs.preczn.com/reference/addmerchantbank) * [Add Merchant Attachment](https://docs.preczn.com/reference/addmerchantattachment) Many of these endpoints accept attachments on the child objects as well as on the merchant itself. For a worked example that creates a merchant with its business, owner, and bank information in a single request, see the [Creating a Merchant](https://docs.preczn.com/recipes/creating-a-merchant) recipe. # Import merchants in bulk *** ## Import merchants from a CSV file CSV import adds many merchants in one batch. You run it yourself from the Dashboard; the file is encrypted before it leaves your machine because it can carry bank accounts, credentials, and personal information. ### Run the import 1. Go to **Import** → **Merchant Import** and select **Upload CSV**. 2. Select **Download CSV Template**. The template is generated for your platform and the mode you're in, so it already contains a column for every connection you've configured. 3. Fill in your merchant data — see the column reference below. 4. Encrypt the file with Preczn's public PGP key. 5. Drag the encrypted `.gpg` file into the upload area. Files can be up to 100 MB. 6. Watch **CSV Import Activity** for the job to finish, then download its **Response File**. Preczn emails the user who started the import when processing completes. > 🚧 Download a fresh template whenever your connections change > > Adding a connection to your platform adds credential columns to the template. A file whose header doesn't match the current template is rejected as a whole — no rows are imported — so re-download the template rather than reusing an old file. ### Columns Two columns are required on every row: | Column | Purpose | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `platformUID` | Your own identifier for the merchant. It's echoed in the response file, which is how you match imported merchants back to your records. | | `name` | The merchant's DBA name. | `externalId` is optional and gives you a second reference value. Each `externalId` must be unique within the import. Owners and bank accounts use numbered column groups. The template ships with one of each; add more by continuing the numbering: | First | Second | | -------------------------- | -------------------------- | | `owner.0.firstName` | `owner.1.firstName` | | `owner.0.lastName` | `owner.1.lastName` | | `owner.0.ownershipPercent` | `owner.1.ownershipPercent` | | `banking.0.routing` | `banking.1.routing` | | `banking.0.account` | `banking.1.account` | Connection credential columns are named for the connection they belong to, and only appear for connections you've configured. Three columns control what happens to the merchant after it's created: | Column | Value | | -------- | ------------------------------------------ | | `plan` | The plan's ID | | `enable` | `TRUE` or `FALSE` | | `labels` | One or more labels separated by semicolons | ### Encrypt the file Install PGP tooling if you don't already have it — [GPG Tools](https://gpgtools.org/) on Mac, [GnuPG](https://gnupg.org/) on Windows and Linux. Download Preczn's public key. The **Public PGP Key** link on the Merchant Import page points at the right key for your environment: ``` https://core.preczn.com/tokenImportPublicKey.asc ``` Import it, then encrypt your file: ```bash gpg --import tokenImportPublicKey.asc gpg -r support@preczn.com -a -e --output merchants.csv.gpg merchants.csv ``` | Flag | Purpose | | ----------------------- | ------------------------ | | `-r support@preczn.com` | Recipient — Preczn's key | | `-a` | ASCII armor output | | `-e` | Encrypt | | `--output` | Output filename | ### Read the results The response file has one row per merchant you submitted: | Column | Description | | ------------------ | -------------------------------------- | | `platformUID` | Your identifier from the original file | | `precznMerchantId` | The new Preczn merchant ID (`mid_`) | | `status` | Whether the row succeeded | | `error` | Validation details, if it failed | Rows are validated individually against the same rules as the Merchant API, so an invalid row fails on its own while the rest of the import continues. Invalid connection credentials fail that row only. Two outcomes are worth checking for specifically. A plan is assigned only if the merchant has valid credentials for every connection that plan uses. A merchant is enabled only if it has both a plan and those credentials — merchants that miss either import successfully but arrive disabled. > 📘 Support can run large imports for you > > For a big migration, or if you'd rather hand off the file, work with your account manager or . ## Import merchants from a connection If your merchants already exist at a processor you've connected, Preczn can pull them across directly. Two methods are available, and support varies by connection — check [Supported Connections](https://docs.preczn.com/docs/supported-connections) for yours. Both require the connection to be configured first. See [Connection Configuration](https://docs.preczn.com/docs/connection-configuration). ### One-Time Merchant Import A one-time import pulls the merchants that exist at the connection right now. 1. Go to **Import** → **Merchant Import**. 2. Select **Connection API**. 3. Choose the connection from the dropdown. Only connections you've configured that support import appear here. 4. Select **Import**. Preczn imports the available merchant data and emails you when it finishes. The job appears in the table on the Merchant Import page, where you can follow its status and download the response file to review any merchants that failed and why. Some connections also offer an **Augment** option in the same dropdown. Rather than creating new merchants, an augment import refreshes data on merchants you already have in Preczn from that connection. > 📘 Imports take a few minutes > > How long an import runs depends on how many merchants the connection returns. The table on the Merchant Import page shows progress once you've started it. > 🚧 Keep sandbox data in Test mode > > Import sandbox data into Test mode only, and production data into Live mode. If something looks wrong, contact your Preczn representative or email . ### Continuous Merchant Import If your platform keeps adding merchants outside Preczn, a continuous import keeps them in sync without another manual pull. Open the connection's configuration and turn on the **Continuous Merchant Import** toggle. From then on, Preczn listens for merchant webhook events from that connection and creates a merchant when one reaches an active, fully boarded state at the processor. Waiting for that state means the underwriting data is complete, so you don't end up with half-populated merchant records. Preczn checks for an existing merchant with the same connection MID before creating one, so a merchant already linked to that connection won't be duplicated. > ❗️ Take care when you also create merchants yourself > > If your platform creates merchants in Preczn programmatically as well as running continuous import, a merchant created without its connection MID attached can be created a second time when the webhook arrives. Contact Preczn Support if you need to run both. # Troubleshooting *** ## Common import failures | Issue | Cause | What to do | | ------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------- | | Whole import rejected | The file header doesn't match the current template | Download a fresh template and re-enter your data | | Missing `platformUID` or `name` | A required column is empty | Give every row both values | | Duplicate `externalId` | The same `externalId` appears more than once | Make each one unique | | Invalid credentials | Connection credentials didn't verify | Confirm the credentials with the connection | | Plan not assigned | The merchant lacks credentials for one of the plan's connections | Add credentials for every connection the plan uses | | Merchant not enabled | No plan was assigned | Get plan assignment working first | | Validation error | A value doesn't match what the API accepts | Read the `error` column and correct the format | For anything the response file doesn't explain — template questions, data formatting, or interpreting results — contact your account manager or .