Set Linked Banking Profile by Merchant Profile ID

This endpoint links a Netevia banking profile to a merchant profile, associating the two records within the platform. Once linked, the banking profile and merchant profile share integrated financial management, enabling streamlined transactions and consolidated account operations. This is typically used during merchant onboarding or when a merchant account needs to be connected to an existing banking profile.

Endpoint

POST /netevia/profile/{profileId}/{merchantProfileId}

Authentication

Bearer token required. Obtain via:

POST https://api.banking.netevia.dev/api/auth/v2

Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.

When to use

Use this endpoint when onboarding a merchant who already has a Netevia banking profile, or when you need to associate an existing banking profile with a new or existing merchant profile. This linkage enables the merchant to manage banking operations and financial accounts in conjunction with their merchant account. It is also appropriate when re-linking profiles after a merchant profile update or migration.

Path Parameters

Parameter	Type	Required	Description
profileId	integer (int32)	Yes	The unique identifier of the Netevia banking profile to link.
merchantProfileId	integer (int32)	Yes	The unique identifier of the merchant profile to associate with the banking profile.

Query Parameters

Parameter	Type	Required	Description
risk	boolean	No	Flag indicating whether the profile should be evaluated or flagged for risk assessment during linking.
isNew	boolean	No	Indicates whether this is a new profile association. When `true`, the system may treat the link as a first-time association rather than an update.

Response

200 OK

