When your platform is migrating a large number of merchants, or adding merchants incrementally, you may want to programmatically manage merchant connection credentials via API rather than use the dashboard.

Adding Connection Credentials via API

In certain situations your merchants will have existing connection credentials that will be needed in order for Preczn to make transaction requests(as an example, your merchant may have a pre-existing relationship with Processor X that has a set of API credentials for that merchant).

The Merchant API supports adding merchant connect credentials by patching that merchants connection directly using the Update Connection Details endpoint.

Preczn offers 3 common credential parameters that can be set in the request (key, secret, mid). Depending on the connection you are trying to configure, you will need to send a combination of these secrets.
As an example, the connection Affinipay requires a single private_secret that should be submitted with secret in order to perform API transactions.
Please refer to the Connection Guide for the specific fields each merchant connect supports, or contact Preczn support for assistance.

In the following example, we highlight how a request would be made for a connection that requires only secret:

PATCH https://api.preczn.com/v1/merchants/{merchantId}/connection/{connectionID}

{
"secret":"xFPtMdvOmWOb9xBHzS4Kde6ZMvR6GrIa",
}

Before the credentials are saved, Preczn validates the credentials with connection and only saves them once the connection returns a success.
Upon saving, the response will include the updated merchant record. Notably the merchant connection status will have updated, most commonly to the 'Active' status (read Merchant Connection Statuses for more details on Merchant Connection Statuses) .

Depending on the format of the request and validity of the credentials, the response will come back in several different ways:

{
    "id": "mid_test_2f428vcgdf94kv6y7rjwms59hf",
    "active": false,
    "plan": "",
    "name": "Bobby's Ecommerce Shop",
    "legalName": "Bobby's Ecommerce Shop",
    "address": {
        "address": "Api Address 1",
        "address2": "Api Address 2",
        "city": "San Francisco",
        "region": "CA",
        "postal": "12345",
        "country": "USA"
    },
    "email": "[email protected]",
    "phone": "12223334444",
    "tin": "****6789",
    "tinType": "ein",
    "website": "https://www.bobbyshop.com",
    "mailingAddress": {
        "address": "Api Mailing Address 1",
        "address2": "Api Mailing Address 2",
        "city": "San Francisco",
        "region": "CA",
        "postal": "93000",
        "country": "USA"
    },
    "billingContact": {
        "address": "",
        "address2": "",
        "city": "",
        "region": "",
        "postal": "",
        "country": "",
        "firstName": "Jack",
        "lastName": "Harbor",
        "email": "",
        "phone": "12223334444"
    },
    "businessType": "corp",
    "publicCompany": false,
    "isBusinessAddress": true,
    "industry": "7371",
    "stateIncorporated": "CA",
    "dateEstablished": "1990-10-22",
    "customerServicePhone": "12223334444",
    "productServiceDescription": "Excellent Products and More",
    "mcc": "5734",
    "createdOn": "2024-02-09T03:48:38Z",
    "modifiedOn": "2024-02-09T04:06:17Z",
    "modifiedBy": "API Key: Default",
    "createdBy": "API Key: Default",
    "annualSaleVolume": 20000,
    "averageTicket": 3000,
    "shipToDays": 7,
    "owners": [],
    "banking": [],
    "connections": [
        {
            "id": "midCon_test_5q9s8hesxs85897c7a9gmea7ay",
            "status": "Active",
            "processor": "AffiniPay"
        }
    ]
}

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

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

{
    "statusCode": 400,
    "message": "Credentials already exist for this connection.  Please update via Dashboard",
    "error": "Bad Request"
}

Updating Existing Credentials via API

In certain circumstances, it may be necessary to update a merchant's existing credentials (as an example, the merchant is acquired by another business or there is a need to rotate secret keys).

In order to protect merchants and platforms, when updating a merchant that has existing connection credentials it's necessary to pass both the original credentials as well as the new credentials in the API request.

To perform this update, use the same Update Connection Details endpoint, but modify the request to include the existing credentials in the existingCredentialsobject. Here is an example:

PATCH https://api.preczn.com/v1/merchants/{merchantId}/connection/{connectionID}

{
  "secret": "new_xFPtMdvOmWOb9xBHzS4Kde6ZMvR6GrIa",
  "existingCredentials": {
    "secret": "old_xFPtMdvOmWOb9xBHzS4Kde6ZMvR6GrIa"
  }
}

Preczn will verify both that the existing credentials match, as well as validate that the new credentials are valid with the connection. If either fails, Preczn will return an error and keep the existing credentials.

{
    "id": "mid_test_2f428vcgdf94kv6y7rjwms59hf",
    "active": false,
    "plan": "",
    "name": "Bobby's Ecommerce Shop",
    "legalName": "Bobby's Ecommerce Shop",
    "address": {
        "address": "Api Address 1",
        "address2": "Api Address 2",
        "city": "San Francisco",
        "region": "CA",
        "postal": "12345",
        "country": "USA"
    },
    "email": "[email protected]",
    "phone": "12223334444",
    "tin": "****6789",
    "tinType": "ein",
    "website": "https://www.bobbyshop.com",
    "mailingAddress": {
        "address": "Api Mailing Address 1",
        "address2": "Api Mailing Address 2",
        "city": "San Francisco",
        "region": "CA",
        "postal": "93000",
        "country": "USA"
    },
    "billingContact": {
        "address": "",
        "address2": "",
        "city": "",
        "region": "",
        "postal": "",
        "country": "",
        "firstName": "Jack",
        "lastName": "Harbor",
        "email": "",
        "phone": "12223334444"
    },
    "businessType": "corp",
    "publicCompany": false,
    "isBusinessAddress": true,
    "industry": "7371",
    "stateIncorporated": "CA",
    "dateEstablished": "1990-10-22",
    "customerServicePhone": "12223334444",
    "productServiceDescription": "Excellent Products and More",
    "mcc": "5734",
    "createdOn": "2024-02-09T03:48:38Z",
    "modifiedOn": "2024-02-09T04:06:17Z",
    "modifiedBy": "API Key: Default",
    "createdBy": "API Key: Default",
    "annualSaleVolume": 20000,
    "averageTicket": 3000,
    "shipToDays": 7,
    "owners": [],
    "banking": [],
    "connections": [
        {
            "id": "midCon_test_5q9s8hesxs85897c7a9gmea7ay",
            "status": "Active",
            "processor": "AffiniPay"
        }
    ]
}

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

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