Roku Validation API

openapi: 3.2.0
info:
  title: Roku Pay Web Services Validation API
  version: '1.0'
  description: 'Roku Pay Web Services provide server-to-server APIs for billing, subscription management,

    transaction validation, and entitlement checks for monetized Roku channels.'
  contact:
    name: Roku Pay Support
    url: https://developer.roku.com/docs/developer-program/roku-pay/overview.md
  x-generated-from: documentation
  x-source-url: https://developer.roku.com/dev/docs/roku-web-service
servers:
- url: https://apipub.roku.com/listen/transaction-service.svc
  description: Roku Pay production transaction service
security:
- PartnerAPIKey: []
tags:
- name: Validation
  description: Transaction and refund validation
paths:
  /validate-transaction/{partnerAPIKey}/{transactionId}:
    get:
      operationId: validateTransaction
      summary: Roku Validate Transaction
      description: 'Verifies that a customer holds a valid entitlement to a product purchased through Roku Pay.

        Returns the purchase status, expiration date, and source channel of the transaction.

        Channels must call this from their backend before granting entitled access to content.'
      tags:
      - Validation
      parameters:
      - name: partnerAPIKey
        in: path
        required: true
        description: The publisher's Roku-issued Partner API key.
        schema:
          type: string
      - name: transactionId
        in: path
        required: true
        description: The unique transaction identifier (up to 1024 ASCII bytes) returned to the channel by the Roku ChannelStore component at purchase time.
        schema:
          type: string
      responses:
        '200':
          description: Transaction validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionValidation'
            application/xml:
              schema:
                $ref: '#/components/schemas/TransactionValidation'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /validate-refund/{partnerAPIKey}/{refundId}:
    get:
      operationId: validateRefund
      summary: Roku Validate Refund
      description: Confirms whether a refund has been successfully issued for a previous transaction.
      tags:
      - Validation
      parameters:
      - name: partnerAPIKey
        in: path
        required: true
        description: The publisher's Roku-issued Partner API key.
        schema:
          type: string
      - name: refundId
        in: path
        required: true
        description: The Roku-issued refund identifier.
        schema:
          type: string
      responses:
        '200':
          description: Refund validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundValidation'
            application/xml:
              schema:
                $ref: '#/components/schemas/RefundValidation'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    RefundValidation:
      type: object
      description: Result of a refund-validation request.
      x-schema-source: documentation
      properties:
        status:
          type: string
        errorCode:
          type: integer
        errorMessage:
          type: string
        refundId:
          type: string
        transactionId:
          type: string
        refundDate:
          type: string
          format: date-time
        refundAmount:
          type: number
          format: float
        currency:
          type: string
        refundReason:
          type: string
    TransactionValidation:
      type: object
      description: Result of a transaction-validation request.
      x-schema-source: documentation
      properties:
        status:
          type: string
          description: Operation status (Success, Failure).
        errorCode:
          type: integer
          description: Numeric Roku error code on failure.
        errorMessage:
          type: string
        transactionId:
          type: string
          description: The transaction identifier that was validated.
        productId:
          type: string
          description: The Roku product code for the entitled product.
        productName:
          type: string
        purchaseDate:
          type: string
          format: date-time
        expirationDate:
          type: string
          format: date-time
          description: When the entitlement expires (for subscriptions and time-limited rentals).
        purchaseStatus:
          type: string
          enum:
          - Active
          - Inactive
          - Pending_Active
          - Pending_Inactive
        isEntitled:
          type: boolean
          description: Whether the customer currently has access to the product.
        purchaseChannel:
          type: string
          description: How the purchase was initiated (e.g., Device, Web, InstantSignup).
        purchaseContext:
          type: string
          description: Context flags identifying the purchase source.
        rokuCustomerId:
          type: string
          description: The Roku-issued anonymized customer identifier.
        amount:
          type: number
          format: float
        currency:
          type: string
        tax:
          type: number
          format: float
    Error:
      type: object
      properties:
        status:
          type: string
        errorCode:
          type: integer
        errorMessage:
          type: string
  responses:
    Error:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
        application/xml:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    PartnerAPIKey:
      type: apiKey
      in: query
      name: partnerAPIKey
      description: 'Roku-issued Partner API Key. For GET endpoints the key is included in the URL path; for

        POST endpoints it is included in the request body. Channels obtain this key from the Roku

        Developer Dashboard.

        '