Remitian Accounts API

openapi: 3.2.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.
  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
    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
    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
    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
    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:
    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'
    Unauthorized:
      description: Missing or invalid authentication credentials
      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