openapi: 3.0.3
info:
  title: Sift Decisions PSP Merchant Management API
  description: 'Sift is a digital trust and safety platform that uses machine learning to detect and prevent online fraud and abuse - payment fraud, account takeover, account abuse, content abuse, and promotion abuse. This definition covers Sift''s public REST APIs: the Events API (stream user activity), the Score API (real-time Sift Scores 0-100 per abuse type), the Decisions API (apply/retrieve accept/watch/block decisions), the Workflow Status API, the legacy Labels API, the Verification API (OTP step-up), and the PSP Merchant Management API.


    MODELED SPECIFICATION - IMPORTANT: Sift does not publish a single machine-readable OpenAPI document. This file was MODELED by API Evangelist from Sift''s public developer documentation (developers.sift.com) and its officially maintained open-source client libraries (sift-python, sift-ruby, sift-java), which encode the exact paths, HTTP methods, and per-API versions. Endpoint paths, methods, versions, and authentication are confirmed against those sources. Request and response bodies are REPRESENTATIVE: Sift documents example payloads and field dictionaries rather than full JSON Schemas for most resources, so the schema shapes here are modeled from documented examples and may not enumerate every optional field. See review.yml for the confirmed-vs-modeled breakdown.


    Versioning is per API family: Events, Score, and Labels are on v205; Decisions, Workflows, and PSP Merchant Management are on v3; Verification is on v1.'
  version: '2026-07-12'
  contact:
    name: Sift Developer Documentation
    url: https://developers.sift.com/docs
  x-modeled: true
  x-modeled-by: API Evangelist
  x-modeled-sources:
  - https://developers.sift.com/docs
  - https://developers.sift.com/docs/curl/apis-overview
  - https://github.com/SiftScience/sift-python
servers:
- url: https://api.sift.com
  description: Sift production API (single public host)
security:
- apiKeyBasic: []
tags:
- name: PSP Merchant Management
  description: Manage sub-merchant profiles for payment service providers.
paths:
  /v3/accounts/{account_id}/psp_management/merchants:
    parameters:
    - $ref: '#/components/parameters/AccountId'
    get:
      operationId: listPspMerchants
      tags:
      - PSP Merchant Management
      summary: List PSP merchants
      description: Lists sub-merchant profiles for an account, paginated.
      parameters:
      - name: batch_size
        in: query
        required: false
        schema:
          type: integer
      - name: batch_token
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A paginated list of merchant profiles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PspMerchantList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createPspMerchant
      tags:
      - PSP Merchant Management
      summary: Create a PSP merchant
      description: Creates a new sub-merchant profile under an account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PspMerchant'
      responses:
        '201':
          description: The created merchant profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PspMerchant'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v3/accounts/{account_id}/psp_management/merchants/{merchant_id}:
    parameters:
    - $ref: '#/components/parameters/AccountId'
    - name: merchant_id
      in: path
      required: true
      description: The ID of the sub-merchant.
      schema:
        type: string
    get:
      operationId: getPspMerchant
      tags:
      - PSP Merchant Management
      summary: Get a PSP merchant
      description: Retrieves a specific sub-merchant profile.
      responses:
        '200':
          description: The merchant profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PspMerchant'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updatePspMerchant
      tags:
      - PSP Merchant Management
      summary: Update a PSP merchant
      description: Updates an existing sub-merchant profile.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PspMerchant'
      responses:
        '200':
          description: The updated merchant profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PspMerchant'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  parameters:
    AccountId:
      name: account_id
      in: path
      required: true
      description: Your numeric Sift Account ID.
      schema:
        type: string
  schemas:
    ApiError:
      type: object
      description: Modeled error envelope. Sift returns a numeric status and error_message.
      properties:
        status:
          type: integer
          description: Sift status code (0 indicates success; non-zero indicates an error).
        error_message:
          type: string
        time:
          type: integer
          format: int64
    PspMerchantList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PspMerchant'
        has_more:
          type: boolean
        next_ref:
          type: string
        total_results:
          type: integer
    PspMerchant:
      type: object
      description: PSP sub-merchant profile (modeled from documented examples).
      required:
      - id
      - name
      properties:
        id:
          type: string
          description: Your unique identifier for the sub-merchant.
        name:
          type: string
        description:
          type: string
        address:
          type: object
          additionalProperties: true
        category:
          type: string
        service_level:
          type: string
        status:
          type: string
          enum:
          - active
          - inactive
          - pending
        risk_profile:
          type: object
          properties:
            level:
              type: string
            score:
              type: number
              format: float
  securitySchemes:
    apiKeyBasic:
      type: http
      scheme: basic
      description: HTTP Basic authentication using your Sift REST API key as the username and an empty password. Ingestion APIs (Events, Score, Labels) also accept the key as $api_key in the JSON request body. Account-scoped APIs (Decisions, Workflows, PSP Merchant Management) require your numeric Account ID in the path in addition to the API key.