/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

merchantId path integer

The ID of the merchant to retrieve

Optional Parameters

Click here to view an exhaustive list of all available parameters

x-account-id header string

The account ID for the request

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: The account ID for the request
required: false

|
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