/merchants/{merchantId}

GET /merchants/{merchantId}

Get a merchant by ID

Retrieves a specific merchant by its ID with all related 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

merchantId path integer

The ID of the merchant to retrieve

Try it out

Output:

Responses

Description

Successful response

{
  "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",
  "principals": [
    {
      "id": 0,
      "merchantId": 0,
      "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": [
    {
      "id": 0,
      "merchantId": 0,
      "type": "string",
      "street1": "string",
      "street2": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "US"
    }
  ],
  "banking": {
    "id": 0,
    "merchantId": 0,
    "routingNumber": "string",
    "accountNumberLast4": "string",
    "accountNumber": "string",
    "accountType": "string",
    "bankName": "string"
  },
  "processing": {
    "id": 0,
    "merchantId": 0,
    "monthlyVolume": 0,
    "averageTicket": 0,
    "highTicket": 0,
    "currentReserve": 0,
    "reservePercentage": 0,
    "processingLimit": 0,
    "dailyLimit": 0,
    "monthlyLimit": 0
  },
  "rates": [
    {
      "id": 0,
      "merchantId": 0,
      "discountRate": 0,
      "transactionFee": 0,
      "monthlyFee": 0,
      "annualFee": 0,
      "chargebackFee": 0,
      "batchFee": 0,
      "statementFee": 0,
      "pciComplianceFee": 0,
      "agentSplit": 0,
      "isoSplit": 0,
      "effectiveDate": "string"
    }
  ],
  "compliance": {
    "id": 0,
    "merchantId": 0,
    "pciCompliant": false,
    "pciLevel": "string",
    "lastPciDate": "string",
    "nextPciDue": "string",
    "certificateUrl": "string",
    "documentsRequired": [
      {
        "type": "string",
        "status": "string",
        "expiryDate": "string"
      }
    ]
  },
  "riskMetrics": {
    "id": 0,
    "merchantId": 0,
    "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"
    }
  ]
}

References

#/components/parameters/xAccountIdHeader #/components/schemas/Merchant #/components/schemas/MerchantPrincipal #/components/schemas/MerchantAddress #/components/schemas/MerchantBanking #/components/schemas/MerchantProcessing #/components/schemas/MerchantRates #/components/schemas/MerchantCompliance #/components/schemas/MerchantRiskMetrics #/components/schemas/MerchantEquipment #/components/schemas/MerchantNote #/components/schemas/MerchantDocument #/components/schemas/MerchantWithRelations

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/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;
}

#/components/schemas/MerchantPrincipal

OpenAPI
TypeScript

type: object
description: Business principal/owner information
properties:
  id:
    type: integer
  merchantId:
    type: integer
  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
    description: Social Security Number (encrypted)
  driversLicenseNumber:
    type: string
    description: Driver's license number (encrypted)
  driversLicenseState:
    type: string
  dateOfBirth:
    type: string
    description: Date of birth (encrypted)
  homeStreet1:
    type: string
  homeStreet2:
    type: string
  homeCity:
    type: string
  homeState:
    type: string
  homeZipCode:
    type: string
  equityOwnership:
    type: integer
    description: Percentage of equity ownership

|
export interface MerchantPrincipal {
  id?: number;
  merchantId?: number;
  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;
  /** Social Security Number (encrypted) */
  ssn?: string;
  /** Driver's license number (encrypted) */
  driversLicenseNumber?: string;
  driversLicenseState?: string;
  /** Date of birth (encrypted) */
  dateOfBirth?: string;
  homeStreet1?: string;
  homeStreet2?: string;
  homeCity?: string;
  homeState?: string;
  homeZipCode?: string;
  /** Percentage of equity ownership */
  equityOwnership?: number;
}

#/components/schemas/MerchantAddress

OpenAPI
TypeScript

type: object
description: Business address information
properties:
  id:
    type: integer
  merchantId:
    type: integer
  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

|
export interface MerchantAddress {
  id?: number;
  merchantId?: number;
  type?: "business" | "legal" | "mailing";
  street1?: string;
  street2?: string;
  city?: string;
  state?: string;
  postalCode?: string;
  country?: string;
}

#/components/schemas/MerchantBanking

OpenAPI
TypeScript

type: object
description: Banking information
properties:
  id:
    type: integer
  merchantId:
    type: integer
  routingNumber:
    type: string
  accountNumberLast4:
    type: string
  accountNumber:
    type: string
    description: Full account number (encrypted)
  accountType:
    type: string
    enum:
      - checking
      - savings
  bankName:
    type: string

|
export interface MerchantBanking {
  id?: number;
  merchantId?: number;
  routingNumber?: string;
  accountNumberLast4?: string;
  /** Full account number (encrypted) */
  accountNumber?: string;
  accountType?: "checking" | "savings";
  bankName?: string;
}

#/components/schemas/MerchantProcessing

OpenAPI
TypeScript

type: object
description: Processing configuration
properties:
  id:
    type: integer
  merchantId:
    type: integer
  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

