/merchants

GET /merchants

Get all merchants

Retrieve a paginated list of merchants with optional filtering and search

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

Optional Parameters

Click here to view an exhaustive list of all available parameters

page query integer

Page number

pageSize query integer

Number of merchants per page

search query string

Search across merchant name, DBA, legal name, and account number

sort query string

Comma separated list of fields to sort by, prefix with - for descending order

status query string

Filter by merchant status

processingStatus query string

Filter by processing status

riskLevel query string

Filter by risk level

mcc query string

Filter by merchant category code

agentId query string

Filter by agent ID

createdFrom query string

Filter by creation date from

createdTo query string

Filter by creation date to

includeRelations query boolean

Include additional related data (equipment, notes, documents)

Try it out

Output:

Responses

Description

Successful response

{
  "data": [
    {
      "id": "string",
      "merchantName": "string",
      "dba": "string",
      "legalName": "string",
      "mcc": "string",
      "mccDescription": "string",
      "status": "string",
      "processingStatus": "string",
      "riskLevel": "string",
      "accountNumber": "string",
      "createdDate": "string",
      "activatedDate": "string",
      "lastProcessingDate": "string",
      "agentId": "string",
      "agentName": "string",
      "isoId": "string",
      "isoName": "string",
      "owner": {
        "firstName": "string",
        "lastName": "string",
        "email": "string",
        "phone": "string",
        "ssn": "string"
      },
      "address": {
        "street1": "string",
        "street2": "string",
        "city": "string",
        "state": "string",
        "postalCode": "string",
        "country": "string"
      },
      "banking": {
        "routingNumber": "string",
        "accountNumberLast4": "string",
        "accountType": "string",
        "bankName": "string"
      },
      "processing": {
        "monthlyVolume": 0,
        "averageTicket": 0,
        "highTicket": 0,
        "currentReserve": 0,
        "reservePercentage": 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
      },
      "compliance": {
        "pciCompliant": false,
        "pciLevel": "string",
        "lastPciDate": "string",
        "nextPciDue": "string",
        "documentsRequired": [
          {
            "type": "string",
            "status": "string",
            "expiryDate": "string"
          }
        ]
      },
      "riskMetrics": {
        "riskScore": 0,
        "chargebackCount": 0,
        "chargebackRatio": 0,
        "refundRatio": 0,
        "suspiciousActivity": false,
        "lastRiskReview": "string",
        "nextRiskReview": "string"
      },
      "equipment": [
        {
          "id": "string",
          "type": "string",
          "model": "string",
          "serialNumber": "string",
          "status": "string",
          "deployedDate": "string",
          "returnedDate": "string"
        }
      ],
      "notes": [
        {
          "id": "string",
          "date": "string",
          "author": "string",
          "content": "string",
          "type": "string",
          "visibility": "string"
        }
      ],
      "documents": [
        {
          "id": "string",
          "name": "string",
          "type": "string",
          "uploadedDate": "string",
          "uploadedBy": "string",
          "status": "string",
          "url": "string"
        }
      ],
      "supportTickets": [
        {
          "id": "string",
          "subject": "string",
          "status": "string",
          "priority": "string",
          "createdDate": "string",
          "lastUpdated": "string"
        }
      ]
    }
  ],
  "totalCount": 0,
  "totalPages": 0,
  "currentPage": 0
}

References

#/components/parameters/xAccountIdHeader #/components/schemas/MerchantEquipment #/components/schemas/MerchantNote #/components/schemas/MerchantDocument #/components/schemas/MerchantResponse #/components/schemas/MerchantList

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/MerchantEquipment

OpenAPI
TypeScript

type: object
description: Equipment assigned to merchant
properties:
  id:
    type: string
  type:
    type: string
    description: Equipment type (terminal, gateway, etc.)
  model:
    type: string
    description: Equipment model
  serialNumber:
    type: string
    description: Serial number
  status:
    type: string
    enum:
      - active
      - inactive
      - returned
    description: Equipment status
  deployedDate:
    type: string
    format: date
    description: Date equipment was deployed
  returnedDate:
    type: string
    format: date
    description: Date equipment was returned

