Splitit Merchant Management API

openapi: 3.0.3
info:
  title: Splitit Account Management System Authentication Merchant Management API
  description: API for onboarding and managing sub-merchants on the Splitit platform. Enables payment facilitators and marketplace operators to add merchant partners, upload compliance documents, send onboarding invitations, monitor approval status, retrieve pending accounts, and generate time-limited secure login links for merchant portal access.
  version: '1.0'
  contact:
    name: Splitit Developer Support
    url: https://developers.splitit.com/
  license:
    name: Proprietary
servers:
- url: https://webapi.production.splitit.com
  description: Production
- url: https://web-api-v3.sandbox.splitit.com
  description: Sandbox
security:
- bearerAuth: []
tags:
- name: Merchant Management
  description: Onboard and manage merchant partners
paths:
  /api/ams/structure:
    get:
      tags:
      - Merchant Management
      operationId: getMerchantPartnerStructure
      summary: Structure for Add Merchant Partner Requests
      description: Retrieve the required fields and structure for creating merchant partner requests. Use this endpoint to understand required and optional fields before calling Add Merchant Partner.
      responses:
        '200':
          description: Merchant partner request structure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantStructureResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/ams/merchants:
    post:
      tags:
      - Merchant Management
      operationId: addMerchantPartner
      summary: Add Merchant Partner
      description: Onboard a new sub-merchant partner to the Splitit platform. Provides required business and compliance information for the new merchant. Payment facilitators and marketplace operators use this endpoint to expand their merchant network on Splitit.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddMerchantPartnerRequest'
      responses:
        '200':
          description: Merchant partner added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantPartnerResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/ams/merchants/{merchantId}/documents:
    post:
      tags:
      - Merchant Management
      operationId: uploadDocuments
      summary: Upload Documents
      description: Submit agreements and compliance documentation for a merchant partner. Supports uploading required KYC/KYB documents and agreements needed for Splitit onboarding approval.
      parameters:
      - name: merchantId
        in: path
        required: true
        description: The merchant partner identifier
        schema:
          type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                documentType:
                  type: string
                  description: Type of document being uploaded
                  example: agreement
                file:
                  type: string
                  format: binary
                  description: The document file to upload
      responses:
        '200':
          description: Document uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentUploadResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /api/ams/merchants/{merchantId}/invite:
    post:
      tags:
      - Merchant Management
      operationId: sendInviteEmail
      summary: Send Invite Emails
      description: Distribute prefilled onboarding forms to merchant partners via email. The invite email contains a link to a prefilled application form that the merchant can complete to finalize their Splitit onboarding.
      parameters:
      - name: merchantId
        in: path
        required: true
        description: The merchant partner identifier
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  description: Email address to send the invite to (defaults to merchant email)
      responses:
        '200':
          description: Invite email sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InviteEmailResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/ams/merchants/{merchantId}/status:
    get:
      tags:
      - Merchant Management
      operationId: getOnboardingStatus
      summary: Get Onboarding Status
      description: Check the approval progress of a merchant partner account. Returns the current onboarding status including any pending items or required actions.
      parameters:
      - name: merchantId
        in: path
        required: true
        description: The merchant partner identifier
        schema:
          type: string
      responses:
        '200':
          description: Merchant onboarding status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingStatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/ams/merchants/pending:
    get:
      tags:
      - Merchant Management
      operationId: getPendingAccounts
      summary: Get Pending Accounts
      description: Retrieve all merchant accounts that are still pending Splitit approval. Use this endpoint to monitor the onboarding pipeline and follow up with merchants who have not yet completed the process.
      responses:
        '200':
          description: List of pending merchant accounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PendingAccountsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/ams/merchants/{merchantId}/login-link:
    post:
      tags:
      - Merchant Management
      operationId: generateDirectLoginLink
      summary: Generate Direct Login Link
      description: Create a secure, time-limited portal access link for a merchant partner without requiring credentials. The generated link provides direct access to the Splitit Merchant Hub for the specified merchant.
      parameters:
      - name: merchantId
        in: path
        required: true
        description: The merchant partner identifier
        schema:
          type: string
      responses:
        '200':
          description: Login link generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginLinkResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    InviteEmailResponse:
      type: object
      properties:
        success:
          type: boolean
        email:
          type: string
          format: email
        sentAt:
          type: string
          format: date-time
    MerchantStructureResponse:
      type: object
      properties:
        requiredFields:
          type: array
          items:
            type: object
            properties:
              fieldName:
                type: string
              fieldType:
                type: string
              isRequired:
                type: boolean
              description:
                type: string
    OnboardingStatusResponse:
      type: object
      properties:
        merchantId:
          type: string
        status:
          type: string
          enum:
          - Pending
          - UnderReview
          - Approved
          - Rejected
          - RequiresInfo
        pendingItems:
          type: array
          items:
            type: string
          description: List of items required to complete onboarding
        updatedAt:
          type: string
          format: date-time
    Address:
      type: object
      properties:
        addressLine1:
          type: string
        addressLine2:
          type: string
        city:
          type: string
        state:
          type: string
        country:
          type: string
          example: US
        zip:
          type: string
    DocumentUploadResponse:
      type: object
      properties:
        documentId:
          type: string
          description: Unique identifier for the uploaded document
        documentType:
          type: string
        uploadedAt:
          type: string
          format: date-time
        status:
          type: string
    PendingAccountsResponse:
      type: object
      properties:
        merchants:
          type: array
          items:
            $ref: '#/components/schemas/MerchantPartnerResponse'
        totalCount:
          type: integer
    MerchantPartnerResponse:
      type: object
      properties:
        merchantId:
          type: string
          description: Unique identifier assigned to the new merchant
        status:
          type: string
          description: Initial onboarding status
        businessName:
          type: string
        email:
          type: string
          format: email
        createdAt:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      properties:
        errorCode:
          type: string
        message:
          type: string
    LoginLinkResponse:
      type: object
      properties:
        loginUrl:
          type: string
          format: uri
          description: Time-limited secure login URL for the merchant portal
        expiresAt:
          type: string
          format: date-time
          description: Expiration time of the login link
    AddMerchantPartnerRequest:
      type: object
      required:
      - businessName
      - email
      properties:
        businessName:
          type: string
          description: Legal business name of the merchant
        businessType:
          type: string
          description: Type of business entity
        email:
          type: string
          format: email
          description: Primary contact email for the merchant
        phone:
          type: string
          description: Business phone number
        businessAddress:
          $ref: '#/components/schemas/Address'
        website:
          type: string
          format: uri
          description: Merchant website URL
        taxId:
          type: string
          description: Tax identification number
        contactName:
          type: string
          description: Name of the primary contact person
  responses:
    Unauthorized:
      description: Unauthorized - token is not authorized or is expired
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Not Found - resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Forbidden - no right to access this resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnprocessableEntity:
      description: Unprocessable Entity - validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT