Use the API to link existing processor credentials programmatically. This is useful for migrating large numbers of merchants or building automated onboarding flows.

Endpoint

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

Request Fields

Fields cannot contain spaces.

Adding Credentials

📘

Connection-Specific Fields

Each processor requires different credential fields. See Supported Connections for a list of available connections and their specific credential requirements.

Request:

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

Successful Response (200):

Returns the updated merchant object with the connection status updated (typically to Active).

Updating Existing Credentials

When credentials already exist on a connection, you must provide both the existing and new credentials for security verification.

Request:

{
  "mid": "acct_new_merchant_id",
  "secret": "sk_live_new_secret_key",
  "existingCredentials": {
    "mid": "acct_1234567890",
    "secret": "sk_live_abc123def456"
  }
}

Preczn verifies that existingCredentials matches what's on file before accepting the update.

Error Responses

Merchant Not Found (404)

The specified merchant does not exist or is not accessible.

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Merchant not found."
}

Connection Not Found (404)

The specified connection does not exist on the merchant.

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Connection not found!"
}

Invalid Credentials (400)

Credentials failed validation with the processor.

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

Missing Required Fields (400)

Required fields for the processor were not provided.

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "StripeConnect requires fields: mid"
}

Existing Credentials Mismatch (409)

When updating, the existingCredentials provided don't match what's on file.

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "The credentials passed in 'existingCredentials' do not match those on file. No updates have been made"
}

Processor Not Supported (400)

The processor doesn't support credential verification through this endpoint.

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "verify required fields not supported for this processor."
}

Validation Process

When you submit credentials:

1. Preczn checks that all required fields for the processor are provided
2. Credentials are validated with the processor's API
3. If valid, credentials are saved and connection status updates
4. If invalid, an error is returned and no changes are made