|
export interface MerchantEquipment {
  id?: string;
  /** Equipment type (terminal, gateway, etc.) */
  type?: string;
  /** Equipment model */
  model?: string;
  /** Serial number */
  serialNumber?: string;
  /** Equipment status */
  status?: "active" | "inactive" | "returned";
  /** Date equipment was deployed */
  deployedDate?: Date;
  /** Date equipment was returned */
  returnedDate?: Date;
}

#/components/schemas/MerchantNote

OpenAPI
TypeScript

type: object
description: Notes about the merchant
properties:
  id:
    type: string
  date:
    type: string
    format: date-time
    description: Note creation date
  author:
    type: string
    description: Note author
  content:
    type: string
    description: Note content
  type:
    type: string
    enum:
      - general
      - risk
      - support
      - compliance
      - billing
      - agent
    description: Note type
  visibility:
    type: string
    enum:
      - internal
      - merchant
      - all
    description: Note visibility

|
export interface MerchantNote {
  id?: string;
  /** Note creation date */
  date?: Date;
  /** Note author */
  author?: string;
  /** Note content */
  content?: string;
  /** Note type */
  type?: "general" | "risk" | "support" | "compliance" | "billing" | "agent";
  /** Note visibility */
  visibility?: "internal" | "merchant" | "all";
}

#/components/schemas/MerchantDocument

OpenAPI
TypeScript

type: object
description: Documents related to merchant
properties:
  id:
    type: string
  name:
    type: string
    description: Document name
  type:
    type: string
    description: Document type
  uploadedDate:
    type: string
    format: date-time
    description: Upload date
  uploadedBy:
    type: string
    description: Who uploaded the document
  status:
    type: string
    enum:
      - pending
      - approved
      - rejected
    description: Document status
  url:
    type: string
    description: Document URL

|
export interface MerchantDocument {
  id?: string;
  /** Document name */
  name?: string;
  /** Document type */
  type?: string;
  /** Upload date */
  uploadedDate?: Date;
  /** Who uploaded the document */
  uploadedBy?: string;
  /** Document status */
  status?: "pending" | "approved" | "rejected";
  /** Document URL */
  url?: string;
}

#/components/schemas/MerchantResponse

OpenAPI
TypeScript

type: object
description: Enhanced merchant response with all related data
properties:
  id:
    type: string
    description: Merchant account ID
  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
  accountNumber:
    type: string
    description: Merchant account number
  createdDate:
    type: string
    format: date-time
    description: When the merchant was created
  activatedDate:
    type: string
    format: date-time
    description: Date merchant was activated
  lastProcessingDate:
    type: string
    format: date-time
    description: Last processing activity date
  agentId:
    type: string
    description: Agent account ID reference
  agentName:
    type: string
    description: Agent name
  isoId:
    type: string
    description: ISO account ID reference
  isoName:
    type: string
    description: ISO name
  owner:
    type: object
    description: Primary owner information
    properties:
      firstName:
        type: string
      lastName:
        type: string
      email:
        type: string
      phone:
        type: string
      ssn:
        type: string
        description: SSN (decrypted for display)
  address:
    type: object
    description: Business address
    properties:
      street1:
        type: string
      street2:
        type: string
      city:
        type: string
      state:
        type: string
      postalCode:
        type: string
      country:
        type: string
  banking:
    type: object
    description: Banking information
    properties:
      routingNumber:
        type: string
      accountNumberLast4:
        type: string
        description: Last 4 digits of account number
      accountType:
        type: string
        enum:
          - checking
          - savings
      bankName:
        type: string
  processing:
    type: object
    description: Processing configuration
    properties:
      monthlyVolume:
        type: number
        format: decimal
      averageTicket:
        type: number
        format: decimal
      highTicket:
        type: number
        format: decimal
      currentReserve:
        type: number
        format: decimal
      reservePercentage:
        type: number
        format: decimal
      processingLimit:
        type: number
        format: decimal
      dailyLimit:
        type: number
        format: decimal
      monthlyLimit:
        type: number
        format: decimal
  rates:
    type: object
    description: Rate structure
    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
  compliance:
    type: object
    description: Compliance information
    properties:
      pciCompliant:
        type: boolean
      pciLevel:
        type: string
      lastPciDate:
        type: string
        format: date-time
      nextPciDue:
        type: string
        format: date-time
      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
    description: Risk assessment metrics
    properties:
      riskScore:
        type: number
      chargebackCount:
        type: number
      chargebackRatio:
        type: number
        format: decimal
      refundRatio:
        type: number
        format: decimal
      suspiciousActivity:
        type: boolean
      lastRiskReview:
        type: string
        format: date-time
      nextRiskReview:
        type: string
        format: date-time
  equipment:
    type: array
    items:
      $ref: "#/components/schemas/MerchantEquipment"
  notes:
    type: array
    items:
      $ref: "#/components/schemas/MerchantNote"
  documents:
    type: array
    items:
      $ref: "#/components/schemas/MerchantDocument"
  supportTickets:
    type: array
    items:
      type: object
      properties:
        id:
          type: string
        subject:
          type: string
        status:
          type: string
          enum:
            - open
            - in_progress
            - resolved
            - closed
        priority:
          type: string
          enum:
            - low
            - medium
            - high
            - urgent
        createdDate:
          type: string
          format: date-time
        lastUpdated:
          type: string
          format: date-time

