> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skinloop.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a player deposit session

> Server-side only. Requires deposits:create and an active, unfrozen merchant.
Enable deposit.completed and deposit.reverted on a webhook endpoint first.
playerReference must come from the merchant's authenticated player session,
never from an unchecked browser parameter. Allowed games must be a subset
of the API key's games. Reusing an Idempotency-Key returns the same session,
even after key rotation within the same merchant. A different request with
the same key returns 409. merchantReference is also unique per merchant.




## OpenAPI

````yaml /openapi.yaml post /v1/merchant-api/deposit-sessions
openapi: 3.1.0
info:
  title: Skinloop API
  version: 1.1.0-draft
  description: |
    Public contract for Skinloop merchant payments, hosted checkout status,
    merchant dashboard reads, and merchant webhooks. Skinloop never exposes
    credentials, private identifiers, trade URLs, or client tokens.
servers:
  - url: https://api.skinloop.io
    description: Production
security: []
tags:
  - name: Account
  - name: Payments
  - name: Checkout
  - name: Reporting
  - name: Dashboard
paths:
  /v1/merchant-api/deposit-sessions:
    post:
      tags:
        - Player deposits
      summary: Create a player deposit session
      description: >
        Server-side only. Requires deposits:create and an active, unfrozen
        merchant.

        Enable deposit.completed and deposit.reverted on a webhook endpoint
        first.

        playerReference must come from the merchant's authenticated player
        session,

        never from an unchecked browser parameter. Allowed games must be a
        subset

        of the API key's games. Reusing an Idempotency-Key returns the same
        session,

        even after key rotation within the same merchant. A different request
        with

        the same key returns 409. merchantReference is also unique per merchant.
      operationId: createPlayerDepositSession
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            minLength: 16
            maxLength: 255
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDepositSession'
      responses:
        '200':
          description: Idempotent replay
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepositSession'
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepositSession'
        '400':
          description: Invalid request or redirect outside the merchant's allowed origins
        '401':
          description: Invalid or revoked key, or missing required scope
        '403':
          description: Merchant is not active or is frozen
        '409':
          description: Conflicting idempotency key or merchant reference
        '429':
          description: Session creation rate limit reached; honor Retry-After
        '503':
          description: Service or required deposit webhook setup is unavailable
      security:
        - merchantApiKey: []
components:
  schemas:
    CreateDepositSession:
      type: object
      additionalProperties: false
      required:
        - merchantReference
        - playerReference
        - allowedGames
        - limits
      properties:
        merchantReference:
          type: string
          minLength: 1
          maxLength: 200
        playerReference:
          type: string
          minLength: 1
          maxLength: 200
          description: Opaque merchant-owned player ID, not an email or trade URL.
        allowedGames:
          type: array
          minItems: 1
          maxItems: 2
          uniqueItems: true
          items:
            type: string
            enum:
              - rust
              - cs2
        limits:
          type: object
          additionalProperties: false
          required:
            - min
            - max
            - currency
          properties:
            min:
              type: integer
              minimum: 1
              maximum: 100000000000
            max:
              type: integer
              minimum: 1
              maximum: 100000000000
            currency:
              type: string
              const: USD
          description: >-
            Inclusive USD-cent limits; max must be at least min. Provider
            eligibility still applies.
        expiresInSeconds:
          type: integer
          minimum: 300
          maximum: 86400
          default: 1800
        successUrl:
          type: string
          format: uri
        cancelUrl:
          type: string
          format: uri
    DepositSession:
      type: object
      required:
        - id
        - mode
        - merchantReference
        - playerReference
        - creditReference
        - eventSequence
        - limits
        - allowedGames
        - status
        - canCreditPlayer
        - hostedUrl
        - expiresAt
      properties:
        id:
          type: string
          pattern: ^ds_[A-Za-z0-9_-]{32}$
        mode:
          type: string
          const: balance_deposit
        merchantReference:
          type: string
        playerReference:
          type: string
        creditReference:
          type: string
          description: Stable unique reference for the merchant's player-ledger credit
        eventSequence:
          type: integer
          minimum: 0
        limits:
          type: object
          properties:
            min:
              type: integer
            max:
              type: integer
            currency:
              type: string
              const: USD
        acceptedAmount:
          type:
            - object
            - 'null'
          properties:
            value:
              type: integer
              description: Actual accepted selection value in USD cents
            currency:
              type: string
              const: USD
        allowedGames:
          type: array
          items:
            type: string
            enum:
              - cs2
              - rust
        status:
          type: string
          enum:
            - created
            - expired
            - pending
            - hold
            - completed
            - failed
            - reverted
        reason:
          type: string
          enum:
            - failed
            - declined
            - canceled
            - expired
            - provider_rejected
        canCreditPlayer:
          type: boolean
        holdUntil:
          type:
            - string
            - 'null'
          format: date-time
        hostedUrl:
          type: string
          format: uri
        continuation:
          type: object
          properties:
            available:
              type: boolean
            path:
              type: string
        expiresAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
  securitySchemes:
    merchantApiKey:
      type: http
      scheme: bearer
      bearerFormat: Skinloop API key
      description: >
        One API-key record may allow cs2, rust, or both. Every checkout's
        allowedGames must be a subset of that key's allowed games; use one key
        record rather than separate CS2 and Rust keys.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.