/merchants

POST /merchants

Create a new merchant

Create a new merchant with the provided data

Authentication Required

Authorization: Bearer {token} header string

This header is required to access this endpoint

Required Parameters

x-account-id header string

Account ID for the request

Request Body

Minimum Required
All Properties

{
  "merchantName": "string",
  "dba": "string",
  "legalName": "string",
  "mcc": "string"
}

{
  "merchantName": "string",
  "dba": "string",
  "legalName": "string",
  "mcc": "string",
  "mccDescription": "string",
  "agentAccountId": "string",
  "agentName": "string",
  "isoName": "string",
  "principals": [
    {
      "type": "string",
      "firstName": "string",
      "lastName": "string",
      "email": "string",
      "phone": "string",
      "ssn": "string",
      "driversLicenseNumber": "string",
      "driversLicenseState": "string",
      "dateOfBirth": "string",
      "homeStreet1": "string",
      "homeStreet2": "string",
      "homeCity": "string",
      "homeState": "string",
      "homeZipCode": "string",
      "equityOwnership": 0
    }
  ],
  "addresses": [
    {
      "type": "string",
      "street1": "string",
      "street2": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "US"
    }
  ],
  "banking": {
    "routingNumber": "string",
    "accountNumber": "string",
    "accountType": "string",
    "bankName": "string"
  },
  "processing": {
    "monthlyVolume": 0,
    "averageTicket": 0,
    "highTicket": 0,
    "processingLimit": 0,
    "dailyLimit": 0,
    "monthlyLimit": 0
  },
  "rates": {
    "discountRate": 0,
    "transactionFee": 0,
    "monthlyFee": 0,
    "annualFee": 0,
    "chargebackFee": 0,
    "batchFee": 0,
    "statementFee": 0,
    "pciComplianceFee": 0,
    "agentSplit": 0,
    "isoSplit": 0,
    "effectiveDate": "string"
  },
  "compliance": {
    "pciCompliant": false,
    "pciLevel": "string",
    "lastPciDate": "string",
    "nextPciDue": "string",
    "certificateUrl": "string",
    "documentsRequired": [
      {
        "type": "string",
        "status": "string",
        "expiryDate": "string"
      }
    ]
  },
  "riskMetrics": {
    "riskScore": 0,
    "chargebackCount": 0,
    "chargebackRatio": 0,
    "refundRatio": 0,
    "suspiciousActivity": false,
    "lastRiskReview": "string",
    "nextRiskReview": "string"
  }
}

Try it out

Output:

Responses

Description

Merchant created successfully

