openapi: 3.1.0
info:
  title: Remitian Tax Payment Accounts Jurisdictions API
  description: The Remitian Tax Payment API enables tax software providers and accounting firms to embed tax payment initiation, validation, and confirmation directly within their existing platforms. Described as the "Stripe for tax," the API acts as a unified gateway to multiple tax authorities, replacing manual government portal logins with automated, jurisdiction-aware payment infrastructure. It provides real-time status updates via webhooks and bank-grade audit logs to track every payment from initiation to completion. Built by accountants for accountants, the API supports managing payments across multiple tax jurisdictions from a single integration point.
  version: 1.0.0
  contact:
    name: Remitian Support
    url: https://help.remitian.com
  termsOfService: https://remitian.com/terms
servers:
- url: https://api.remitian.com
  description: Production Server
security:
- bearerAuth: []
tags:
- name: Jurisdictions
  description: Retrieve and manage supported tax jurisdictions and their associated payment requirements and routing rules.
paths:
  /v1/jurisdictions:
    get:
      operationId: listJurisdictions
      summary: List supported jurisdictions
      description: Retrieve the list of tax jurisdictions supported by Remitian, including federal, state, provincial, and local authorities. Each jurisdiction entry includes its payment requirements, accepted tax types, and routing configuration.
      tags:
      - Jurisdictions
      parameters:
      - name: country
        in: query
        description: Filter by country code (ISO 3166-1 alpha-2)
        schema:
          type: string
          example: US
      - name: type
        in: query
        description: Filter by jurisdiction type
        schema:
          type: string
          enum:
          - federal
          - state
          - provincial
          - local
      - $ref: '#/components/parameters/PageLimit'
      - $ref: '#/components/parameters/PageOffset'
      responses:
        '200':
          description: A list of supported jurisdictions
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Jurisdiction'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/jurisdictions/{jurisdictionId}:
    get:
      operationId: getJurisdiction
      summary: Retrieve a jurisdiction
      description: Retrieve detailed information about a specific tax jurisdiction, including accepted tax types, payment deadlines, required fields, and routing details.
      tags:
      - Jurisdictions
      parameters:
      - name: jurisdictionId
        in: path
        required: true
        description: Unique identifier of the jurisdiction
        schema:
          type: string
      responses:
        '200':
          description: Jurisdiction details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Jurisdiction'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    PageLimit:
      name: limit
      in: query
      description: Maximum number of results to return per page
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
    PageOffset:
      name: offset
      in: query
      description: Number of results to skip for pagination
      schema:
        type: integer
        minimum: 0
        default: 0
  responses:
    Unauthorized:
      description: Missing or invalid authentication credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Requested resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Jurisdiction:
      type: object
      properties:
        id:
          type: string
          description: Unique jurisdiction identifier
        name:
          type: string
          description: Display name of the tax jurisdiction
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code
          pattern: ^[A-Z]{2}$
        type:
          type: string
          description: Level of government
          enum:
          - federal
          - state
          - provincial
          - local
        taxTypes:
          type: array
          description: Tax types accepted by this jurisdiction
          items:
            type: string
        requiredFields:
          type: array
          description: Fields required for payment submission to this jurisdiction
          items:
            type: string
        paymentMethods:
          type: array
          description: Accepted payment methods
          items:
            type: string
        active:
          type: boolean
          description: Whether this jurisdiction is currently active
    Pagination:
      type: object
      properties:
        total:
          type: integer
          description: Total number of results
        limit:
          type: integer
          description: Maximum results per page
        offset:
          type: integer
          description: Current offset
        hasMore:
          type: boolean
          description: Whether more results are available
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code
            message:
              type: string
              description: Human-readable error message
            details:
              type: array
              description: Detailed error information
              items:
                type: object
                properties:
                  field:
                    type: string
                    description: Field related to the error
                  message:
                    type: string
                    description: Detail about the field error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: API key authentication using a Bearer token provided by Remitian during partner onboarding.
externalDocs:
  description: Remitian Integration Documentation
  url: https://remitian.com/integrations/integrate-remitian