---
updatedAt: 2026-07-16T19:00:35.000Z
agentTools:
projectIndex: https://docs.preczn.com/llms.txt
---
# Add Merchant Bank Account
# OpenAPI definition
```json
{
"openapi": "3.0.0",
"info": {
"title": "Preczn API",
"version": "1.0",
"contact": {}
},
"servers": [
{
"url": "https://api.preczn.com"
}
],
"paths": {
"/v1/merchants/{merchantId}/bankaccounts": {
"post": {
"operationId": "addMerchantBank",
"parameters": [
{
"name": "merchantId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "idempotency-key",
"in": "header",
"description": "Unique key to ensure idempotency of requests. If provided, the server will return the same response for subsequent requests with the same key.",
"required": false,
"schema": {
"type": "string",
"example": "123e4567-e89b-12d3-a456-426614174000"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Banking"
}
}
}
},
"responses": {
"201": {
"description": "Bank Account Created for Merchant.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MerchantOut"
}
}
}
},
"401": {
"description": "Invalid API key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"403": {
"description": "Resource Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"404": {
"description": "Merchant not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"500": {
"description": "Unable to service request due to server-side error. Please reattempt request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
}
},
"security": [
{
"apiKey": []
}
],
"summary": "Add Merchant Bank Account",
"tags": [
"Merchant Vault"
]
}
}
},
"components": {
"schemas": {
"Address1": {
"type": "object",
"properties": {
"address": {
"type": "string",
"example": "123 Drive Way",
"description": "Address line 1. Content is currently unrestricted (reserved for future tightening)."
},
"address2": {
"type": "string",
"example": "Unit 2",
"description": "Address line 2. Content is currently unrestricted (reserved for future tightening)."
},
"city": {
"type": "string",
"example": "New York City",
"description": "City. Content is currently unrestricted (reserved for future tightening)."
},
"region": {
"type": "string",
"example": "NY",
"description": "State or province code in 2-character abbreviation (e.g., CA, NC). The set of valid codes depends on the sibling country field: US state codes when country is USA (the default), Canadian province codes when country is CAN."
},
"postal": {
"type": "string",
"example": "10001",
"description": "Postal or ZIP code, validated against the sibling country field. USA (the default): 12345 or 12345-6789. CAN: A1A 1A1 (space optional). Whitespace is stripped before validation; empty values are not validated."
},
"country": {
"type": "string",
"example": "USA",
"enum": [
"AFG",
"ALB",
"DZA",
"ASM",
"AND",
"AGO",
"AIA",
"ATA",
"ATG",
"ARG",
"ARM",
"ABW",
"AUS",
"AUT",
"AZE",
"BHS",
"BHR",
"BGD",
"BRB",
"BLR",
"BEL",
"BLZ",
"BEN",
"BMU",
"BTN",
"BOL",
"BES",
"BIH",
"BWA",
"BVT",
"BRA",
"IOT",
"BRN",
"BGR",
"BFA",
"BDI",
"CPV",
"KHM",
"CMR",
"CAN",
"CYM",
"CAF",
"TCD",
"CHL",
"CHN",
"CXR",
"CCK",
"COL",
"COM",
"COD",
"COG",
"COK",
"CRI",
"HRV",
"CUB",
"CUW",
"CYP",
"CZE",
"CIV",
"DNK",
"DJI",
"DMA",
"DOM",
"ECU",
"EGY",
"SLV",
"GNQ",
"ERI",
"EST",
"SWZ",
"ETH",
"FLK",
"FRO",
"FJI",
"FIN",
"FRA",
"GUF",
"PYF",
"ATF",
"GAB",
"GMB",
"GEO",
"DEU",
"GHA",
"GIB",
"GRC",
"GRL",
"GRD",
"GLP",
"GUM",
"GTM",
"GGY",
"GIN",
"GNB",
"GUY",
"HTI",
"HMD",
"VAT",
"HND",
"HKG",
"HUN",
"ISL",
"IND",
"IDN",
"IRN",
"IRQ",
"IRL",
"IMN",
"ISR",
"ITA",
"JAM",
"JPN",
"JEY",
"JOR",
"KAZ",
"KEN",
"KIR",
"PRK",
"KOR",
"KWT",
"KGZ",
"LAO",
"LVA",
"LBN",
"LSO",
"LBR",
"LBY",
"LIE",
"LTU",
"LUX",
"MAC",
"MDG",
"MWI",
"MYS",
"MDV",
"MLI",
"MLT",
"MHL",
"MTQ",
"MRT",
"MUS",
"MYT",
"MEX",
"FSM",
"MDA",
"MCO",
"MNG",
"MNE",
"MSR",
"MAR",
"MOZ",
"MMR",
"NAM",
"NRU",
"NPL",
"NLD",
"NCL",
"NZL",
"NIC",
"NER",
"NGA",
"NIU",
"NFK",
"MNP",
"NOR",
"OMN",
"PAK",
"PLW",
"PSE",
"PAN",
"PNG",
"PRY",
"PER",
"PHL",
"PCN",
"POL",
"PRT",
"PRI",
"QAT",
"MKD",
"ROU",
"RUS",
"RWA",
"REU",
"BLM",
"SHN",
"KNA",
"LCA",
"MAF",
"SPM",
"VCT",
"WSM",
"SMR",
"STP",
"SAU",
"SEN",
"SRB",
"SYC",
"SLE",
"SGP",
"SXM",
"SVK",
"SVN",
"SLB",
"SOM",
"ZAF",
"SGS",
"SSD",
"ESP",
"LKA",
"SDN",
"SUR",
"SJM",
"SWE",
"CHE",
"SYR",
"TWN",
"TJK",
"TZA",
"THA",
"TLS",
"TGO",
"TKL",
"TON",
"TTO",
"TUN",
"TUR",
"TKM",
"TCA",
"TUV",
"UGA",
"UKR",
"ARE",
"GBR",
"UMI",
"USA",
"URY",
"UZB",
"VUT",
"VEN",
"VNM",
"VGB",
"VIR",
"WLF",
"ESH",
"YEM",
"ZMB",
"ZWE",
"ALA"
],
"description": "ISO 3166-1 alpha-3 Country Code."
}
}
},
"BillingAddress": {
"type": "object",
"properties": {
"address": {
"type": "string",
"example": "123 Drive Way",
"description": "Address line 1. Content is currently unrestricted (reserved for future tightening)."
},
"address2": {
"type": "string",
"example": "Unit 2",
"description": "Address line 2. Content is currently unrestricted (reserved for future tightening)."
},
"city": {
"type": "string",
"example": "New York City",
"description": "City. Content is currently unrestricted (reserved for future tightening)."
},
"region": {
"type": "string",
"example": "NY",
"description": "State or province code in 2-character abbreviation (e.g., CA, NC). The set of valid codes depends on the sibling country field: US state codes when country is USA (the default), Canadian province codes when country is CAN."
},
"postal": {
"type": "string",
"example": "10001",
"description": "Postal or ZIP code, validated against the sibling country field. USA (the default): 12345 or 12345-6789. CAN: A1A 1A1 (space optional). Whitespace is stripped before validation; empty values are not validated."
},
"country": {
"type": "string",
"example": "USA",
"enum": [
"AFG",
"ALB",
"DZA",
"ASM",
"AND",
"AGO",
"AIA",
"ATA",
"ATG",
"ARG",
"ARM",
"ABW",
"AUS",
"AUT",
"AZE",
"BHS",
"BHR",
"BGD",
"BRB",
"BLR",
"BEL",
"BLZ",
"BEN",
"BMU",
"BTN",
"BOL",
"BES",
"BIH",
"BWA",
"BVT",
"BRA",
"IOT",
"BRN",
"BGR",
"BFA",
"BDI",
"CPV",
"KHM",
"CMR",
"CAN",
"CYM",
"CAF",
"TCD",
"CHL",
"CHN",
"CXR",
"CCK",
"COL",
"COM",
"COD",
"COG",
"COK",
"CRI",
"HRV",
"CUB",
"CUW",
"CYP",
"CZE",
"CIV",
"DNK",
"DJI",
"DMA",
"DOM",
"ECU",
"EGY",
"SLV",
"GNQ",
"ERI",
"EST",
"SWZ",
"ETH",
"FLK",
"FRO",
"FJI",
"FIN",
"FRA",
"GUF",
"PYF",
"ATF",
"GAB",
"GMB",
"GEO",
"DEU",
"GHA",
"GIB",
"GRC",
"GRL",
"GRD",
"GLP",
"GUM",
"GTM",
"GGY",
"GIN",
"GNB",
"GUY",
"HTI",
"HMD",
"VAT",
"HND",
"HKG",
"HUN",
"ISL",
"IND",
"IDN",
"IRN",
"IRQ",
"IRL",
"IMN",
"ISR",
"ITA",
"JAM",
"JPN",
"JEY",
"JOR",
"KAZ",
"KEN",
"KIR",
"PRK",
"KOR",
"KWT",
"KGZ",
"LAO",
"LVA",
"LBN",
"LSO",
"LBR",
"LBY",
"LIE",
"LTU",
"LUX",
"MAC",
"MDG",
"MWI",
"MYS",
"MDV",
"MLI",
"MLT",
"MHL",
"MTQ",
"MRT",
"MUS",
"MYT",
"MEX",
"FSM",
"MDA",
"MCO",
"MNG",
"MNE",
"MSR",
"MAR",
"MOZ",
"MMR",
"NAM",
"NRU",
"NPL",
"NLD",
"NCL",
"NZL",
"NIC",
"NER",
"NGA",
"NIU",
"NFK",
"MNP",
"NOR",
"OMN",
"PAK",
"PLW",
"PSE",
"PAN",
"PNG",
"PRY",
"PER",
"PHL",
"PCN",
"POL",
"PRT",
"PRI",
"QAT",
"MKD",
"ROU",
"RUS",
"RWA",
"REU",
"BLM",
"SHN",
"KNA",
"LCA",
"MAF",
"SPM",
"VCT",
"WSM",
"SMR",
"STP",
"SAU",
"SEN",
"SRB",
"SYC",
"SLE",
"SGP",
"SXM",
"SVK",
"SVN",
"SLB",
"SOM",
"ZAF",
"SGS",
"SSD",
"ESP",
"LKA",
"SDN",
"SUR",
"SJM",
"SWE",
"CHE",
"SYR",
"TWN",
"TJK",
"TZA",
"THA",
"TLS",
"TGO",
"TKL",
"TON",
"TTO",
"TUN",
"TUR",
"TKM",
"TCA",
"TUV",
"UGA",
"UKR",
"ARE",
"GBR",
"UMI",
"USA",
"URY",
"UZB",
"VUT",
"VEN",
"VNM",
"VGB",
"VIR",
"WLF",
"ESH",
"YEM",
"ZMB",
"ZWE",
"ALA"
],
"description": "ISO 3166-1 alpha-3 Country Code."
},
"firstName": {
"type": "string",
"example": "Bob",
"description": "Contact First Name.",
"pattern": "^[a-z ,.'-]*$"
},
"lastName": {
"type": "string",
"example": "White",
"description": "Contact Last Name.",
"pattern": "^[a-z ,.'-]*$"
},
"email": {
"type": "string",
"example": "email@preczn.com",
"description": "Contact Email.",
"format": "email"
},
"phone": {
"type": "string",
"example": "19999999999",
"description": "Contact phone number. Validated only when a non-empty value is provided. Format: North American phone digits only, optionally prefixed with '1'. No spaces, parentheses, or hyphens. Example: 19999999999."
}
}
},
"Owner": {
"type": "object",
"properties": {
"firstName": {
"type": "string",
"example": "Sam",
"description": "First name.",
"pattern": "^[a-z ,.'-]*$"
},
"middleName": {
"type": "string",
"example": "David",
"description": "Middle name.",
"pattern": "^[a-z ,.'-]*$"
},
"lastName": {
"type": "string",
"example": "Samson",
"description": "Last name.",
"pattern": "^[a-z ,.'-]*$"
},
"email": {
"type": "string",
"example": "contact@example.com",
"description": "Email address."
},
"phone": {
"type": "string",
"example": "19999999999",
"description": "Phone number. Format: North American phone digits only, optionally prefixed with '1'. No spaces, parentheses, or hyphens. Example: 19999999999.",
"pattern": "^1?\\d{10}$"
},
"address": {
"description": "Address of the contact",
"allOf": [
{
"$ref": "#/components/schemas/Address1"
}
]
},
"businessTitle": {
"type": "string",
"example": "CFO",
"description": "Business Title.",
"pattern": "^[a-z ,.'-]*$"
},
"citizenshipCountry": {
"type": "string",
"example": "USA",
"enum": [
"AFG",
"ALB",
"DZA",
"ASM",
"AND",
"AGO",
"AIA",
"ATA",
"ATG",
"ARG",
"ARM",
"ABW",
"AUS",
"AUT",
"AZE",
"BHS",
"BHR",
"BGD",
"BRB",
"BLR",
"BEL",
"BLZ",
"BEN",
"BMU",
"BTN",
"BOL",
"BES",
"BIH",
"BWA",
"BVT",
"BRA",
"IOT",
"BRN",
"BGR",
"BFA",
"BDI",
"CPV",
"KHM",
"CMR",
"CAN",
"CYM",
"CAF",
"TCD",
"CHL",
"CHN",
"CXR",
"CCK",
"COL",
"COM",
"COD",
"COG",
"COK",
"CRI",
"HRV",
"CUB",
"CUW",
"CYP",
"CZE",
"CIV",
"DNK",
"DJI",
"DMA",
"DOM",
"ECU",
"EGY",
"SLV",
"GNQ",
"ERI",
"EST",
"SWZ",
"ETH",
"FLK",
"FRO",
"FJI",
"FIN",
"FRA",
"GUF",
"PYF",
"ATF",
"GAB",
"GMB",
"GEO",
"DEU",
"GHA",
"GIB",
"GRC",
"GRL",
"GRD",
"GLP",
"GUM",
"GTM",
"GGY",
"GIN",
"GNB",
"GUY",
"HTI",
"HMD",
"VAT",
"HND",
"HKG",
"HUN",
"ISL",
"IND",
"IDN",
"IRN",
"IRQ",
"IRL",
"IMN",
"ISR",
"ITA",
"JAM",
"JPN",
"JEY",
"JOR",
"KAZ",
"KEN",
"KIR",
"PRK",
"KOR",
"KWT",
"KGZ",
"LAO",
"LVA",
"LBN",
"LSO",
"LBR",
"LBY",
"LIE",
"LTU",
"LUX",
"MAC",
"MDG",
"MWI",
"MYS",
"MDV",
"MLI",
"MLT",
"MHL",
"MTQ",
"MRT",
"MUS",
"MYT",
"MEX",
"FSM",
"MDA",
"MCO",
"MNG",
"MNE",
"MSR",
"MAR",
"MOZ",
"MMR",
"NAM",
"NRU",
"NPL",
"NLD",
"NCL",
"NZL",
"NIC",
"NER",
"NGA",
"NIU",
"NFK",
"MNP",
"NOR",
"OMN",
"PAK",
"PLW",
"PSE",
"PAN",
"PNG",
"PRY",
"PER",
"PHL",
"PCN",
"POL",
"PRT",
"PRI",
"QAT",
"MKD",
"ROU",
"RUS",
"RWA",
"REU",
"BLM",
"SHN",
"KNA",
"LCA",
"MAF",
"SPM",
"VCT",
"WSM",
"SMR",
"STP",
"SAU",
"SEN",
"SRB",
"SYC",
"SLE",
"SGP",
"SXM",
"SVK",
"SVN",
"SLB",
"SOM",
"ZAF",
"SGS",
"SSD",
"ESP",
"LKA",
"SDN",
"SUR",
"SJM",
"SWE",
"CHE",
"SYR",
"TWN",
"TJK",
"TZA",
"THA",
"TLS",
"TGO",
"TKL",
"TON",
"TTO",
"TUN",
"TUR",
"TKM",
"TCA",
"TUV",
"UGA",
"UKR",
"ARE",
"GBR",
"UMI",
"USA",
"URY",
"UZB",
"VUT",
"VEN",
"VNM",
"VGB",
"VIR",
"WLF",
"ESH",
"YEM",
"ZMB",
"ZWE",
"ALA"
],
"description": "ISO 3166-1 alpha-3 country code (e.g., USA). Membership in the ISO-3 list is currently not enforced by validation (reserved for future tightening)."
},
"ownershipDate": {
"type": "string",
"example": "1990-01-20",
"description": "Date when an owner became an owner. ISO 8601 date, YYYY-MM-DD.",
"pattern": "^(?:\\d{4})[-/](?:0[1-9]|1[0-2])[-/](?:0[1-9]|[12][0-9]|3[01])$"
},
"dob": {
"type": "string",
"example": "1970-01-01",
"description": "Date of birth. ISO 8601 date, YYYY-MM-DD. The format is currently not enforced by validation (reserved for future tightening). Responses return a masked value: the birth year followed by **** (e.g., 1970****)."
},
"ssn": {
"type": "string",
"example": "555555555",
"description": "Social security number. 9 digits, no hyphens or spaces. Responses return a masked value: **** followed by the last 4 digits (e.g., ****5555); the field is omitted when no SSN is on file.",
"maxLength": 9,
"minLength": 9,
"pattern": "^(\\d{9})?$"
},
"ssnLast4": {
"type": "string",
"example": "5555",
"description": "Last 4 digits of the social security number. Exactly 4 digits. When ssn is also provided in the same request, this value must match the last 4 digits of ssn.",
"minLength": 4,
"maxLength": 4,
"pattern": "^(\\d{4})?$"
},
"ownershipPercent": {
"type": "number",
"example": 85,
"description": "Percentage of ownership as a whole integer, expected range 0 to 100 (e.g., 85). The range and integer form are currently not enforced by validation (reserved for future tightening)."
},
"type": {
"type": "string",
"example": "Director",
"description": "Owner type",
"enum": [
"Director",
"Executive",
"Owner"
]
},
"politicallyExposed": {
"type": "boolean",
"default": false,
"example": false,
"description": "Publically exposed owner flag."
},
"primaryRepresentative": {
"type": "boolean",
"default": false,
"example": false,
"description": "Sponsoring stakeholder from the merchant.",
"enum": [
true
]
},
"driversLicenseNumber": {
"type": "string",
"example": "D12345678910",
"description": "Driver's license number. Alphanumeric characters only; must not be an empty string. Responses return a masked value: **** followed by the last 4 characters.",
"minLength": 1,
"pattern": "^[a-zA-Z0-9]*$"
},
"driversLicenseState": {
"type": "string",
"example": "NY",
"description": "State or province code where the driver's license was issued, in 2-character abbreviation (e.g., NY). The set of valid codes depends on the sibling address.country field: US state codes when country is USA (the default), Canadian province codes when country is CAN.",
"minLength": 1
},
"driversLicenseExpiration": {
"type": "string",
"example": "2035-01-01",
"description": "Driver's license expiration date. ISO 8601 date, YYYY-MM-DD.",
"minLength": 1,
"pattern": "^(?:\\d{4})[-/](?:0[1-9]|1[0-2])[-/](?:0[1-9]|[12][0-9]|3[01])$"
},
"significantResponsibility": {
"type": "boolean",
"example": true,
"default": true,
"description": "Significant Responsibility."
}
}
},
"Banking": {
"type": "object",
"properties": {
"accountName": {
"type": "string",
"example": "WellsFargo",
"description": "Name of bank associated with the bank account.",
"pattern": "^[a-zA-Z0-9\\s]*$"
},
"accountType": {
"type": "string",
"example": "personalChecking",
"enum": [
"personalChecking",
"personalSavings",
"corporateChecking",
"corporateSavings"
],
"description": "Bank account type. One of personalChecking, personalSavings, corporateChecking, or corporateSavings."
},
"nameOnAccount": {
"type": "string",
"example": "John Smith",
"description": "Name of the person or corporation that is on the account. Must match what is displayed on checks.",
"pattern": "^[a-zA-Z0-9\\s]*$"
},
"routing": {
"type": "string",
"example": "011000015",
"description": "Bank routing number, validated against the sibling country field. USA: exactly 9 digits with a valid ABA checksum. CAN: exactly 8 digits. When country is omitted, only the 8-or-9-digit length check applies. Empty values are not validated. Responses return a masked value: **** followed by the last 4 digits."
},
"account": {
"type": "string",
"example": "1234567890",
"maxLength": 17,
"description": "Bank account number. Digits only, up to 17 characters; no spaces, hyphens, or decimal points. Responses return a masked value: **** followed by the last 4 digits.",
"pattern": "^[+-]?([0-9]*[.])?[0-9]+$"
},
"primaryAccount": {
"type": "boolean",
"example": true,
"default": true,
"description": "Flag that distinguishes this bank account as the primary account. Only the value true is accepted; sending false is rejected, so an account is demoted by designating a different account as primary instead. At least one account must be designated as the primary account, and there should be only one primary account — that uniqueness is not enforced by request validation.",
"enum": [
true
]
},
"country": {
"type": "string",
"example": "USA",
"enum": [
"USA",
"CAN"
],
"description": "ISO 3166-1 alpha-3 Country Code.",
"pattern": "^[A-Z]{3}$",
"minLength": 1
},
"hasDisbursementHistory": {
"type": "boolean",
"example": true,
"default": true,
"description": "This field indicates whether the bank account has a history of receiving disbursements or payouts from payment processors. It can be utilized during the onboarding process for certain connections to enhance the underwriting procedure.",
"enum": [
true,
false
]
}
}
},
"SaasDataBilling": {
"type": "object",
"properties": {
"amount": {
"type": "number",
"example": 1000,
"description": "Amount the merchant is billed for vertical saas service."
},
"frequency": {
"type": "string",
"enum": [
"ONE_TIME",
"WEEKLY",
"MONTHLY",
"ANNUAL",
"OTHER"
],
"example": "MONTHLY",
"description": " Frequency at which the merchant is billed for vertical saas service. Enumerations of: ONE_TIME, WEEKLY, MONTHLY, ANNUAL, OTHER"
},
"currency": {
"type": "string",
"enum": [
"USD"
],
"example": "USD",
"description": "Currency in which the merchant is billed for vertical saas service. Enumeration: Only support USD."
}
}
},
"SaasData": {
"type": "object",
"properties": {
"startDate": {
"type": "string",
"example": "2025-03-17T19:46:45Z",
"description": "ISO 8601 formatted Date when the merchant started using the vertical saas platform."
},
"billing": {
"description": "Billing configuration for the vertical SaaS service, including amount, frequency, and currency.",
"example": {
"amount": 1000,
"frequency": "MONTHLY",
"currency": "USD"
},
"allOf": [
{
"$ref": "#/components/schemas/SaasDataBilling"
}
]
}
}
},
"PaymentMethod1": {
"type": "object",
"properties": {
"last30Days": {
"type": "integer",
"example": 1000,
"description": "Transaction volume in the last 30 days"
},
"last180Days": {
"type": "integer",
"example": 1000,
"description": "Transaction volume in the last 180 days"
}
}
},
"TransactionVolumeSnapshot": {
"type": "object",
"properties": {
"volumeAsOfDate": {
"type": "string",
"example": "2025-03-17T19:46:45Z",
"description": "ISO 8601 formatted Date when the transaction volume snapshot was last updated."
},
"allPaymentMethods": {
"description": "Aggregated transaction volume across all payment methods, including 30-day and 180-day totals.",
"example": {
"last30Days": 1000,
"last180Days": 5000
},
"allOf": [
{
"$ref": "#/components/schemas/PaymentMethod1"
}
]
}
}
},
"GooglePaySettings": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"example": true,
"description": "Enable or disable Google Pay for this merchant. When enabled, customers can pay using Google Pay wallet. Set to false to disable Google Pay for customer transactions."
}
}
},
"ApplePaySettings": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"example": true,
"description": "Enable or disable Apple Pay for this merchant. When enabled, customers can pay using Apple Pay wallet from Safari or Apple devices. Defaults to true if not specified."
}
}
},
"MerchantWalletSettings": {
"type": "object",
"properties": {
"googlePay": {
"description": "Google Pay configuration for this merchant. Enable or disable Google Pay wallet payments.",
"example": {
"enabled": true
},
"allOf": [
{
"$ref": "#/components/schemas/GooglePaySettings"
}
]
},
"applePay": {
"description": "Apple Pay configuration for this merchant. Enable or disable Apple Pay wallet payments for customers using Apple devices.",
"example": {
"enabled": true
},
"allOf": [
{
"$ref": "#/components/schemas/ApplePaySettings"
}
]
}
}
},
"SaqOut": {
"type": "object",
"properties": {
"lastSignedSAQ": {
"type": "string",
"example": "saq_57jaev7pna8nftrkr6xksaastw",
"description": "The ID of the last signed SAQ"
},
"lastSignedSAQExpiresOn": {
"type": "string",
"example": "2023-11-1:10:00",
"description": "The timestamp that the last SAQ expires on "
},
"ids": {
"type": "string",
"example": "[saq_1231313a, saq_231q121]",
"description": "The Ids of the created saqs."
}
}
},
"SigningContact": {
"type": "object",
"properties": {
"firstName": {
"type": "string",
"maxLength": 255,
"example": "Bob",
"description": "Signing contact's first name."
},
"lastName": {
"type": "string",
"maxLength": 255,
"example": "Smith",
"description": "Signing contact's last name."
},
"email": {
"type": "string",
"maxLength": 255,
"example": "bob.smith@gmail.com",
"description": "Signing contact's email.",
"format": "email"
},
"title": {
"type": "string",
"maxLength": 255,
"example": "CEO",
"description": "Signing contact's job title."
},
"phone": {
"type": "string",
"maxLength": 14,
"example": "+14155550188",
"description": "Signing contact's phone in E164 format (+1XXXXXXXXXX). Non-E164 values (e.g. \"(555) 123-4567\", bare 10-digit \"4155550188\") are rejected with HTTP 400.",
"pattern": "^\\+1\\d{10}$"
}
}
},
"NewUserLoginData": {
"type": "object",
"properties": {
"username": {
"type": "string",
"example": "JohnDoe86",
"description": "Username for the connection setup. Although Preczn allows alphanumeric and special characters, verify if the connection accepts only alphanumeric characters.",
"maxLength": 50
},
"firstName": {
"type": "string",
"example": "John",
"description": "First name of the user associated with the login.",
"maxLength": 50
},
"lastName": {
"type": "string",
"example": "Doe",
"description": "Last name of the user associated with the login.",
"maxLength": 50
},
"email": {
"type": "string",
"example": "johndoe@example.com",
"description": "Email address linked to user login. Used for password resets or sending invitation emails by the connection.",
"maxLength": 50,
"format": "email"
},
"connectionID": {
"type": "string",
"example": "t1_log_65dfe38079b8b79b1a24c21",
"description": "UUID provided by the connection to identify the user.",
"maxLength": 50
}
}
},
"AdyenTosDocument": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "TOS_DOC_00000001",
"minLength": 1
}
},
"required": [
"id"
]
},
"ContactRoleAssignment": {
"type": "object",
"properties": {
"subjectType": {
"type": "string",
"enum": [
"owner",
"contact"
]
},
"subjectId": {
"type": "string"
}
},
"required": [
"subjectType",
"subjectId"
]
},
"ContactRoleAssignmentsMap": {
"type": "object",
"properties": {
"account": {
"$ref": "#/components/schemas/ContactRoleAssignment"
},
"credit": {
"$ref": "#/components/schemas/ContactRoleAssignment"
},
"sales": {
"$ref": "#/components/schemas/ContactRoleAssignment"
},
"marketing": {
"$ref": "#/components/schemas/ContactRoleAssignment"
},
"applicant": {
"$ref": "#/components/schemas/ContactRoleAssignment"
}
}
},
"ConnectionSpecificRequirements": {
"type": "object",
"properties": {
"tosDate": {
"type": "string",
"example": "2024-01-31",
"description": "Date when the terms of service/conditions were signed."
},
"tosIp": {
"type": "string",
"example": "1.1.1.1",
"description": "The IP address address of the machine that approved the terms of service/conditions.",
"format": "ipv4"
},
"userAgent": {
"type": "string",
"example": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
"description": "The user agent value from the request that approved the terms of service/conditions."
},
"tosVersion": {
"type": "string",
"example": "12345",
"description": "The version number of the terms of service/conditions that was signed."
},
"tosAcceptedByOwnerId": {
"type": "string",
"example": "own_789_test_",
"description": "The ID of the merchant owner who accepted the Terms of Service. Must exist in the form's owners list. Used for AFP connections to identify the TOS signer."
},
"billingType": {
"type": "string",
"enum": [
"NET",
"GROSS"
],
"example": "GROSS",
"description": "Used to define how the merchant will be billed at the connection. Used by Rainforest"
},
"billingGroups": {
"example": [
"bpf_2DrDFJPutxE5AIbJSopAnqniEbr",
"bpf_2FRDFJPutxE5AIbJSopAnqniEbr"
],
"description": "The billing groups associated with the connection e.g Rainforest.",
"type": "array",
"items": {
"type": "string"
}
},
"customField": {
"type": "string",
"maxLength": 50,
"example": "Conversion",
"description": "This field is utilized to convey metadata to specific connections during the onboarding process.",
"minLength": 0
},
"channel": {
"type": "string",
"example": "External-API-MegaCommercePlatform",
"description": "A static value that is used by certain connections to identify the partner."
},
"presentedDisclosures": {
"type": "string",
"example": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. In dictum non consectetur a erat nam at. Blandit libero volutpat sed cras ornare arcu dui. Dictum non consectetur a erat nam at lectus urna. Auctor eu augue ut lectus arcu bibendum at varius vel. Sit amet nisl purus in mollis nunc sed id. Venenatis tellus in metus vulputate eu scelerisque felis imperdiet proin. Et magnis dis parturient montes. Sit amet tellus cras adipiscing enim eu turpis.
",
"description": "Disclosure text that was presented when terms of service/conditions was signed."
},
"blackbox": {
"type": "string",
"example": "TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZWxpdCwgc2VkIGRvIGVpdXNtb2QgdGVtcG9yIGluY2lkaWR1bnQgdXQgbGFib3JlIGV0IGRvbG9yZSBtYWduYSBhbGlxdWEuIEluIGRpY3R1bSBub24gY29uc2VjdGV0dXIgYSBlcmF0IG5hbSBhdC4gQmxhbmRpdCBsaWJlcm8gdm9sdXRwYXQgc2VkIGNyYXMgb3JuYXJlIGFyY3UgZHVpLiBEaWN0dW0gbm9uIGNvbnNlY3RldHVyIGEgZXJhdCBuYW0gYXQgbGVjdHVzIHVybmEuIEF1Y3RvciBldSBhdWd1ZSB1dCBsZWN0dXMgYXJjdSBiaWJlbmR1bSBhdCB2YXJpdXMgdmVsLiBTaXQgYW1ldCBuaXNsIHB1cnVzIGluIG1vbGxpcyBudW5jIHNlZCBpZC4gVmVuZW5hdGlzIHRlbGx1cyBpbiBtZXR1cyB2dWxwdXRhdGUgZXUgc2NlbGVyaXNxdWUgZmVsaXMgaW1wZXJkaWV0IHByb2luLiBFdCBtYWduaXMgZGlzIHBhcnR1cmllbnQgbW9udGVzLiBTaXQgYW1ldCB0ZWxsdXMgY3JhcyBhZGlwaXNjaW5nIGVuaW0gZXUgdHVycGlzLg==",
"description": "A unique anti-fraud code that is generated when terms of service/conditions was signed."
},
"signingContact": {
"description": "Information about the user that approved the boarding form last.",
"allOf": [
{
"$ref": "#/components/schemas/SigningContact"
}
]
},
"newUserLoginData": {
"description": "Data that is sent to the connection to establish the initial user login to the connection's merchant portal. Used solely to establish the first connection and do not update with user changes.",
"allOf": [
{
"$ref": "#/components/schemas/NewUserLoginData"
}
]
},
"platformConnectionId": {
"type": "string",
"example": "pfp_2DrDFJPutxE5AIbJSopAnqniEbr",
"description": "Links this merchant AFP connection to a specific platform AFP connection. Required for AdyenForPlatforms processors."
},
"adyenTosDocuments": {
"description": "Array of Adyen TOS documents to accept. Normalized from comma-separated tosVersion if not provided directly.",
"type": "array",
"items": {
"$ref": "#/components/schemas/AdyenTosDocument"
}
},
"adyenStoreId": {
"type": "string",
"example": "ST_00000001",
"description": "Adyen Store ID for the merchant connection. Distinct from Jaris shopId."
},
"adyenPaymentMethodIds": {
"example": [
"PM_00000001",
"PM_00000002"
],
"description": "Array of Adyen Payment Method IDs configured for this merchant connection.",
"type": "array",
"items": {
"type": "string"
}
},
"pciTemplateReferences": {
"example": [
"PCIT_00000001",
"PCIT_00000002"
],
"description": "Array of PCI template reference IDs to sign. Returned by the GET pci-questionnaires endpoint.",
"type": "array",
"items": {
"type": "string"
}
},
"pciSignedByOwnerId": {
"type": "string",
"example": "own_789_test_",
"description": "The ID of the merchant owner who signed the PCI questionnaire. Must exist in the form's owners list."
},
"pciQuestionnaireIds": {
"type": "string",
"example": "PCIQ_00000001,PCIQ_00000002",
"description": "Comma-separated Adyen PCI questionnaire IDs returned after signing."
},
"pciSignedDate": {
"type": "string",
"example": "2026-04-13T12:00:00.000Z",
"description": "ISO 8601 timestamp of when the PCI questionnaire was signed."
},
"greenskyPrimaryBusinessCategory": {
"type": "string",
"example": "HVAC",
"enum": [
"Awnings, Sunrooms",
"Basement - Finishing / Remodeling",
"Basement - Foundation",
"Basement - Waterproofing",
"Carports/Portable Buildings",
"Concrete / Masonry",
"Construction",
"Construction - Outdoor",
"Electrical",
"Energy Efficiency",
"Fencing",
"Fencing - Pet Containment",
"Flooring",
"Flooring - Coatings",
"General Contracting",
"Generators",
"Home Automation",
"HVAC",
"Kitchen and Bathrooms",
"Landscape/Hardscape",
"Painting",
"Pest Control",
"Plumbing",
"Pools",
"Remodeling",
"Restoration",
"Retail",
"Roofing",
"Siding / Decks",
"Solar",
"Spas and Saunas",
"Walk-In Tub",
"Water Treatment",
"Windows and Doors",
"Other"
],
"description": "The GreenSky primary business category for this merchant connection."
},
"contacts": {
"description": "Role-to-subject polymorphic refs. Each role (account, credit, sales, marketing, applicant) holds { subjectType: \"owner\" | \"contact\", subjectId: string }.",
"allOf": [
{
"$ref": "#/components/schemas/ContactRoleAssignmentsMap"
}
]
},
"rampAuthorizationState": {
"type": "string",
"description": "The Ramp partner authorization state for this merchant connection.",
"minLength": 0,
"maxLength": 1024
},
"rampRequestedScopes": {
"description": "The Ramp scopes requested for this merchant connection.",
"type": "array",
"items": {
"type": "string"
}
},
"rampApplicationType": {
"type": "string",
"maxLength": 50,
"description": "The Ramp application type for this merchant connection.",
"minLength": 0
}
}
},
"MerchantConnectionID": {
"type": "object",
"properties": {
"mid": {
"type": "string",
"example": "t1_mer_66ba55436f19c236f52329e",
"description": "Connected merchant Id."
},
"applicationId": {
"type": "string",
"example": "sbx_app_6SZPPblJOxQG7uC9d6Umx5Z6JRF",
"description": "Associated application Id when underwriting merchants. Used by the following connections: Rainforest"
},
"shopId": {
"type": "string",
"example": "6eb3ff30-fc31-4403-95fb-efe50a740d56",
"description": "The merchant shop ID."
}
}
},
"IngressWebhook": {
"type": "object",
"properties": {
"url": {
"type": "string",
"example": "https://wc-api.dev.preczn.com/v1/transactions/braintree/platform/18vk0wec9m9qcre6j7trvwtah6/merchant/mid_test_3t1jyk0w938y4bfrh3vb8z168m",
"description": "The webhook URL for receiving transaction notifications from the processor."
},
"verified": {
"type": "boolean",
"example": false,
"description": "Indicates whether the webhook URL has been verified with the processor."
}
}
},
"ConnectionOut": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "midCon_6v59stftbs837axmpahj21m8jf",
"description": "The merchant connections unique ID in Preczn."
},
"status": {
"type": "string",
"example": "Active",
"enum": [
"Active",
"Cancelled",
"Closed",
"Disabled",
"Error",
"Evaluating",
"Inquiry",
"PartialBoarded",
"Pending",
"Queued",
"Ready",
"Requirements",
"RFI",
"Rejected",
"Sent",
"Unconfigured",
"Underwriting"
],
"description": "The Preczn status of that merchant’s connection. Set by Preczn as onboarding progresses and by connection events; it is not directly settable on merchant create or update. Onboarding can only be initiated while the status is Ready, RFI, or Error: from Ready or Error a successful request moves the status to Queued, while an RFI is resubmitted without a status change and requires changed merchant data. Closing a connection moves the status to Closed."
},
"processor": {
"type": "string",
"example": "Payrix",
"enum": [
"Stripe",
"StripeConnect",
"Braintree",
"PayPal",
"Payrix",
"Rainforest",
"MerchantE",
"Checkout",
"Adyen",
"AdyenForPlatforms",
"QuantumEPay",
"Greensky",
"AffiniPay",
"Nelnet",
"TillPayments",
"Jaris",
"Finix",
"AuthorizeNet",
"Stax",
"PayflowPro",
"Nuvei",
"CardPointe",
"Ramp",
"Frame"
],
"description": "The specific merchant connection, identified by processor name (e.g., Payrix). This is also the connectionId used in the connection path parameters. Not every processor supports onboarding through Preczn; consult onboardingRequirements to determine whether a connection can be onboarded."
},
"onboardingSubmissionDate": {
"type": "string",
"description": "The date and time when the first onboarding attempt was made for the merchant on the connection. This field is populated only if the onboarding was initiated directly through Preczn."
},
"lastDataTransmissionDate": {
"type": "string",
"description": "The date and time when merchant data was most recently transmitted to the connection. This can occur during onboarding, in response to a request for additional information, or to update data, such as submitting an SAQ file."
},
"connectionOnboardingDate": {
"type": "string",
"description": "The date and time when the merchant officially completed onboarding with the connection. This value is retrieved from connections that provide an official onboarding timestamp.",
"example": "2025-08-30T06:00:00Z"
},
"missingRequiredData": {
"example": [
"connectionspecificRequirements.tosVersion",
"connectionspecificRequirements.tosIp"
],
"description": "A list of all merchant data fields that are still needed in order to board that merchant to the connection.",
"type": "array",
"items": {
"type": "string"
}
},
"connectionspecificRequirements": {
"description": "Connection specific data that has to be transmitted during the onboarding process. Connections require only certain data be passed; please consult missingRequiredData for which fields are necessary.",
"allOf": [
{
"$ref": "#/components/schemas/ConnectionSpecificRequirements"
}
]
},
"onboardingRequirements": {
"example": [
"name",
"legalBusinessName"
],
"description": "A list of all the merchant data that is required to onboard the merchant to this specific connection.",
"type": "array",
"items": {
"type": "string"
}
},
"actionDescription": {
"type": "string",
"example": "Action required",
"description": "The text that is set when an action is required on the merchant connect."
},
"actionRequired": {
"type": "boolean",
"example": true,
"description": "Flag to indicate if there is action needed. May be set independently in the event no description is provided."
},
"actionDescriptionReviewed": {
"type": "boolean",
"description": "Flag to designate if an Operator has reviewed and approved the description before it's presented to merchants."
},
"requirementsTemplate": {
"type": "string",
"description": "Requirements template id."
},
"connectionID": {
"description": "Merchant connection IDs are returned from the connection. These are often used to run transactions directly through the connection, rather than via Preczn. However, an ID does not necessarily indicate that the merchant is ready to process transactions. Please verify that the merchant is enabled by checking the status (e.g., \"Active\") or other relevant properties on the merchant record.",
"allOf": [
{
"$ref": "#/components/schemas/MerchantConnectionID"
}
]
},
"ingressWebhook": {
"description": "Webhook configuration for receiving transaction notifications from the processor. Currently supported for Braintree connections.",
"allOf": [
{
"$ref": "#/components/schemas/IngressWebhook"
}
]
},
"platformConnectionId": {
"type": "string",
"description": "Links this merchant AFP connection to a specific platform AFP connection (platform.processors[].id)."
},
"balanceAccountId": {
"type": "string",
"description": "Adyen Balance Account ID for split payments and fund management (AFP only)."
},
"legalEntityId": {
"type": "string",
"description": "Adyen Legal Entity ID for KYC/boarding with Legal Entity Management API (AFP only)."
},
"businessLineId": {
"type": "string",
"description": "Adyen Business Line ID for the merchant (AFP only)."
},
"adyenStoreId": {
"type": "string",
"description": "Adyen Store ID created via Management API (AFP only)."
},
"adyenPaymentMethodIds": {
"description": "Array of Adyen Payment Method IDs configured for the store (AFP only).",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"ImportData": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "midImp_test_jklasfdksdfjk",
"description": "The merchant import data unique ID in Preczn"
},
"importedFrom": {
"type": "string",
"example": "Payrix",
"enum": [
"Stripe",
"StripeConnect",
"Braintree",
"PayPal",
"Payrix",
"Rainforest",
"MerchantE",
"Checkout",
"Adyen",
"AdyenForPlatforms",
"QuantumEPay",
"Greensky",
"AffiniPay",
"Nelnet",
"TillPayments",
"Jaris",
"Finix",
"AuthorizeNet",
"Stax",
"PayflowPro",
"Nuvei",
"CardPointe",
"Ramp",
"Frame"
],
"description": "The specific merchant connection."
},
"importedFields": {
"example": [
"name",
"legalBusinessName"
],
"description": "A list of all the merchant data that is imported from processor",
"type": "array",
"items": {
"type": "string"
}
},
"importedOn": {
"type": "string",
"description": "Import Data date"
}
},
"required": [
"id"
]
},
"MerchantOut": {
"type": "object",
"properties": {
"active": {
"type": "boolean",
"example": true,
"default": true,
"description": "Whether merchant is active or inactive in Preczn. Inactive merchants cannot perform transactions"
},
"plan": {
"type": "string",
"example": "plan_1pj1vzhj9k9438fd8pvtpx91wn",
"description": "Plan ID"
},
"labels": {
"example": [
"LABEL1",
"LABEL2",
"LABEL3"
],
"description": "The labels array enables multiple labels to be added to a merchant record for enhanced categorization and filtering in the vault. Each label must be capital alphanumeric characters and spaces only. Note that any addition or removal of labels in the array requires all desired labels to be included in the request. Please be cautious when modifying merchants with existing labels; ensure that you include any existing labels you wish to keep along with any new labels in the array.",
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Z0-9\\s]*$"
}
},
"name": {
"type": "string",
"maxLength": 255,
"example": "Bob's e-Commerce Shop",
"description": "Merchant name (e.g. DBA)",
"minLength": 1
},
"legalName": {
"type": "string",
"maxLength": 255,
"example": "Robert's Online Accessories Inc.",
"description": "Merchant registered business name. Up to 255 characters; content is otherwise unrestricted today (reserved for future tightening)."
},
"address": {
"description": "Merchant physical address.",
"allOf": [
{
"$ref": "#/components/schemas/Address1"
}
]
},
"email": {
"type": "string",
"example": "inquiry@example.com",
"description": "Merchant email address.",
"format": "email"
},
"phone": {
"type": "string",
"example": "19991210123",
"description": "Merchant phone number. Format: North American phone digits only, optionally prefixed with '1'. No spaces, parentheses, or hyphens. Example: 19991210123.",
"pattern": "^1?\\d{10}$"
},
"annualFinanceVolume": {
"type": "integer",
"example": 100000,
"description": "The amount a merchant finances in a year.",
"minimum": 0
},
"tin": {
"type": "string",
"example": "123456789",
"description": "Tax identification number. 9 to 15 alphanumeric characters only.",
"minLength": 9,
"maxLength": 15,
"pattern": "^[a-zA-Z0-9]*$"
},
"tinType": {
"type": "string",
"example": "ssn",
"enum": [
"ssn",
"ein",
"bn",
"sin"
],
"description": "Identification number type, value must be either `ssn`, `ein`, `bn`, or `sin`."
},
"website": {
"type": "string",
"example": "https://www.example.com/",
"description": "URL to merchant's website.",
"format": "uri"
},
"mailingAddress": {
"description": "Mailing address.",
"allOf": [
{
"$ref": "#/components/schemas/Address1"
}
]
},
"billingContact": {
"description": "Billing address.",
"allOf": [
{
"$ref": "#/components/schemas/BillingAddress"
}
]
},
"businessType": {
"type": "string",
"example": "llc",
"enum": [
"soleProprietor",
"corp",
"llc",
"partnership",
"nonprofit",
"govt"
],
"description": "Business type."
},
"publicCompany": {
"type": "boolean",
"example": true,
"default": true,
"description": "Publically traded company flag."
},
"isBusinessAddress": {
"type": "boolean",
"example": false,
"description": "Flag indicating whether the merchant address is a business address."
},
"stateIncorporated": {
"type": "string",
"example": "NY",
"description": "State in which business was incorporated."
},
"countryIncorporated": {
"type": "string",
"example": "USA",
"description": "Country in which business was incorporated.",
"enum": [
"AFG",
"ALB",
"DZA",
"ASM",
"AND",
"AGO",
"AIA",
"ATA",
"ATG",
"ARG",
"ARM",
"ABW",
"AUS",
"AUT",
"AZE",
"BHS",
"BHR",
"BGD",
"BRB",
"BLR",
"BEL",
"BLZ",
"BEN",
"BMU",
"BTN",
"BOL",
"BES",
"BIH",
"BWA",
"BVT",
"BRA",
"IOT",
"BRN",
"BGR",
"BFA",
"BDI",
"CPV",
"KHM",
"CMR",
"CAN",
"CYM",
"CAF",
"TCD",
"CHL",
"CHN",
"CXR",
"CCK",
"COL",
"COM",
"COD",
"COG",
"COK",
"CRI",
"HRV",
"CUB",
"CUW",
"CYP",
"CZE",
"CIV",
"DNK",
"DJI",
"DMA",
"DOM",
"ECU",
"EGY",
"SLV",
"GNQ",
"ERI",
"EST",
"SWZ",
"ETH",
"FLK",
"FRO",
"FJI",
"FIN",
"FRA",
"GUF",
"PYF",
"ATF",
"GAB",
"GMB",
"GEO",
"DEU",
"GHA",
"GIB",
"GRC",
"GRL",
"GRD",
"GLP",
"GUM",
"GTM",
"GGY",
"GIN",
"GNB",
"GUY",
"HTI",
"HMD",
"VAT",
"HND",
"HKG",
"HUN",
"ISL",
"IND",
"IDN",
"IRN",
"IRQ",
"IRL",
"IMN",
"ISR",
"ITA",
"JAM",
"JPN",
"JEY",
"JOR",
"KAZ",
"KEN",
"KIR",
"PRK",
"KOR",
"KWT",
"KGZ",
"LAO",
"LVA",
"LBN",
"LSO",
"LBR",
"LBY",
"LIE",
"LTU",
"LUX",
"MAC",
"MDG",
"MWI",
"MYS",
"MDV",
"MLI",
"MLT",
"MHL",
"MTQ",
"MRT",
"MUS",
"MYT",
"MEX",
"FSM",
"MDA",
"MCO",
"MNG",
"MNE",
"MSR",
"MAR",
"MOZ",
"MMR",
"NAM",
"NRU",
"NPL",
"NLD",
"NCL",
"NZL",
"NIC",
"NER",
"NGA",
"NIU",
"NFK",
"MNP",
"NOR",
"OMN",
"PAK",
"PLW",
"PSE",
"PAN",
"PNG",
"PRY",
"PER",
"PHL",
"PCN",
"POL",
"PRT",
"PRI",
"QAT",
"MKD",
"ROU",
"RUS",
"RWA",
"REU",
"BLM",
"SHN",
"KNA",
"LCA",
"MAF",
"SPM",
"VCT",
"WSM",
"SMR",
"STP",
"SAU",
"SEN",
"SRB",
"SYC",
"SLE",
"SGP",
"SXM",
"SVK",
"SVN",
"SLB",
"SOM",
"ZAF",
"SGS",
"SSD",
"ESP",
"LKA",
"SDN",
"SUR",
"SJM",
"SWE",
"CHE",
"SYR",
"TWN",
"TJK",
"TZA",
"THA",
"TLS",
"TGO",
"TKL",
"TON",
"TTO",
"TUN",
"TUR",
"TKM",
"TCA",
"TUV",
"UGA",
"UKR",
"ARE",
"GBR",
"UMI",
"USA",
"URY",
"UZB",
"VUT",
"VEN",
"VNM",
"VGB",
"VIR",
"WLF",
"ESH",
"YEM",
"ZMB",
"ZWE",
"ALA"
]
},
"dateEstablished": {
"type": "string",
"example": "1970-12-22",
"description": "Date which merchant business was established."
},
"customerServicePhone": {
"type": "string",
"example": "19991210123",
"description": "Merchant business customer service phone number. Format: North American phone digits only, optionally prefixed with '1'. No spaces, parentheses, or hyphens. Example: 19991210123.",
"pattern": "^1?\\d{10}$"
},
"productServiceDescription": {
"type": "string",
"example": "Miscellaneous online retail sales.",
"description": "Description of merchant's products or services provided."
},
"mcc": {
"type": "string",
"example": "0742",
"description": "Merchant category code."
},
"naicsClassificationCode": {
"type": "string",
"example": "722511",
"description": "NAICS classification code for the merchant's primary business activity. Format: a 6-digit code from the current NAICS revision (NAICS 2022). Preczn checks the code exists in that revision, not just its format; an unknown or retired code is rejected with HTTP 400. Look up codes at the U.S. Census Bureau NAICS search (https://www.census.gov/naics/). Example: 722511.",
"pattern": "^\\d{6}$"
},
"annualSaleVolume": {
"type": "integer",
"example": 10000050,
"description": "The total sales volume for the year, represented as a whole number without decimals. For example, an annual sales volume of $100,000.50 should be entered as 10000050. This field is intended to avoid decimal representation by scaling the actual dollar amount to a whole number (i.e., multiplying the dollar amount by 100).",
"minimum": 0
},
"averageTicket": {
"type": "integer",
"example": 1350,
"description": "The average sales ticket dollar amount, represented as a whole number without decimals. For example, an amount of $13.50 should be entered as 1350. This field is intended to avoid decimal representation by scaling the actual dollar amount to a whole number (i.e., multiplying the dollar amount by 100).",
"minimum": 0
},
"highTicket": {
"type": "integer",
"example": 50000,
"description": "The highest sales ticket dollar amount collected by the merchant, represented as a whole number without decimals. For example, an amount of $2,500.75 should be entered as 250075. This field is intended to avoid decimal representation by scaling the actual dollar amount to a whole number (i.e., multiplying the dollar amount by 100).",
"minimum": 0
},
"shipToDays": {
"type": "number",
"example": 3,
"minimum": 0,
"maximum": 30,
"description": "Number of days required to ship sold items."
},
"externalId": {
"type": "string",
"description": "A unique identifier used to reference the merchant in your external system. This value must be unique across the same mode (test or live).",
"maxLength": 50,
"example": "external-merchant-id-456"
},
"owners": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Owner"
}
},
"banking": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Banking"
}
},
"saasData": {
"description": "Vertical SaaS platform data for this merchant, including start date and billing configuration.",
"example": {
"startDate": "2025-03-17T19:46:45Z",
"billing": {
"amount": 1000,
"frequency": "MONTHLY",
"currency": "USD"
}
},
"allOf": [
{
"$ref": "#/components/schemas/SaasData"
}
]
},
"transactionVolumeSnapshot": {
"description": "Snapshot of the merchant transaction volume, including date and aggregated payment method totals.",
"example": {
"volumeAsOfDate": "2025-03-17T19:46:45Z",
"allPaymentMethods": {
"last30Days": 1000,
"last180Days": 5000
}
},
"allOf": [
{
"$ref": "#/components/schemas/TransactionVolumeSnapshot"
}
]
},
"walletSettings": {
"description": "Digital wallet payment settings for this merchant. Configure Google Pay and Apple Pay payment methods.",
"example": {
"googlePay": {
"enabled": true
},
"applePay": {
"enabled": true
}
},
"allOf": [
{
"$ref": "#/components/schemas/MerchantWalletSettings"
}
]
},
"id": {
"type": "string",
"example": "mid_2zyd88xrnr90xskmjmqpd0x1vj",
"description": "Merchant ID"
},
"creationMethod": {
"type": "string",
"example": "api",
"description": "Merchant data creation type"
},
"lastSignedSAQExpiresOn": {
"type": "string",
"example": "2024-01-01T01:01:01Z",
"description": "Last Signed SAQ Expiration Date"
},
"createdOn": {
"type": "string",
"example": "2023-02-22T17:07:03Z",
"description": "Date and time the merchant was created."
},
"modifiedOn": {
"type": "string",
"example": "2023-02-22T17:07:03Z",
"description": "Date and time the merchant was last modified."
},
"modifiedBy": {
"type": "string",
"example": "API Key: Default",
"description": "User, API, or integration that modified the merchant."
},
"createdBy": {
"type": "string",
"example": "API Key: Default",
"description": "User, API, or integration that last created the merchant."
},
"Saq": {
"$ref": "#/components/schemas/SaqOut"
},
"Connection": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ConnectionOut"
}
},
"ImportData": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ImportData"
}
},
"primaryLocationId": {
"type": "string",
"example": "midLoc_01jr8qk2m9x4tn5vw7yz3a",
"description": "Id of the merchant's primary location. Absent means the merchant itself is the primary location."
},
"locations": {
"example": [
"midLoc_01jr8qk2m9x4tn5vw7yz3a",
"midLoc_01jr8r7c2fx9pm3kd6hs8b"
],
"description": "Ids of the merchant's locations.",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"ApiErrorResponse": {
"type": "object",
"properties": {
"statusCode": {
"type": "number",
"description": "Http status code."
},
"error": {
"type": "string",
"description": "General http error message"
},
"message": {
"oneOf": [
{
"type": "string",
"description": "Error message"
},
{
"type": "array",
"items": {
"type": "string"
},
"description": "List of error messages or validation failure",
"example": [
"field should not be empty.",
"field should be non zero."
]
}
]
}
}
}
},
"securitySchemes": {
"apiKey": {
"type": "apiKey",
"name": "x-api-key",
"in": "header"
}
}
}
}
```