{
  "id": 0,
  "merchantName": "string",
  "dba": "string",
  "legalName": "string",
  "mcc": "string",
  "mccDescription": "string",
  "status": "string",
  "processingStatus": "string",
  "riskLevel": "string",
  "merchantAccountId": "string",
  "agentAccountId": "string",
  "agentName": "string",
  "isoAccountId": "string",
  "isoName": "string",
  "activatedDate": "string",
  "lastProcessingDate": "string",
  "createdBy": "string",
  "updatedBy": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

References

#/components/parameters/xAccountIdHeader #/components/schemas/CreateMerchantRequest #/components/schemas/Merchant

in: header
name: x-account-id
schema:
  type: string
description: Account ID for the request
required: true
example: "2311"

|
export type xAccountIdHeader = any; // Schema type not fully supported

#/components/schemas/CreateMerchantRequest

OpenAPI
TypeScript

type: object
required:
  - merchantName
  - dba
  - legalName
  - mcc
properties:
  merchantName:
    type: string
    description: Business trading name
  dba:
    type: string
    description: Doing Business As name
  legalName:
    type: string
    description: Legal business name
  mcc:
    type: string
    description: Merchant category code
  mccDescription:
    type: string
    description: Description of the MCC
  agentAccountId:
    type: string
    description: Agent account ID reference
  agentName:
    type: string
    description: Agent name
  isoName:
    type: string
    description: ISO name
  principals:
    type: array
    items:
      type: object
      required:
        - type
        - firstName
        - lastName
        - email
      properties:
        type:
          type: string
          enum:
            - FOUNDER
            - CO_FOUNDER
            - INVESTOR
            - SHAREHOLDER
            - PARTNER
            - SILENT_PARTNER
            - LIMITED_PARTNER
            - EMPLOYEE_OWNER
            - FAMILY_MEMBER
            - HEIR
            - BOARD_MEMBER_WITH_EQUITY
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
        phone:
          type: string
        ssn:
          type: string
        driversLicenseNumber:
          type: string
        driversLicenseState:
          type: string
        dateOfBirth:
          type: string
        homeStreet1:
          type: string
        homeStreet2:
          type: string
        homeCity:
          type: string
        homeState:
          type: string
        homeZipCode:
          type: string
        equityOwnership:
          type: integer
  addresses:
    type: array
    items:
      type: object
      required:
        - type
        - street1
        - city
        - state
        - postalCode
      properties:
        type:
          type: string
          enum:
            - business
            - legal
            - mailing
        street1:
          type: string
        street2:
          type: string
        city:
          type: string
        state:
          type: string
        postalCode:
          type: string
        country:
          type: string
          default: US
  banking:
    type: object
    required:
      - routingNumber
      - accountNumber
      - accountType
      - bankName
    properties:
      routingNumber:
        type: string
      accountNumber:
        type: string
      accountType:
        type: string
        enum:
          - checking
          - savings
      bankName:
        type: string
  processing:
    type: object
    properties:
      monthlyVolume:
        type: number
        format: decimal
      averageTicket:
        type: number
        format: decimal
      highTicket:
        type: number
        format: decimal
      processingLimit:
        type: number
        format: decimal
      dailyLimit:
        type: number
        format: decimal
      monthlyLimit:
        type: number
        format: decimal
  rates:
    type: object
    required:
      - discountRate
      - transactionFee
      - effectiveDate
    properties:
      discountRate:
        type: number
        format: decimal
      transactionFee:
        type: number
        format: decimal
      monthlyFee:
        type: number
        format: decimal
      annualFee:
        type: number
        format: decimal
      chargebackFee:
        type: number
        format: decimal
      batchFee:
        type: number
        format: decimal
      statementFee:
        type: number
        format: decimal
      pciComplianceFee:
        type: number
        format: decimal
      agentSplit:
        type: number
        format: decimal
      isoSplit:
        type: number
        format: decimal
      effectiveDate:
        type: string
        format: date
  compliance:
    type: object
    properties:
      pciCompliant:
        type: boolean
      pciLevel:
        type: string
      lastPciDate:
        type: string
        format: date
      nextPciDue:
        type: string
        format: date
      certificateUrl:
        type: string
      documentsRequired:
        type: array
        items:
          type: object
          properties:
            type:
              type: string
            status:
              type: string
              enum:
                - pending
                - approved
                - expired
            expiryDate:
              type: string
              format: date
  riskMetrics:
    type: object
    properties:
      riskScore:
        type: integer
      chargebackCount:
        type: integer
      chargebackRatio:
        type: number
        format: decimal
      refundRatio:
        type: number
        format: decimal
      suspiciousActivity:
        type: boolean
      lastRiskReview:
        type: string
        format: date
      nextRiskReview:
        type: string
        format: date

|
export interface CreateMerchantRequest {
  /** Business trading name */
  merchantName: string;
  /** Doing Business As name */
  dba: string;
  /** Legal business name */
  legalName: string;
  /** Merchant category code */
  mcc: string;
  /** Description of the MCC */
  mccDescription?: string;
  /** Agent account ID reference */
  agentAccountId?: string;
  /** Agent name */
  agentName?: string;
  /** ISO name */
  isoName?: string;
  principals?: {
    type:
      | "FOUNDER"
      | "CO_FOUNDER"
      | "INVESTOR"
      | "SHAREHOLDER"
      | "PARTNER"
      | "SILENT_PARTNER"
      | "LIMITED_PARTNER"
      | "EMPLOYEE_OWNER"
      | "FAMILY_MEMBER"
      | "HEIR"
      | "BOARD_MEMBER_WITH_EQUITY";
    firstName: string;
    lastName: string;
    email: string;
    phone?: string;
    ssn?: string;
    driversLicenseNumber?: string;
    driversLicenseState?: string;
    dateOfBirth?: string;
    homeStreet1?: string;
    homeStreet2?: string;
    homeCity?: string;
    homeState?: string;
    homeZipCode?: string;
    equityOwnership?: number;
  }[];
  addresses?: {
    type: "business" | "legal" | "mailing";
    street1: string;
    street2?: string;
    city: string;
    state: string;
    postalCode: string;
    country?: string;
  }[];
  banking?: {
    routingNumber: string;
    accountNumber: string;
    accountType: "checking" | "savings";
    bankName: string;
  };
  processing?: {
    monthlyVolume?: number;
    averageTicket?: number;
    highTicket?: number;
    processingLimit?: number;
    dailyLimit?: number;
    monthlyLimit?: number;
  };
  rates?: {
    discountRate: number;
    transactionFee: number;
    monthlyFee?: number;
    annualFee?: number;
    chargebackFee?: number;
    batchFee?: number;
    statementFee?: number;
    pciComplianceFee?: number;
    agentSplit?: number;
    isoSplit?: number;
    effectiveDate: Date;
  };
  compliance?: {
    pciCompliant?: boolean;
    pciLevel?: string;
    lastPciDate?: Date;
    nextPciDue?: Date;
    certificateUrl?: string;
    documentsRequired?: {
      type?: string;
      status?: "pending" | "approved" | "expired";
      expiryDate?: Date;
    }[];
  };
  riskMetrics?: {
    riskScore?: number;
    chargebackCount?: number;
    chargebackRatio?: number;
    refundRatio?: number;
    suspiciousActivity?: boolean;
    lastRiskReview?: Date;
    nextRiskReview?: Date;
  };
}

#/components/schemas/Merchant

OpenAPI
TypeScript

type: object
description: Core merchant object
properties:
  id:
    type: integer
    description: Unique identifier for the merchant
  merchantName:
    type: string
    description: Business trading name
  dba:
    type: string
    description: Doing Business As name
  legalName:
    type: string
    description: Legal business name
  mcc:
    type: string
    description: Merchant category code
  mccDescription:
    type: string
    description: Description of the MCC
  status:
    type: string
    enum:
      - active
      - inactive
      - suspended
      - pending
      - closed
    description: Current merchant status
  processingStatus:
    type: string
    enum:
      - enabled
      - disabled
      - limited
      - hold
    description: Processing status
  riskLevel:
    type: string
    enum:
      - low
      - medium
      - high
      - critical
    description: Risk assessment level
  merchantAccountId:
    type: string
    description: Merchant account ID reference
  agentAccountId:
    type: string
    description: Agent account ID reference
  agentName:
    type: string
    description: Agent name
  isoAccountId:
    type: string
    description: ISO account ID reference
  isoName:
    type: string
    description: ISO name
  activatedDate:
    type: string
    format: date-time
    description: Date merchant was activated
  lastProcessingDate:
    type: string
    format: date-time
    description: Last processing activity date
  createdBy:
    type: string
    description: Email of user who created the merchant
  updatedBy:
    type: string
    description: Email of user who last updated the merchant
  createdAt:
    type: string
    format: date-time
    description: When the merchant was created
  updatedAt:
    type: string
    format: date-time
    description: When the merchant was last updated

|
export interface Merchant {
  /** Unique identifier for the merchant */
  id?: number;
  /** Business trading name */
  merchantName?: string;
  /** Doing Business As name */
  dba?: string;
  /** Legal business name */
  legalName?: string;
  /** Merchant category code */
  mcc?: string;
  /** Description of the MCC */
  mccDescription?: string;
  /** Current merchant status */
  status?: "active" | "inactive" | "suspended" | "pending" | "closed";
  /** Processing status */
  processingStatus?: "enabled" | "disabled" | "limited" | "hold";
  /** Risk assessment level */
  riskLevel?: "low" | "medium" | "high" | "critical";
  /** Merchant account ID reference */
  merchantAccountId?: string;
  /** Agent account ID reference */
  agentAccountId?: string;
  /** Agent name */
  agentName?: string;
  /** ISO account ID reference */
  isoAccountId?: string;
  /** ISO name */
  isoName?: string;
  /** Date merchant was activated */
  activatedDate?: Date;
  /** Last processing activity date */
  lastProcessingDate?: Date;
  /** Email of user who created the merchant */
  createdBy?: string;
  /** Email of user who last updated the merchant */
  updatedBy?: string;
  /** When the merchant was created */
  createdAt?: Date;
  /** When the merchant was last updated */
  updatedAt?: Date;
}

Route Source Code

Check out the source code for this route entrypoint here: /merchants/route.ts

Or the swagger.yaml spec this documentation was generated from: /merchants/swagger.yaml