|
export interface MerchantProcessing {
  id?: number;
  merchantId?: number;
  monthlyVolume?: number;
  averageTicket?: number;
  highTicket?: number;
  currentReserve?: number;
  reservePercentage?: number;
  processingLimit?: number;
  dailyLimit?: number;
  monthlyLimit?: number;
}

#/components/schemas/MerchantRates

OpenAPI
TypeScript

type: object
description: Rate structure
properties:
  id:
    type: integer
  merchantId:
    type: integer
  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

|
export interface MerchantRates {
  id?: number;
  merchantId?: number;
  discountRate?: number;
  transactionFee?: number;
  monthlyFee?: number;
  annualFee?: number;
  chargebackFee?: number;
  batchFee?: number;
  statementFee?: number;
  pciComplianceFee?: number;
  agentSplit?: number;
  isoSplit?: number;
  effectiveDate?: Date;
}

#/components/schemas/MerchantCompliance

OpenAPI
TypeScript

type: object
description: Compliance information
properties:
  id:
    type: integer
  merchantId:
    type: integer
  pciCompliant:
    type: boolean
    description: Whether merchant is PCI compliant
  pciLevel:
    type: string
    description: PCI compliance level
  lastPciDate:
    type: string
    format: date
    description: Last PCI compliance date
  nextPciDue:
    type: string
    format: date
    description: Next PCI compliance due date
  certificateUrl:
    type: string
    description: URL to PCI certificate
  documentsRequired:
    type: array
    items:
      type: object
      properties:
        type:
          type: string
        status:
          type: string
          enum:
            - pending
            - approved
            - expired
        expiryDate:
          type: string
          format: date

|
export interface MerchantCompliance {
  id?: number;
  merchantId?: number;
  /** Whether merchant is PCI compliant */
  pciCompliant?: boolean;
  /** PCI compliance level */
  pciLevel?: string;
  /** Last PCI compliance date */
  lastPciDate?: Date;
  /** Next PCI compliance due date */
  nextPciDue?: Date;
  /** URL to PCI certificate */
  certificateUrl?: string;
  documentsRequired?: {
    type?: string;
    status?: "pending" | "approved" | "expired";
    expiryDate?: Date;
  }[];
}

#/components/schemas/MerchantRiskMetrics

OpenAPI
TypeScript

type: object
description: Risk assessment metrics
properties:
  id:
    type: integer
  merchantId:
    type: integer
  riskScore:
    type: integer
    description: Overall risk score
  chargebackCount:
    type: integer
    description: Number of chargebacks
  chargebackRatio:
    type: number
    format: decimal
    description: Chargeback ratio
  refundRatio:
    type: number
    format: decimal
    description: Refund ratio
  suspiciousActivity:
    type: boolean
    description: Flag for suspicious activity
  lastRiskReview:
    type: string
    format: date
    description: Last risk review date
  nextRiskReview:
    type: string
    format: date
    description: Next risk review date

|
export interface MerchantRiskMetrics {
  id?: number;
  merchantId?: number;
  /** Overall risk score */
  riskScore?: number;
  /** Number of chargebacks */
  chargebackCount?: number;
  /** Chargeback ratio */
  chargebackRatio?: number;
  /** Refund ratio */
  refundRatio?: number;
  /** Flag for suspicious activity */
  suspiciousActivity?: boolean;
  /** Last risk review date */
  lastRiskReview?: Date;
  /** Next risk review date */
  nextRiskReview?: Date;
}

#/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/MerchantWithRelations

OpenAPI
TypeScript

allOf:
  - 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
    fromRef: "#/components/schemas/Merchant"
  - type: object
    properties:
      principals:
        type: array
        items:
          $ref: "#/components/schemas/MerchantPrincipal"
      addresses:
        type: array
        items:
          $ref: "#/components/schemas/MerchantAddress"
      banking:
        $ref: "#/components/schemas/MerchantBanking"
      processing:
        $ref: "#/components/schemas/MerchantProcessing"
      rates:
        type: array
        items:
          $ref: "#/components/schemas/MerchantRates"
      compliance:
        $ref: "#/components/schemas/MerchantCompliance"
      riskMetrics:
        $ref: "#/components/schemas/MerchantRiskMetrics"
      equipment:
        type: array
        items:
          $ref: "#/components/schemas/MerchantEquipment"
      notes:
        type: array
        items:
          $ref: "#/components/schemas/MerchantNote"
      documents:
        type: array
        items:
          $ref: "#/components/schemas/MerchantDocument"

|
export interface MerchantWithRelations_AllOf_0 {
  /** 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;
}

export interface MerchantWithRelations_AllOf_1 {
  principals?: MerchantPrincipal[];
  addresses?: MerchantAddress[];
  banking?: MerchantBanking;
  processing?: MerchantProcessing;
  rates?: MerchantRates[];
  compliance?: MerchantCompliance;
  riskMetrics?: MerchantRiskMetrics;
  equipment?: MerchantEquipment[];
  notes?: MerchantNote[];
  documents?: MerchantDocument[];
}

export type MerchantWithRelations = MerchantWithRelations_AllOf_0 &
  MerchantWithRelations_AllOf_1;

Route Source Code

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

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