|
export interface MerchantResponse {
  /** Merchant account ID */
  id?: string;
  /** 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 number */
  accountNumber?: string;
  /** When the merchant was created */
  createdDate?: Date;
  /** Date merchant was activated */
  activatedDate?: Date;
  /** Last processing activity date */
  lastProcessingDate?: Date;
  /** Agent account ID reference */
  agentId?: string;
  /** Agent name */
  agentName?: string;
  /** ISO account ID reference */
  isoId?: string;
  /** ISO name */
  isoName?: string;
  /** Primary owner information */
  owner?: {
    firstName?: string;
    lastName?: string;
    email?: string;
    phone?: string;
    ssn?: string;
  };
  /** Business address */
  address?: {
    street1?: string;
    street2?: string;
    city?: string;
    state?: string;
    postalCode?: string;
    country?: string;
  };
  /** Banking information */
  banking?: {
    routingNumber?: string;
    accountNumberLast4?: string;
    accountType?: "checking" | "savings";
    bankName?: string;
  };
  /** Processing configuration */
  processing?: {
    monthlyVolume?: number;
    averageTicket?: number;
    highTicket?: number;
    currentReserve?: number;
    reservePercentage?: number;
    processingLimit?: number;
    dailyLimit?: number;
    monthlyLimit?: number;
  };
  /** Rate structure */
  rates?: {
    discountRate?: number;
    transactionFee?: number;
    monthlyFee?: number;
    annualFee?: number;
    chargebackFee?: number;
    batchFee?: number;
    statementFee?: number;
    pciComplianceFee?: number;
    agentSplit?: number;
    isoSplit?: number;
  };
  /** Compliance information */
  compliance?: {
    pciCompliant?: boolean;
    pciLevel?: string;
    lastPciDate?: Date;
    nextPciDue?: Date;
    documentsRequired?: {
      type?: string;
      status?: "pending" | "approved" | "expired";
      expiryDate?: Date;
    }[];
  };
  /** Risk assessment metrics */
  riskMetrics?: {
    riskScore?: number;
    chargebackCount?: number;
    chargebackRatio?: number;
    refundRatio?: number;
    suspiciousActivity?: boolean;
    lastRiskReview?: Date;
    nextRiskReview?: Date;
  };
  equipment?: MerchantEquipment[];
  notes?: MerchantNote[];
  documents?: MerchantDocument[];
  supportTickets?: {
    id?: string;
    subject?: string;
    status?: "open" | "in_progress" | "resolved" | "closed";
    priority?: "low" | "medium" | "high" | "urgent";
    createdDate?: Date;
    lastUpdated?: Date;
  }[];
}

#/components/schemas/MerchantList

OpenAPI
TypeScript

type: object
properties:
  data:
    type: array
    items:
      $ref: "#/components/schemas/MerchantResponse"
  totalCount:
    type: integer
  totalPages:
    type: integer
  currentPage:
    type: integer

|
export interface MerchantList {
  data?: MerchantResponse[];
  totalCount?: number;
  totalPages?: number;
  currentPage?: number;
}

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