Field	Type	Description
id	integer	Internal record ID of the primary profile.
createdDate	string (date-time)	Timestamp when the profile record was created.
updatedDate	string (date-time)	Timestamp of the last update to the profile record. Null if never updated.
userProfileId	integer	ID of the user profile associated with this primary profile.
step	integer	Current onboarding step of the profile (enum: 0–4).
accountHolderInformation	object	Personal information of the account holder (for personal profiles). See fields below.
accountHolderInformation.id	integer	Internal ID of the personal information record.
accountHolderInformation.createdDate	string (date-time)	Creation timestamp of the personal information record.
accountHolderInformation.updatedDate	string (date-time)	Last update timestamp. Nullable.
accountHolderInformation.email	string	Account holder email address.
accountHolderInformation.givenName	string	Account holder first name.
accountHolderInformation.familyName	string	Account holder last name.
accountHolderInformation.middleName	string	Account holder middle name. Nullable.
accountHolderInformation.phone	string	Account holder phone number.
accountHolderInformation.ssn	string	Account holder SSN (returned masked as `XXX-XX-XXXX`).
accountHolderInformation.dateOfBirth	string (date-time)	Account holder date of birth.
accountHolderInformation.streetAddress	string	Street address (read-only).
accountHolderInformation.extendedAddress	string	Extended address line (read-only).
accountHolderInformation.postalCode	string	Postal/ZIP code (read-only).
accountHolderInformation.locality	string	City or locality (read-only).
accountHolderInformation.state	integer	US state enum (1–53).
accountHolderInformation.countryCodeAlpha3	string	ISO 3166-1 alpha-3 country code (read-only).
businessAccountHolder	object	Business account holder information (for business profiles). Contains business and primary authorized person details.
businessAccountHolder.email	string	Email of the primary authorized person.
businessAccountHolder.givenName	string	First name of the primary authorized person.
businessAccountHolder.familyName	string	Last name of the primary authorized person.
businessAccountHolder.middleName	string	Middle name of the primary authorized person.
businessAccountHolder.phone	string	Phone number of the primary authorized person.
businessAccountHolder.ssn	string	SSN of the primary authorized person (returned masked).
businessAccountHolder.dateOfBirth	string (date-time)	Date of birth of the primary authorized person.
businessAccountHolder.legalBusinessName	string	Legal name of the business.
businessAccountHolder.doingBusinessAsName	string	DBA name of the business.
businessAccountHolder.website	string	Business website URL.
businessAccountHolder.businessType	integer	Business type enum (0–4).
businessAccountHolder.businessPhone	string	Business phone number.
businessAccountHolder.employerIdentificationNumber	string	Business EIN.
businessAccountHolder.percentageOwnership	integer	Ownership percentage of the primary authorized person.
businessAccountHolder.authorizingPersonTitle	integer	Title of the authorizing person (enum: 0–6).
businessAccountHolder.primaryAuthorizedPersonId	string	External identifier for the primary authorized person.
businessAccountHolder.businessStartDate	string (date-time)	Date the business was established.
businessAccountHolder.annualBusinessRevenue	integer (int64)	Annual revenue of the business in cents.
businessAccountHolder.payrollCustomer	boolean	Whether the business is a payroll customer.
businessAccountHolder.owners	array	List of additional business owners. Each owner includes: `businessAccountId`, `givenName`, `familyName`, `middleName`, `email`, `dateOfBirth`, `percentageOwnership`, `phoneNumber`, `ssn`, `streetAddress`, `extendedAddress`, `postalCode`, `locality`, `state`, `countryCodeAlpha3`, `ownerType`.
businessAccountHolder.merchantProfileId	integer	The merchant profile ID linked to this business account holder.
isSubmitted	boolean	Whether the banking application has been submitted. Nullable.
accountHolderId	string	External account holder identifier.
nickName	string	Display nickname for the profile.
cardProductId	string	ID of the card product associated with this profile.
openApplicationId	string	ID of the open banking application.
financialAccountId	string	ID of the associated financial account.
applicationStatus	integer	Numeric application status (enum: 0–4).
bankingStatus	string	String-based banking application status. One of: `New`, `Submitted`, `PendingUW`, `ApprovedUW`, `Closed`, `Cancelled`, `Pending_Review`, `Denied`, `Approved`, `Pending`, `InReview`, `AutoApprovedUW`.
applicationDate	string (date-time)	Date the application was created.
approvalDate	string (date-time)	Date the application was approved.
isDeleted	boolean	Whether the profile has been soft-deleted.
isLocked	boolean	Whether the profile is locked.
isAccessLocked	boolean	Whether login access is locked (e.g., after multiple failed login attempts).
isMfaEnabled	boolean	Whether multi-factor authentication is enabled.
isOtpEnabled	boolean	Whether one-time password authentication is enabled.
agentPayoutProfileId	integer	ID of the associated agent payout profile. Nullable.
salesRepresentativeId	integer	ID of the associated sales representative. Nullable.
rewordType	integer	Reward type enum (1, 2, or 4).
isNew	boolean	Whether this is a new profile. Nullable.
isExceptional	boolean	Whether the profile is flagged as exceptional. Nullable.
profileSettings	object	Profile-level settings including financial account limits and transfer limits.
profileSettings.financialAccountsPermissions.financialAccountsMaxNumber	integer	Maximum number of financial accounts allowed.
profileSettings.financialAccountsPermissions.externalAccountsMaxNumber	integer	Maximum number of external accounts allowed.
profileSettings.transferAmountLimits.achOutTransferAmountLimit	integer (int64)	ACH outbound transfer limit in cents. Nullable.
profileSettings.transferAmountLimits.internalTransferAmountLimit	integer (int64)	Internal transfer limit in cents. Nullable.
profileSettings.loanOff	boolean	Whether loan features are disabled for this profile.
applicationCreationType	string	How the banking application was created. One of: `MobileApplication`, `OnlineBankingApplication`, `OnlineMerchantApplication`, `NeteviaBoardingApplication`, `BankingAPI`, `NeteviaAPI`.
exceptionalTemplateId	integer	ID of the exceptional template applied to this profile. Nullable.
profileType	integer	Profile type enum (0–3).
accountType	integer	Account type enum (1–5).
employer	object	Employer profile linked via EWA. Includes `id`, `name`, `enabled`, `date`.
lockFinancialAccountId	string	ID of the financial account used as a lock account. Nullable.
agreements	array	List of agreements accepted by the account holder. Each includes `name`, `createdDate`, `acceptanceDate`.

