When your merchants have an existing relationship with a processor — boarded outside of Preczn — you can link those credentials to the merchant record and start routing through Preczn without boarding them again.

When to use this

Linking applies whenever a merchant already has a processor account that Preczn did not create:

• Migrating merchants to Preczn — your platform has merchants already processing with a provider, and you are adding Preczn to your stack
• Pre-boarded merchants — merchants completed onboarding directly with a processor before using Preczn
• Processor-managed onboarding — the processor handled merchant onboarding outside of Preczn's onboarding flow

If the merchant has no account with the processor yet, board them instead — see Merchant Onboarding.

Credentials

Whichever method you use, the same credential fields and the same validation apply.

Credential fields

Each connection requires a different combination of these, and refers to them by its own names — MerchantE's Profile ID is sent as key, and Till Payments' Secure Secret as environment. The connection's own guide lists exactly which values it needs, what the processor calls them, and where to find them; Supported Connections indexes every guide.

mid, key, secret, achMid, and urlPrefix cannot contain spaces.

urlPrefix applies only to CardPointe connections. A full CardPointe URL such as https://site-uat.cardconnect.com is also accepted and is normalized to the bare prefix before it is stored.

How validation works

Submitting credentials does not simply store them. Preczn:

1. Checks that every field the connection requires is present
2. Sends the credentials to the processor for verification
3. On success, saves the credentials and sets the connection status — normally Active, or whatever status the processor returns
4. On failure, returns an error and saves nothing

Because nothing is persisted until the processor accepts the credentials, a failed attempt leaves the existing connection untouched.

📘

Use sandbox credentials in Test mode

Test-mode connections route to the processor's sandbox, so they need the sandbox credentials your processor issued — not your production ones. See Live vs Test Mode.

Link credentials in the Dashboard

Adding credentials during merchant creation

When you create a merchant, you select the connections it is enabled to process against. Selecting a connection reveals the fields that connection requires, and a Save to Verify Credentials notice stays visible until you save.

Enter the merchant's details for the connection and select Save Connection. Repeat for each additional connection the merchant is enabled for.

Editing and adding credentials

To add or change credentials on an existing merchant, open the merchant's detail page and select the connection in the Connections pane. The connection drawer opens.

Select Configure Credentials on a connection that is still Unconfigured, or Edit Credentials on one that already has values. Enter the credentials and select Save Changes — the button reads Verifying… while Preczn checks the values with the processor.

Stored credentials are masked when the drawer reads them back, for example ****5678. Leaving a masked field untouched keeps the stored value, so you can change one credential without re-entering the others.

Link credentials via the API

Use the API to link credentials programmatically — for migrating large numbers of merchants, or building an automated onboarding flow.

Endpoint

PATCH /v1/merchants/{merchantId}/connections/{connectionId}

The request is idempotent, and it holds a lock on the merchant while it runs, so concurrent updates to the same merchant are serialized rather than racing.

Adding credentials

Send only the credential fields for the connection. Any of mid, key, secret, environment, applicationId, achMid, or urlPrefix triggers verification with the processor.

Request:

{
  "mid": "acct_1234567890",
  "secret": "sk_live_abc123def456"
}

Successful response (200): the updated merchant object, with the connection status set to the verified value — normally Active.

Updating existing credentials

Updating uses the same request. Send the connection's full credential set, with the new value in place of the old one.

Masked values are safe to send back. A value containing the masking characters — the form the Dashboard returns when it reads credentials — is swapped for the stored credential instead of overwriting it. That means a payload read from the Dashboard can be submitted with only the changed field replaced, and the masked ones will keep their stored values.

{
  "mid": "acct_1234567890",
  "secret": "sk_live_new_secret_key"
}

Verification runs before anything is written, so an update that the processor rejects leaves the existing credentials in place.

Error responses

Errors return the standard envelope:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid connection credentials. Please update credentials and submit again."
}