MarketSDK Payments API

openapi: 3.2.0
info:
  title: Marketsdk Payments API
  version: 1.0.0
  contact: {}
  description: 'Operations tagged Payments 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: Payments
paths:
  /v1/payments:
    get:
      operationId: listPayments
      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: order
        required: false
        in: query
        description: Only the payment for this order.
        schema:
          type: string
      - name: status
        required: false
        in: query
        schema:
          type: string
          enum:
          - awaiting_payment
          - succeeded
          - canceled
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentList'
        '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 payments, newest first
      tags:
      - Payments
    servers:
    - url: https://api.marketsdk.com
  /v1/payments/{id}:
    get:
      operationId: getPayment
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentObject'
        '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 payment
      tags:
      - Payments
    patch:
      operationId: updatePayment
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMetadataDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentObject'
        '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: Replace a payment's metadata
      tags:
      - Payments
    servers:
    - url: https://api.marketsdk.com
  /v1/payments/{id}/retry_release:
    post:
      description: For a release that failed, for example because the seller could not yet receive transfers. A release is also tried again by itself when the seller becomes able to receive payouts.
      operationId: retryPaymentRelease
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentObject'
        '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: Try a failed release of the seller's share again
      tags:
      - Payments
    servers:
    - url: https://api.marketsdk.com
  /v1/refunds:
    post:
      description: Recorded at once with status `pending`, then made at Stripe. If the seller's share was already released, the transfer is reversed in the same proportion, so your fee is given back in proportion too.
      operationId: createRefund
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRefundDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundObject'
        '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: Refund a payment, in full or in part
      tags:
      - Payments
    get:
      operationId: listRefunds
      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: payment
        required: false
        in: query
        schema:
          type: string
      - name: order
        required: false
        in: query
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundList'
        '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 refunds, newest first
      tags:
      - Payments
    servers:
    - url: https://api.marketsdk.com
  /v1/refunds/{id}:
    get:
      operationId: getRefund
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundObject'
        '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 refund
      tags:
      - Payments
    patch:
      operationId: updateRefund
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMetadataDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundObject'
        '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: Replace a refund's metadata
      tags:
      - Payments
    servers:
    - url: https://api.marketsdk.com
components:
  schemas:
    CreateRefundDto:
      type: object
      properties:
        payment:
          type: string
          description: The payment to refund. Give this or `order`.
          example: pay_034XtPDs7UJ0TXzTsdaHZa
        order:
          type: string
          description: The order whose payment to refund. Give this or `payment`.
          example: ord_034XtPDs7UJ0TXzTsdaHZa
        amount:
          type: number
          description: Minor units. Defaults to everything not yet refunded.
          minimum: 1
        reason:
          type: string
          enum:
          - requested_by_customer
          - duplicate
          - fraudulent
        metadata:
          type: object
          additionalProperties:
            type: string
    RefundObject:
      type: object
      properties:
        object:
          type: string
          enum:
          - refund
        id:
          type: string
          example: ref_034XtPDs7UJ0TXzTsdaHZa
        payment:
          type: string
        order:
          type: string
        amount:
          type: number
          description: Minor units.
        currency:
          type: string
          example: USD
        reason:
          type:
          - string
          - 'null'
          enum:
          - requested_by_customer
          - duplicate
          - fraudulent
          - null
        initiated_by:
          type: string
          enum:
          - api
          - order_cancelled
          - order_expired
          - late_payment
          - stripe
          description: '`api` for a refund you asked for; `order_cancelled` and `order_expired` when an order ended without completing; `late_payment` for a payment that arrived after its order lapsed; `stripe` for a refund made in the Stripe dashboard, which does not reverse the transfer.'
        status:
          type: string
          enum:
          - pending
          - succeeded
          - failed
          - canceled
        failure_reason:
          type:
          - string
          - 'null'
        transfer_reversal:
          description: Present when the refund came after release.
          anyOf:
          - $ref: '#/components/schemas/RefundReversalObject'
          - type: 'null'
        stripe:
          $ref: '#/components/schemas/RefundStripeObject'
        metadata:
          type: object
          additionalProperties:
            type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - object
      - id
      - payment
      - order
      - amount
      - currency
      - reason
      - initiated_by
      - status
      - failure_reason
      - transfer_reversal
      - stripe
      - metadata
      - created_at
      - updated_at
    RefundStripeObject:
      type: object
      properties:
        refund:
          type:
          - string
          - 'null'
        transfer_reversal:
          type:
          - string
          - 'null'
      required:
      - refund
      - transfer_reversal
    RefundReversalObject:
      type: object
      properties:
        amount:
          type: number
          description: Taken back from the seller's transfer. Minor units.
      required:
      - amount
    RefundList:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/RefundObject'
        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
    ErrorEnvelope:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      required:
      - error
    PaymentObject:
      type: object
      properties:
        object:
          type: string
          enum:
          - payment
        id:
          type: string
          example: pay_034XtPDs7UJ0TXzTsdaHZa
        order:
          type: string
        method:
          type: string
          enum:
          - checkout_session
          - payment_intent
        status:
          type: string
          enum:
          - awaiting_payment
          - succeeded
          - canceled
        amount:
          type: number
          description: Minor units.
        fee_amount:
          type: number
          description: The customer's platform fee. Minor units.
        currency:
          type: string
          example: USD
        checkout_url:
          type:
          - string
          - 'null'
          description: Stripe-hosted checkout. Shown only while payment is due.
        client_secret:
          type:
          - string
          - 'null'
          description: For Stripe Elements on your own page. Shown only while payment is due.
        last_failure:
          type:
          - string
          - 'null'
          description: Stripe's message for the last failed attempt to pay.
        amount_refunded:
          type: number
          description: Refunded or being refunded. Minor units.
        release:
          $ref: '#/components/schemas/PaymentReleaseObject'
        stripe:
          description: Ids of the objects on your Stripe account.
          allOf:
          - $ref: '#/components/schemas/PaymentStripeObject'
        metadata:
          type: object
          additionalProperties:
            type: string
        paid_at:
          type:
          - string
          - 'null'
          format: date-time
        canceled_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - object
      - id
      - order
      - method
      - status
      - amount
      - fee_amount
      - currency
      - checkout_url
      - client_secret
      - last_failure
      - amount_refunded
      - release
      - stripe
      - metadata
      - paid_at
      - canceled_at
      - created_at
      - updated_at
    PaymentReleaseObject:
      type: object
      properties:
        status:
          type:
          - string
          - 'null'
          enum:
          - held
          - releasing
          - released
          - failed
          - nothing_to_release
          - null
          description: Null until the buyer pays.
        amount:
          type: number
          description: Transferred to the seller's Stripe account. Minor units.
        amount_reversed:
          type: number
          description: Taken back from the seller for refunds after release. Minor units.
        failure:
          type:
          - string
          - 'null'
        released_at:
          type:
          - string
          - 'null'
          format: date-time
      required:
      - status
      - amount
      - amount_reversed
      - failure
      - released_at
    UpdateMetadataDto:
      type: object
      properties:
        metadata:
          type: object
          additionalProperties:
            type: string
      required:
      - metadata
    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
    PaymentStripeObject:
      type: object
      properties:
        payment_intent:
          type:
          - string
          - 'null'
        checkout_session:
          type:
          - string
          - 'null'
        charge:
          type:
          - string
          - 'null'
        transfer:
          type:
          - string
          - 'null'
      required:
      - payment_intent
      - checkout_session
      - charge
      - transfer
    PaymentList:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/PaymentObject'
        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
  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