MarketSDK Trust API

openapi: 3.2.0
info:
  title: Marketsdk Trust API
  version: 1.0.0
  contact: {}
  description: 'Operations tagged Trust across 2 of this provider''s published API definitions: marketsdk-openapi.json, marketsdk-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.marketsdk.com
tags:
- name: Trust
paths:
  /v1/sellers/{id}/verifications:
    post:
      description: Creates a Stripe Identity session on your Stripe account and returns its page, once. Only the outcome and the session id are kept; no document image or document data. When seller verification is on, a seller can publish only once verified.
      operationId: createVerification
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVerificationDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Not allowed with this key, or the marketplace is read-only.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: The object is not in a state that allows this.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Start a seller's identity verification
      tags:
      - Trust
    servers:
    - url: https://api.marketsdk.com
  /v1/verifications:
    get:
      operationId: listVerifications
      parameters:
      - name: limit
        required: false
        in: query
        schema:
          minimum: 1
          maximum: 100
          default: 20
          type: number
      - name: starting_after
        required: false
        in: query
        description: The `next_cursor` of the previous page.
        schema:
          type: string
      - name: seller
        required: false
        in: query
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationList'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: List identity verifications, newest first
      tags:
      - Trust
    servers:
    - url: https://api.marketsdk.com
  /v1/verifications/{id}:
    get:
      operationId: getVerification
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Retrieve an identity verification
      tags:
      - Trust
    servers:
    - url: https://api.marketsdk.com
  /v1/verifications/{id}/cancel:
    post:
      operationId: cancelVerification
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: The object is not in a state that allows this.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Cancel a verification the seller has not submitted
      tags:
      - Trust
    servers:
    - url: https://api.marketsdk.com
  /v1/disputes:
    get:
      description: Filter by `stage` for a queue.
      operationId: listDisputes
      parameters:
      - name: limit
        required: false
        in: query
        schema:
          minimum: 1
          maximum: 100
          default: 20
          type: number
      - name: starting_after
        required: false
        in: query
        description: The `next_cursor` of the previous page.
        schema:
          type: string
      - name: stage
        required: false
        in: query
        schema:
          type: string
          enum:
          - evidence
          - awaiting_decision
          - decided
      - name: order
        required: false
        in: query
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeList'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: List disputes, newest first
      tags:
      - Trust
    servers:
    - url: https://api.marketsdk.com
  /v1/disputes/{id}:
    get:
      operationId: getDispute
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Retrieve a dispute
      tags:
      - Trust
    servers:
    - url: https://api.marketsdk.com
  /v1/disputes/{id}/evidence:
    post:
      description: Only while the dispute is in its evidence stage.
      operationId: addDisputeEvidence
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddEvidenceDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeEvidenceObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Not allowed with this key, or the marketplace is read-only.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: The object is not in a state that allows this.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Add evidence from one side
      tags:
      - Trust
    get:
      operationId: listDisputeEvidence
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeEvidenceList'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: A dispute's evidence, oldest first
      tags:
      - Trust
    servers:
    - url: https://api.marketsdk.com
  /v1/disputes/{id}/close_evidence:
    post:
      operationId: closeDisputeEvidence
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: The object is not in a state that allows this.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: End the evidence stage early
      tags:
      - Trust
    servers:
    - url: https://api.marketsdk.com
  /v1/disputes/{id}/decide:
    post:
      description: 'Your team''s decision: who it went against, in writing, and with payments on, how much goes back to the buyer. On a claimed order, deciding against the party who disputed upholds the claim and completes the order; deciding against the claimant cancels it.'
      operationId: decideDispute
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DecideDisputeDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: The object is not in a state that allows this.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Decide a dispute
      tags:
      - Trust
    servers:
    - url: https://api.marketsdk.com
  /v1/orders/{id}/disputes:
    post:
      description: 'On a claimed order, by the party who did not claim: the order becomes disputed. On a completed order, by either party inside the dispute window: the order stays completed.'
      operationId: openDispute
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenDisputeDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Not allowed with this key, or the marketplace is read-only.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: The object is not in a state that allows this.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Dispute an order
      tags:
      - Trust
    servers:
    - url: https://api.marketsdk.com
