New Merchant Zod Schema
We use zod-schemas to validate incoming body requests. If you happen to use JS/TS, you can use the zod library to validate your body before sending the request.
import { z } from "zod";
export const validateUSPhoneNumber = (phone: string) => {
if (phone.startsWith("1")) return false;
if (phone === "0000000000") return false;
if (phone.startsWith("555")) return false;
if (phone.slice(3, 6) === "555") return false;
return true;
};
export const validateRoutingNumber = (routing: string) => {
if (routing.length !== 9) return false;
// Calculate checksum using ABA routing number algorithm
const digits = routing.split("").map(Number);
const checksum =
3 * (digits[0]! + digits[3]! + digits[6]!) +
7 * (digits[1]! + digits[4]! + digits[7]!) +
1 * (digits[2]! + digits[5]! + digits[8]!);
if (routing === "000000000") return false;
return checksum % 10 === 0;
};
const addressSchema = z.object({
street1: z
.string()
.min(1, "Street address is required")
.refine(
(value) => !value.toLowerCase().includes("po box") && !value.toLowerCase().includes("p.o. box"),
"PO Boxes are not allowed",
),
street2: z.string().optional(),
city: z.string().min(1, "City is required"),
state: z.string().length(2, "State must be a 2-letter code").toUpperCase(),
zipCode: z.string().regex(/^\d{5}(-\d{4})?$/, "ZIP code must be in format 12345 or 12345-6789"),
});
const dateSchema = z.object({
month: z.number().min(1).max(12),
day: z.number().min(1).max(31),
year: z.number().min(1900),
});
const legalSchema = z
.object({
name: z
.string()
.min(1, "Business legal name is required")
.max(100, "Business legal name cannot exceed 100 characters"),
dba: z.string().min(1, "DBA name is required").max(24, "DBA name cannot exceed 24 characters"),
locationName: z.string().min(1, "Location name is required").optional(),
taxId: z.string().regex(/^\d{9}$/, "TIN/EIN/SSN must be in format XXXXXXXXX (9 digits)"),
address: addressSchema,
mailingAddress: addressSchema.optional(),
ownershipType: z.enum(
[
"GOVERNMENT",
"JOINT STOCK",
"LIMITED",
"NON PROFIT ORG",
"PARTNERSHIP",
"CORPORATION",
"PUBLIC COMPANY",
"SOLE PROPRIETOR",
],
{
errorMap: () => ({ message: "Invalid business type" }),
},
),
category: z
.enum(["MOTO", "RETAIL"], {
errorMap: () => ({ message: "Invalid business category" }),
})
.optional(),
productsSold: z.string().max(30, "Description cannot exceed 30 characters").optional().default("Medical Services"),
phone: z
.string()
.regex(/^\d{10}$/, "Phone number must be exactly 10 digits")
.refine(validateUSPhoneNumber, "Phone number cannot start with 1 or contain 555"),
email: z.string().email("Invalid business email address").min(1, "Business email is required"),
dateOfIncorporation: dateSchema,
website: z.string().url("Must be a valid URL. It must begin with https://").optional(),
averageTicketPrice: z.number().min(0, "Average ticket price must be positive"),
highTicketPrice: z.number().min(0, "High ticket price must be positive"),
averageMonthlyVolume: z.number().min(0, "Average monthly volume must be positive"),
averageYearlyVolume: z.number().min(0, "Average yearly volume must be positive").optional(),
b2bTransactionPercentage: z
.number()
.min(0, "B2B percentage must be between 0 and 100")
.max(100, "B2B percentage must be between 0 and 100")
.optional(),
b2cTransactionPercentage: z
.number()
.min(0, "B2C percentage must be between 0 and 100")
.max(100, "B2C percentage must be between 0 and 100")
.optional(),
})
.transform((data) => {
const transformedData = { ...data };
// Compute yearly volume if not provided
if (!data.averageYearlyVolume) {
transformedData.averageYearlyVolume = data.averageMonthlyVolume * 12;
}
// Handle B2B/B2C percentages
if (data.b2bTransactionPercentage && !data.b2cTransactionPercentage) {
transformedData.b2cTransactionPercentage = 100 - data.b2bTransactionPercentage;
} else if (data.b2cTransactionPercentage && !data.b2bTransactionPercentage) {
transformedData.b2bTransactionPercentage = 100 - data.b2cTransactionPercentage;
}
return transformedData;
})
.superRefine((data, ctx) => {
// Validate that at least one percentage is provided
if (!data.b2bTransactionPercentage && !data.b2cTransactionPercentage) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: "Either B2B or B2C transaction percentage must be provided",
path: ["b2bTransactionPercentage"],
});
}
// Validate sum equals 100 if both provided
if (
data.b2bTransactionPercentage &&
data.b2cTransactionPercentage &&
data.b2bTransactionPercentage + data.b2cTransactionPercentage !== 100
) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: "B2B and B2C percentages must sum to 100",
path: ["b2bTransactionPercentage"],
});
}
});
const ownerSchema = z.object({
title: z.enum(["CEO", "CFO", "COO", "President", "Secretary", "Treasurer", "Vice President"], {
errorMap: () => ({ message: "Invalid title" }),
}),
firstName: z.string().min(1, "First Name is required"),
lastName: z.string().min(1, "Last Name is required"),
percentage: z
.number()
.min(0, "Ownership percentage must be positive")
.max(100, "Ownership percentage cannot exceed 100"),
ssn: z.string().regex(/^\d{9}$/, "SSN must be in format XXXXXXXXX (9 digits)"),
dob: dateSchema,
address: addressSchema,
phone: z
.string()
.regex(/^\d{10}$/, "Phone number must be exactly 10 digits")
.refine(validateUSPhoneNumber, "Phone number cannot start with 1 or contain 555"),
email: z.string().email("Invalid email address"),
isControllingProng: z.boolean({
required_error: "Controlling prong selection is required",
}),
isPrimaryContact: z.boolean({
required_error: "Primary contact selection is required",
}),
isPciContact: z.boolean({
required_error: "PCI contact selection is required",
}),
});
const ownersSchema = z
.array(ownerSchema)
.max(4, "Maximum of 4 owners allowed")
.superRefine((owners, ctx) => {
owners.forEach((owner, index) => {
if (owner.percentage < 25) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: "Owner must have at least 25% ownership to be listed. Otherwise remove the owner",
path: [index, "percentage"],
});
}
});
});
// First define the control prong schema
const controlProngSchema = z.object({
title: z.enum(["CEO", "CFO", "COO", "President", "Secretary", "Treasurer", "Vice President"], {
errorMap: () => ({ message: "Invalid title" }),
}),
firstName: z.string().min(1, "First Name is required"),
lastName: z.string().min(1, "Last Name is required"),
ssn: z.string().regex(/^\d{9}$/, "SSN must be in format XXXXXXXXX (9 digits)"),
dob: dateSchema,
address: addressSchema,
phone: z
.string()
.regex(/^\d{10}$/, "Phone number must be exactly 10 digits")
.refine(validateUSPhoneNumber, "Phone number cannot start with 1 or contain 555"),
email: z.string().email("Invalid email address"),
});
// First define the primary contact schema
const primaryContactSchema = z.object({
title: z.enum(["CEO", "CFO", "COO", "President", "Secretary", "Treasurer", "Vice President"], {
errorMap: () => ({ message: "Invalid title" }),
}),
firstName: z.string().min(1, "First Name is required"),
lastName: z.string().min(1, "Last Name is required"),
phone: z
.string()
.regex(/^\d{10}$/, "Phone number must be exactly 10 digits")
.refine(validateUSPhoneNumber, "Phone number cannot start with 1 or contain 555"),
email: z.string().email("Invalid email address"),
});
const pciContactSchema = z.object({
email: z.string().email("Invalid email address"),
});
const bankAccountSchema = z
.object({
name: z.string().min(1, "Bank name is required"),
routingNumber: z
.string()
.regex(/^\d{9}$/, "Routing number must be exactly 9 digits")
.refine(validateRoutingNumber, "Invalid routing number"),
confirmRoutingNumber: z.string(),
accountNumber: z
.string()
.min(9, "Account number must be at least 9 characters")
.regex(/^\d+$/, "Account number must contain only numbers"),
confirmAccountNumber: z.string(),
})
.refine((data) => data.routingNumber === data.confirmRoutingNumber, {
message: "Routing numbers must match",
path: ["confirmRoutingNumber"],
})
.refine((data) => data.accountNumber === data.confirmAccountNumber, {
message: "Account numbers must match",
path: ["confirmAccountNumber"],
});
export const merchantRequestSchema = z
.object({
legal: legalSchema,
owners: ownersSchema.optional(),
controlProng: controlProngSchema.optional(),
primaryContact: primaryContactSchema.optional(),
pciContact: pciContactSchema.optional(),
bankAccount: bankAccountSchema,
})
.transform((data, _ctx) => {
// Find owners with special roles
const controllingOwner = data.owners?.find((owner) => owner.isControllingProng);
const primaryContactOwner = data.owners?.find((owner) => owner.isPrimaryContact);
const primaryPciContactOwner = data.owners?.find((owner) => owner.isPciContact);
const transformedData = { ...data };
// Autofill controlProng if controlling owner exists && this is not a sole proprietorship
if (controllingOwner && data.legal.ownershipType !== "SOLE PROPRIETOR") {
const {
isControllingProng: _isControllingProng,
percentage: _percentage,
isPrimaryContact: _isPrimaryContact,
isPciContact: _isPciContact,
...controlProngFields
} = controllingOwner;
transformedData.controlProng = controlProngFields;
}
// If primaryContact has been provided, then use that. Otherwise, use the primary contact owner
if (primaryContactOwner && !data.primaryContact) {
transformedData.primaryContact = {
title: primaryContactOwner.title,
firstName: primaryContactOwner.firstName,
lastName: primaryContactOwner.lastName,
phone: primaryContactOwner.phone,
email: primaryContactOwner.email,
};
}
if (primaryPciContactOwner && !data.pciContact) {
transformedData.pciContact = {
email: primaryPciContactOwner.email,
};
}
return transformedData;
})
.superRefine((values, ctx) => {
let valid = true;
const ownershipType = values.legal.ownershipType;
// Rule 1. There should always be at least 1 primary contact
if (!values.primaryContact) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: "Primary contact information is required",
path: ["primaryContact"],
});
valid = false;
}
if (!values.pciContact) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: "PCI contact information is required",
path: ["pciContact"],
});
valid = false;
}
// Rule 2. If ownershipType is "GOVERNMENT" or "PUBLIC COMPANY", there should be no owners or control prong
if (["GOVERNMENT", "PUBLIC COMPANY"].includes(ownershipType)) {
if (!!values.owners) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: `${ownershipType} should not have any owners listed`,
path: ["owners"],
});
valid = false;
}
if (!!values.controlProng) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: `${ownershipType} should not have a control prong`,
path: ["controlProng"],
});
valid = false;
}
}
// Rule 3. If ownershipType is "NON PROFIT ORG", there should be no owners, but a control prong
else if (ownershipType === "NON PROFIT ORG") {
if (!!values.owners) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: "Non-profit organizations should not have any owners listed",
path: ["owners"],
});
valid = false;
}
if (!values.controlProng) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: "Non-profit organizations require control prong information",
path: ["controlProng"],
});
valid = false;
}
}
// Rule 4. If ownershipType is "SOLE PROPRIETOR", there should be exactly 1 owner, no control prong, and legal name should equal firstName lastName
else if (ownershipType === "SOLE PROPRIETOR") {
if (!values.owners || values.owners.length !== 1) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: "Sole proprietorship must have exactly one owner",
path: ["owners"],
});
valid = false;
}
if (!!values.controlProng) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: "Sole proprietorship should not have a control prong",
path: ["controlProng"],
});
valid = false;
}
if (values.legal.name !== values.owners?.[0]?.firstName + " " + values.owners?.[0]?.lastName) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: "For sole proprietorship, business legal name must match owner's name",
path: ["legal", "firstName"],
});
valid = false;
}
}
// Rule 5. If its any other type of ownership, there should be at least 1 owner and a control prong
else {
if (!values.owners || values.owners.length === 0) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: `At least one owner is required for ${ownershipType}`,
path: ["owners"],
});
valid = false;
}
if (!values.controlProng) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: "Control prong information is required when no owner is marked as controlling prong",
path: ["controlProng"],
});
valid = false;
}
}
return valid;
});
export type MerchantRequestBody = z.infer<typeof merchantRequestSchema>;