> ## 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 USD hosted checkout session

> The merchant is derived from the API key. Amounts are integer cents and only USD is supported.



## OpenAPI

````yaml /openapi.yaml post /v1/merchant-api/checkouts
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: Payments
  - name: Checkout
  - name: Reporting
  - name: Dashboard
paths:
  /v1/merchant-api/checkouts:
    post:
      tags:
        - Checkout
      summary: Create a USD hosted checkout session
      description: >-
        The merchant is derived from the API key. Amounts are integer cents and
        only USD is supported.
      operationId: createMerchantCheckout
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateHostedCheckoutRequest'
      responses:
        '200':
          description: Idempotent replay
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HostedCheckout'
        '201':
          description: Checkout created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HostedCheckout'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
        - merchantApiKey: []
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        minLength: 16
        maxLength: 255
  schemas:
    CreateHostedCheckoutRequest:
      type: object
      additionalProperties: false
      required:
        - merchantOrderId
        - amount
        - allowedGames
        - successUrl
        - cancelUrl
      properties:
        merchantOrderId:
          type: string
          minLength: 1
          maxLength: 200
        amount:
          $ref: '#/components/schemas/UsdAmount'
        allowedGames:
          type: array
          minItems: 1
          maxItems: 2
          uniqueItems: true
          items:
            type: string
            enum:
              - cs2
              - rust
        successUrl:
          type: string
          format: uri
        cancelUrl:
          type: string
          format: uri
        metadata:
          type: object
          maxProperties: 20
          additionalProperties:
            oneOf:
              - type: string
                maxLength: 500
              - type: number
              - type: boolean
        expiresInSeconds:
          type: integer
          minimum: 300
          maximum: 86400
    HostedCheckout:
      type: object
      additionalProperties: false
      required:
        - id
        - merchantOrderId
        - amount
        - allowedGames
        - hostedUrl
        - successUrl
        - cancelUrl
        - metadata
        - status
        - expiresAt
        - createdAt
        - updatedAt
        - reservationRequired
        - fulfillmentAllowed
        - holdUntil
        - warnings
      properties:
        id:
          type: string
          pattern: ^cs_[A-Za-z0-9_-]{32,}$
        merchantOrderId:
          type: string
        amount:
          $ref: '#/components/schemas/UsdAmount'
        allowedGames:
          type: array
          items:
            type: string
            enum:
              - cs2
              - rust
        hostedUrl:
          type: string
          format: uri
        successUrl:
          type: string
          format: uri
        cancelUrl:
          type: string
          format: uri
        metadata:
          type: object
        status:
          type: string
          enum:
            - created
            - initiated
            - pending
            - active
            - hold
            - completed
            - canceled
            - declined
            - failed
            - reverted
            - expired
            - reconciliation_required
        expiresAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        reservationRequired:
          type: boolean
          description: >-
            True when the checkout includes CS2 and the merchant order must
            remain reserved through completion
        fulfillmentAllowed:
          type: boolean
          description: True only after payment.completed
        holdUntil:
          type:
            - string
            - 'null'
          format: date-time
          description: For CS2 hold state
          exactly eight days after the provider hold timestamp: null
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/MerchantWarning'
      example:
        id: cs_0123456789abcdefghijklmnopqrstuvwxyz
        merchantOrderId: order_123
        amount:
          value: 4999
          currency: USD
        allowedGames:
          - cs2
          - rust
        hostedUrl: https://checkout.skinloop.io/cs_0123456789abcdefghijklmnopqrstuvwxyz
        successUrl: https://merchant.example/paid
        cancelUrl: https://merchant.example/canceled
        metadata: {}
        status: created
        expiresAt: '2026-09-18T13:00:00Z'
        createdAt: '2026-09-18T12:00:00Z'
        updatedAt: '2026-09-18T12:00:00Z'
        reservationRequired: true
        fulfillmentAllowed: false
        holdUntil: null
        warnings: []
    UsdAmount:
      type: object
      additionalProperties: false
      required:
        - value
        - currency
      properties:
        value:
          type: integer
          minimum: 1
          maximum: 100000000000
          description: Integer cents, so 4999 means 49.99 USD.
        currency:
          type: string
          const: USD
    MerchantWarning:
      type: object
      additionalProperties: false
      required:
        - code
        - severity
        - message
        - action
      properties:
        code:
          type: string
          enum:
            - checkout_expiring
            - selected_value_above_target
            - trade_pending
            - trade_hold_pending
            - reconciliation_required
        severity:
          type: string
          enum:
            - info
            - warning
            - action_required
        message:
          type: string
        action:
          type: string
        documentationUrl:
          type: string
          format: uri
        details:
          type: object
          additionalProperties:
            oneOf:
              - type: string
              - type: number
    Error:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
            message:
              type: string
            request_id:
              type: string
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication or signature verification failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Checkout origin is not allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    IdempotencyConflict:
      description: Idempotency key was previously used with a different request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: Checkout service is not configured or unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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.

````