components:
  schemas:
    DisputeEvidenceObject:
      type: object
      properties:
        object:
          type: string
          enum:
          - dispute_evidence
        id:
          type: string
          example: dev_034XtPDs7UJ0TXzTsdaHZa
        dispute:
          type: string
        party:
          type: string
          enum:
          - buyer
          - seller
        author:
          type: string
        body:
          type:
          - string
          - 'null'
        links:
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time
      required:
      - object
      - id
      - dispute
      - party
      - author
      - body
      - links
      - created_at
    DecideDisputeDto:
      type: object
      properties:
        against:
          type: string
          enum:
          - buyer
          - seller
          description: Who the decision went against. They get a dispute_lost reputation event; the other party gets dispute_won.
        note:
          type: string
          description: The written decision, kept with the dispute.
          maxLength: 5000
        refund_amount:
          type: number
          description: 'Payments on only. Minor units to refund to the buyer; the rest goes to the seller. Defaults: a claimed order whose claim is upheld refunds nothing; one whose claim is rejected refunds everything; a dispute on a completed order refunds nothing.'
          minimum: 0
        decided_by:
          type: string
          description: Who on your team decided, for the record. Up to 200 characters.
          maxLength: 200
      required:
      - against
      - note
    VerificationObject:
      type: object
      properties:
        object:
          type: string
          enum:
          - verification
        id:
          type: string
          example: ver_034XtPDs7UJ0TXzTsdaHZa
        seller:
          type: string
        status:
          type: string
          enum:
          - requires_input
          - processing
          - verified
          - canceled
          description: Stripe Identity's status for this attempt. `requires_input` with a `last_error_code` means the seller must try again.
        last_error_code:
          type:
          - string
          - 'null'
          description: Stripe's reason the last attempt failed, such as `document_expired`.
        url:
          type:
          - string
          - 'null'
          description: The Stripe-hosted verification page. Returned only when the verification is created. Send the seller there.
        stripe_session:
          type:
          - string
          - 'null'
          description: The Stripe Identity verification session.
        verified_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - object
      - id
      - seller
      - status
      - last_error_code
      - url
      - stripe_session
      - verified_at
      - created_at
      - updated_at
    DisputeObject:
      type: object
      properties:
        object:
          type: string
          enum:
          - dispute
        id:
          type: string
          example: dsp_034XtPDs7UJ0TXzTsdaHZa
        order:
          type: string
        kind:
          type: string
          enum:
          - claimed_order
          - completed_order
        opened_by:
          type: string
          enum:
          - buyer
          - seller
        opener:
          type: string
        reason:
          type:
          - string
          - 'null'
          description: Null once the opener's data is erased.
        stage:
          type: string
          enum:
          - evidence
          - awaiting_decision
          - decided
        evidence_due_at:
          type: string
          format: date-time
        decision_due_at:
          type:
          - string
          - 'null'
          format: date-time
        overdue:
          type: boolean
          description: True once the decision time limit has passed with no decision.
        evidence_count:
          type: number
          description: Pieces of evidence given so far.
        decision:
          anyOf:
          - $ref: '#/components/schemas/DisputeDecisionObject'
          - type: 'null'
        card_disputes:
          description: Card disputes on the same order, linked here but separate.
          type: array
          items:
            $ref: '#/components/schemas/CardDisputeObject'
        metadata:
          type: object
          additionalProperties:
            type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - object
      - id
      - order
      - kind
      - opened_by
      - opener
      - reason
      - stage
      - evidence_due_at
      - decision_due_at
      - overdue
      - evidence_count
      - decision
      - card_disputes
      - metadata
      - created_at
      - updated_at
    VerificationList:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/VerificationObject'
        has_more:
          type: boolean
          description: Whether another page follows.
        next_cursor:
          type:
          - string
          - 'null'
          description: Pass as `starting_after` (or `cursor` for search) to get the next page.
      required:
      - object
      - data
      - has_more
      - next_cursor
    OpenDisputeDto:
      type: object
      properties:
        actor:
          type: string
          description: The buyer or seller opening the dispute.
          example: buy_034XtPDs7UJ0TXzTsdaHZa
        reason:
          type: string
          description: What went wrong, in their words.
          maxLength: 2000
        metadata:
          type: object
          additionalProperties:
            type: string
      required:
      - actor
      - reason
    ErrorEnvelope:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      required:
      - error
    DisputeDecisionObject:
      type: object
      properties:
        against:
          type: string
          enum:
          - buyer
          - seller
        outcome:
          type: string
          enum:
          - claim_upheld
          - claim_rejected
          - decided
          description: '`decided` for a dispute on a completed order, which has no claim to uphold.'
        refund_amount:
          type:
          - number
          - 'null'
          description: Refunded to the buyer by this decision. Null with payments off.
        note:
          type: string
        decided_by:
          type:
          - string
          - 'null'
        decided_at:
          type: string
          format: date-time
      required:
      - against
      - outcome
      - refund_amount
      - note
      - decided_by
      - decided_at
    CardDisputeObject:
      type: object
      properties:
        object:
          type: string
          enum:
          - card_dispute
        id:
          type: string
          example: cdp_034XtPDs7UJ0TXzTsdaHZa
        order:
          type: string
        stripe_dispute:
          type: string
          description: The dispute's id on your Stripe account.
        amount:
          type: number
        currency:
          type: string
        reason:
          type: string
        status:
          type: string
          description: Stripe's status, such as needs_response, won, or lost.
        created_at:
          type: string
          format: date-time
      required:
      - object
      - id
      - order
      - stripe_dispute
      - amount
      - currency
      - reason
      - status
      - created_at
    DisputeList:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/DisputeObject'
        has_more:
          type: boolean
          description: Whether another page follows.
        next_cursor:
          type:
          - string
          - 'null'
          description: Pass as `starting_after` (or `cursor` for search) to get the next page.
      required:
      - object
      - data
      - has_more
      - next_cursor
    ErrorBody:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable. Never changes once published.
          example: resource_missing
        message:
          type: string
          description: For people.
          example: No seller has that id.
        param:
          type: string
          description: The request field at fault.
          example: seller
        request_id:
          type: string
          example: req_7Gq0mR2s9xVbN4kT1pLc
      required:
      - code
      - message
      - request_id
    DisputeEvidenceList:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/DisputeEvidenceObject'
        has_more:
          type: boolean
          description: Whether another page follows.
        next_cursor:
          type:
          - string
          - 'null'
          description: Pass as `starting_after` (or `cursor` for search) to get the next page.
      required:
      - object
      - data
      - has_more
      - next_cursor
    AddEvidenceDto:
      type: object
      properties:
        actor:
          type: string
          description: The buyer or seller giving evidence.
        body:
          type: string
          maxLength: 10000
        links:
          maxItems: 5
          description: Links to files the party provided, such as photos you store. HTTPS only.
          type: array
          items:
            type: string
      required:
      - actor
      - body
    CreateVerificationDto:
      type: object
      properties:
        return_url:
          type: string
          description: Where Stripe sends the seller after the verification page.
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: API key
      type: http
      description: 'An API key: msk_test_sk_…, msk_live_sk_…, or a publishable msk_…_pk_… key where allowed.'
