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. Use these endpoints

    to verify that a Roku user holds a valid entitlement to your content, to issue refunds, to update

    billing cycles, and to grant service credits. All endpoints require a Roku-issued Partner API

    Key.


    Roku Pay handles payment processing, subscription state, and tax calculation on behalf of the

    publisher; channels query these endpoints from their authentication backends rather than from

    BrightScript directly.

    '
  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
    Error:
      type: object
      properties:
        status:
          type: string
        errorCode:
          type: integer
        errorMessage:
          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
  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.

        '