{
  "id": 10045,
  "createdDate": "2025-03-10T08:30:00Z",
  "updatedDate": "2025-11-15T14:22:00Z",
  "userProfileId": 3301,
  "step": 3,
  "accountHolderInformation": null,
  "businessAccountHolder": {
    "id": 8821,
    "createdDate": "2025-03-10T08:30:00Z",
    "updatedDate": "2025-11-15T14:22:00Z",
    "email": "[email protected]",
    "givenName": "Jane",
    "familyName": "Smith",
    "middleName": null,
    "phone": "5125550100",
    "ssn": "XXX-XX-XXXX",
    "dateOfBirth": "1980-06-15T00:00:00Z",
    "streetAddress": "456 Commerce Blvd",
    "extendedAddress": "Suite 200",
    "postalCode": "78701",
    "locality": "Austin",
    "state": 43,
    "countryCodeAlpha3": "USA",
    "percentageOwnership": 100,
    "authorizingPersonTitle": 2,
    "legalBusinessName": "Acme Corp LLC",
    "doingBusinessAsName": "Acme Corp",
    "website": "https://acmecorp.com",
    "businessType": 1,
    "businessPhone": "5125550200",
    "employerIdentificationNumber": "12-3456789",
    "primaryAuthorizedPersonId": "auth-person-abc123",
    "businessStartDate": "2018-01-01T00:00:00Z",
    "annualBusinessRevenue": 500000000,
    "payrollCustomer": false,
    "owners": [],
    "merchantProfileId": 7712
  },
  "isSubmitted": true,
  "accountHolderId": "acct-holder-xyz789",
  "nickName": "Acme Main",
  "cardProductId": "card-prod-001",
  "openApplicationId": "app-open-55432",
  "financialAccountId": "fin-acct-998877",
  "applicationStatus": 2,
  "bankingStatus": "Approved",
  "applicationDate": "2025-03-10T08:30:00Z",
  "approvalDate": "2025-03-12T11:00:00Z",
  "isDeleted": false,
  "isLocked": false,
  "isAccessLocked": false,
  "isMfaEnabled": true,
  "isOtpEnabled": false,
  "agentPayoutProfileId": null,
  "salesRepresentativeId": 501,
  "rewordType": 1,
  "isNew": false,
  "isExceptional": false,
  "profileSettings": {
    "financialAccountsPermissions": {
      "financialAccountsMaxNumber": 5,
      "externalAccountsMaxNumber": 3
    },
    "transferAmountLimits": {
      "achOutTransferAmountLimit": 1000000,
      "internalTransferAmountLimit": 500000
    },
    "loanOff": false
  },
  "applicationCreationType": "NeteviaBoardingApplication",
  "exceptionalTemplateId": null,
  "profileType": 1,
  "accountType": 2,
  "employer": null,
  "lockFinancialAccountId": null,
  "agreements": [
    {
      "name": "Terms of Service",
      "createdDate": "2025-03-10T08:30:00Z",
      "acceptanceDate": "2025-03-10T08:35:00Z"
    }
  ]
}

Error Codes

Code	When it happens
400	Missing required path parameters or invalid integer format for `profileId` or `merchantProfileId`
401	Token missing, expired, or invalid
403	Insufficient permissions to link the specified profiles
404	The specified `profileId` or `merchantProfileId` does not exist
500	Internal server error

Common Mistakes

Passing profileId or merchantProfileId as strings instead of integers — both path parameters must be valid 32-bit integers.
Omitting the Authorization: Bearer header or using an expired token, resulting in a 401 error.
Attempting to link profiles that belong to different partners — ensure both the banking profile and merchant profile are within the same partner scope.
Confusing profileId (banking profile) with merchantProfileId (merchant system profile) — they are distinct identifiers and must be passed in the correct path positions.
Not checking bankingStatus in the response — a status of Denied or Closed may indicate the link succeeded at the data level but the account is not in an active state.

Related Endpoints

GET /netevia/profile/{profileId} — Retrieve details of an existing banking profile by its ID
POST /netevia/profile — Create a new Netevia banking profile
PUT /netevia/profile/{profileId} — Update an existing banking profile
GET /netevia/profile/{profileId}/{merchantProfileId} — Retrieve the linked banking profile for a given merchant profile ID

Example

curl -X POST https://api.banking.netevia.dev/netevia/profile/10045/7712 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

To include optional query parameters:

curl -X POST "https://api.banking.netevia.dev/netevia/profile/10045/7712?risk=false&isNew=false" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"