x-refined-from:
- marketsdk-openapi.json
- marketsdk-openapi.json
x-stripe-permissions:
- permission: accounts
  category: Core
  resource: Accounts
  level: Write
  used_for: Create sellers' connected accounts and read their status
- permission: account_links
  category: Connect
  resource: Account Links
  level: Write
  used_for: Onboarding links for sellers
- permission: transfers
  category: Connect
  resource: Transfers
  level: Write
  used_for: Release funds to a seller, and reverse them on a refund
- permission: payment_intents
  category: Core
  resource: Payment Intents
  level: Write
  used_for: Buyer payments, and cancelling unpaid ones
- permission: charges_and_refunds
  category: Core
  resource: Charges and Refunds
  level: Write
  used_for: Refunds, full and partial
- permission: checkout_sessions
  category: Checkout
  resource: Checkout Sessions
  level: Write
  used_for: Hosted checkout, and expiring unpaid sessions
- permission: identity_verification_sessions
  category: Identity
  resource: Verification Sessions and Reports
  level: Write
  used_for: Seller identity verification
- permission: disputes
  category: Core
  resource: Disputes
  level: Read
  used_for: Reading card disputes, to link them to orders
- permission: webhook_endpoints
  category: Webhook Endpoints
  resource: Webhook Endpoints
  level: Write
  used_for: Registering our endpoint on your account