openapi: 3.1.0
info:
  title: Remitian Tax Payment Accounts 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: Accounts
  description: Manage client accounts and their linked bank connections for tax payment processing.
paths:
  /v1/accounts:
    get:
      operationId: listAccounts
      summary: List client accounts
      description: Retrieve a list of client accounts registered for tax payment processing, including their linked bank connections and verification status.
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/PageLimit'
      - $ref: '#/components/parameters/PageOffset'
      responses:
        '200':
          description: A list of client accounts
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Account'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createAccount
      summary: Create a client account
      description: Register a new client account for tax payment processing. The account must be linked to a verified bank connection before payments can be initiated.
      tags:
      - Accounts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountCreateRequest'
      responses:
        '201':
          description: Account created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/accounts/{accountId}:
    get:
      operationId: getAccount
      summary: Retrieve a client account
      description: Retrieve the details of a specific client account, including linked bank connections and payment history summary.
      tags:
      - Accounts
      parameters:
      - name: accountId
        in: path
        required: true
        description: Unique identifier of the client account
        schema:
          type: string
      responses:
        '200':
          description: Account details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Account:
      type: object
      properties:
        id:
          type: string
          description: Unique account identifier
        name:
          type: string
          description: Display name for the client account
        email:
          type: string
          format: email
          description: Contact email for the account
        bankConnections:
          type: array
          description: Linked and verified bank connections
          items:
            $ref: '#/components/schemas/BankConnection'
        status:
          type: string
          description: Account verification status
          enum:
          - pending
          - verified
          - suspended
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the account was created
    BankConnection:
      type: object
      properties:
        id:
          type: string
          description: Unique bank connection identifier
        institutionName:
          type: string
          description: Name of the banking institution
        accountLast4:
          type: string
          description: Last four digits of the bank account number
          pattern: ^\d{4}$
        status:
          type: string
          description: Connection verification status
          enum:
          - pending
          - verified
          - failed
        verifiedAt:
          type: string
          format: date-time
          description: Timestamp when the connection was verified
    AccountCreateRequest:
      type: object
      required:
      - name
      - email
      properties:
        name:
          type: string
          description: Display name for the client account
          minLength: 1
          maxLength: 255
        email:
          type: string
          format: email
          description: Contact email for the account
        taxIdentifier:
          type: string
          description: Primary taxpayer identification number
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Arbitrary key-value pairs for reference data
    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
  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'
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Requested resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/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