openapi: 3.1.0
info:
  title: Remitian Tax Payment 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
externalDocs:
  description: Remitian Integration Documentation
  url: https://remitian.com/integrations/integrate-remitian
servers:
  - url: https://api.remitian.com
    description: Production Server
tags:
  - name: Accounts
    description: >-
      Manage client accounts and their linked bank connections for
      tax payment processing.
  - name: Audit Logs
    description: >-
      Access bank-grade audit logs that track every payment from initiation
      to completion for compliance and reconciliation.
  - name: Jurisdictions
    description: >-
      Retrieve and manage supported tax jurisdictions and their associated
      payment requirements and routing rules.
  - name: Payments
    description: >-
      Initiate, validate, and confirm tax payments across multiple
      jurisdictions through a single unified gateway.
  - name: Webhooks
    description: >-
      Manage webhook subscriptions for real-time payment status updates
      and event notifications.
security:
  - bearerAuth: []
paths:
  /v1/payments:
    get:
      operationId: listPayments
      summary: List payments
      description: >-
        Retrieve a paginated list of tax payments. Supports filtering by
        jurisdiction, status, date range, and client account. Results are
        sorted by creation date in descending order.
      tags:
        - Payments
      parameters:
        - $ref: '#/components/parameters/JurisdictionFilter'
        - $ref: '#/components/parameters/StatusFilter'
        - $ref: '#/components/parameters/DateFromFilter'
        - $ref: '#/components/parameters/DateToFilter'
        - $ref: '#/components/parameters/PageLimit'
        - $ref: '#/components/parameters/PageOffset'
      responses:
        '200':
          description: A paginated list of payments
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Payment'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: initiatePayment
      summary: Initiate a tax payment
      description: >-
        Initiate a new tax payment to a specific jurisdiction. The API
        validates the payment details against jurisdiction-specific rules,
        routes it to the appropriate tax authority, and returns a payment
        object with a unique identifier for tracking. Payments move directly
        from client accounts to tax authorities through verified banking
        connections.
      tags:
        - Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentInitiationRequest'
      responses:
        '201':
          description: Payment initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: Validation failed against jurisdiction rules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/payments/{paymentId}:
    get:
      operationId: getPayment
      summary: Retrieve a payment
      description: >-
        Retrieve the full details of a specific tax payment, including its
        current status, jurisdiction routing information, validation results,
        and audit trail.
      tags:
        - Payments
      parameters:
        - $ref: '#/components/parameters/PaymentId'
      responses:
        '200':
          description: Payment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/payments/{paymentId}/validate:
    post:
      operationId: validatePayment
      summary: Validate a payment
      description: >-
        Run jurisdiction-specific validation on a payment before confirmation.
        Checks payment amounts, tax periods, jurisdiction-specific identifiers,
        and account details against the rules of the target tax authority.
        Returns validation results with any errors or warnings.
      tags:
        - Payments
      parameters:
        - $ref: '#/components/parameters/PaymentId'
      responses:
        '200':
          description: Validation results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/payments/{paymentId}/confirm:
    post:
      operationId: confirmPayment
      summary: Confirm a payment
      description: >-
        Confirm a validated payment for processing. Once confirmed, the
        payment is routed to the appropriate tax authority through verified
        banking connections. This action is irreversible. The payment status
        will transition to "processing" and subsequent updates will be
        delivered via webhooks.
      tags:
        - Payments
      parameters:
        - $ref: '#/components/parameters/PaymentId'
      responses:
        '200':
          description: Payment confirmed and queued for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Payment is not in a confirmable state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/payments/{paymentId}/cancel:
    post:
      operationId: cancelPayment
      summary: Cancel a payment
      description: >-
        Cancel a payment that has not yet been confirmed or is still in a
        cancellable processing state. Returns the updated payment object
        with a cancelled status.
      tags:
        - Payments
      parameters:
        - $ref: '#/components/parameters/PaymentId'
      responses:
        '200':
          description: Payment cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Payment cannot be cancelled in its current state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /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'
  /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'
  /v1/audit-logs:
    get:
      operationId: listAuditLogs
      summary: List audit logs
      description: >-
        Retrieve bank-grade audit logs that track every payment from
        initiation to completion. Supports filtering by payment, account,
        event type, and date range for compliance and reconciliation purposes.
      tags:
        - Audit Logs
      parameters:
        - name: paymentId
          in: query
          description: Filter logs by payment identifier
          schema:
            type: string
        - name: accountId
          in: query
          description: Filter logs by account identifier
          schema:
            type: string
        - name: eventType
          in: query
          description: Filter by audit event type
          schema:
            type: string
        - $ref: '#/components/parameters/DateFromFilter'
        - $ref: '#/components/parameters/DateToFilter'
        - $ref: '#/components/parameters/PageLimit'
        - $ref: '#/components/parameters/PageOffset'
      responses:
        '200':
          description: A paginated list of audit log entries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AuditLogEntry'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/webhooks:
    get:
      operationId: listWebhookSubscriptions
      summary: List webhook subscriptions
      description: >-
        Retrieve a list of registered webhook subscriptions for receiving
        real-time payment status updates and event notifications.
      tags:
        - Webhooks
      responses:
        '200':
          description: A list of webhook subscriptions
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookSubscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createWebhookSubscription
      summary: Create a webhook subscription
      description: >-
        Register a new webhook endpoint to receive real-time notifications
        for payment events. The endpoint must be a publicly accessible
        HTTPS URL. A signing secret is returned for verifying webhook
        delivery authenticity.
      tags:
        - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookSubscriptionRequest'
      responses:
        '201':
          description: Webhook subscription created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/webhooks/{webhookId}:
    delete:
      operationId: deleteWebhookSubscription
      summary: Delete a webhook subscription
      description: >-
        Remove a webhook subscription. The endpoint will no longer receive
        event notifications after deletion.
      tags:
        - Webhooks
      parameters:
        - name: webhookId
          in: path
          required: true
          description: Unique identifier of the webhook subscription
          schema:
            type: string
      responses:
        '204':
          description: Webhook subscription deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        API key authentication using a Bearer token provided by Remitian
        during partner onboarding.
  parameters:
    PaymentId:
      name: paymentId
      in: path
      required: true
      description: Unique identifier of the payment
      schema:
        type: string
    JurisdictionFilter:
      name: jurisdictionId
      in: query
      description: Filter by jurisdiction identifier
      schema:
        type: string
    StatusFilter:
      name: status
      in: query
      description: Filter by payment status
      schema:
        type: string
        enum:
          - draft
          - validated
          - confirmed
          - processing
          - completed
          - failed
          - cancelled
    DateFromFilter:
      name: dateFrom
      in: query
      description: Filter results from this date (ISO 8601)
      schema:
        type: string
        format: date
    DateToFilter:
      name: dateTo
      in: query
      description: Filter results up to this date (ISO 8601)
      schema:
        type: string
        format: date
    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
  schemas:
    Payment:
      type: object
      properties:
        id:
          type: string
          description: Unique payment identifier
        status:
          type: string
          description: Current status of the payment
          enum:
            - draft
            - validated
            - confirmed
            - processing
            - completed
            - failed
            - cancelled
        amount:
          type: number
          format: double
          description: Payment amount in the specified currency
          minimum: 0.01
        currency:
          type: string
          description: Three-letter ISO 4217 currency code
          pattern: '^[A-Z]{3}$'
          example: USD
        taxType:
          type: string
          description: Type of tax being paid
          example: income_tax
        taxPeriod:
          type: string
          description: Tax period for the payment (e.g., 2025-Q4, 2025)
          example: '2025'
        jurisdictionId:
          type: string
          description: Identifier of the target tax jurisdiction
        accountId:
          type: string
          description: Identifier of the client account making the payment
        validationResults:
          $ref: '#/components/schemas/ValidationResult'
        confirmationNumber:
          type: string
          description: >-
            Confirmation number issued by the tax authority upon successful
            payment processing
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the payment was initiated
        updatedAt:
          type: string
          format: date-time
          description: Timestamp of the last status update
        metadata:
          type: object
          additionalProperties:
            type: string
          description: >-
            Arbitrary key-value pairs for partner-specific reference data
    PaymentInitiationRequest:
      type: object
      required:
        - amount
        - currency
        - taxType
        - taxPeriod
        - jurisdictionId
        - accountId
      properties:
        amount:
          type: number
          format: double
          description: Payment amount in the specified currency
          minimum: 0.01
        currency:
          type: string
          description: Three-letter ISO 4217 currency code
          pattern: '^[A-Z]{3}$'
          example: USD
        taxType:
          type: string
          description: Type of tax being paid (varies by jurisdiction)
          example: income_tax
        taxPeriod:
          type: string
          description: Tax period for the payment
          example: '2025'
        jurisdictionId:
          type: string
          description: Identifier of the target tax jurisdiction
        accountId:
          type: string
          description: Identifier of the client account making the payment
        taxIdentifier:
          type: string
          description: >-
            Taxpayer identification number (EIN, SSN, BN) as required by
            the jurisdiction
        metadata:
          type: object
          additionalProperties:
            type: string
          description: >-
            Arbitrary key-value pairs for partner-specific reference data
    ValidationResult:
      type: object
      properties:
        valid:
          type: boolean
          description: Whether the payment passed all validation checks
        errors:
          type: array
          description: List of validation errors that must be resolved
          items:
            $ref: '#/components/schemas/ValidationIssue'
        warnings:
          type: array
          description: List of validation warnings that may need attention
          items:
            $ref: '#/components/schemas/ValidationIssue'
    ValidationIssue:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error or warning code
        field:
          type: string
          description: The field that triggered the validation issue
        message:
          type: string
          description: Human-readable description of the issue
    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
    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
    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
    AuditLogEntry:
      type: object
      properties:
        id:
          type: string
          description: Unique audit log entry identifier
        paymentId:
          type: string
          description: Associated payment identifier
        accountId:
          type: string
          description: Associated account identifier
        eventType:
          type: string
          description: Type of audit event
          example: payment.confirmed
        description:
          type: string
          description: Human-readable description of the event
        actor:
          type: string
          description: >-
            Identifier of the user or system that triggered the event
        ipAddress:
          type: string
          description: IP address of the request that triggered the event
        timestamp:
          type: string
          format: date-time
          description: When the event occurred
        metadata:
          type: object
          additionalProperties: true
          description: Additional context for the audit event
    WebhookSubscription:
      type: object
      properties:
        id:
          type: string
          description: Unique webhook subscription identifier
        url:
          type: string
          format: uri
          description: HTTPS endpoint URL for webhook delivery
        events:
          type: array
          description: List of event types to subscribe to
          items:
            type: string
        signingSecret:
          type: string
          description: >-
            Secret key for HMAC signature verification of webhook
            deliveries. Only returned on creation.
        active:
          type: boolean
          description: Whether the subscription is active
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the subscription was created
    WebhookSubscriptionRequest:
      type: object
      required:
        - url
        - events
      properties:
        url:
          type: string
          format: uri
          description: HTTPS endpoint URL for webhook delivery
        events:
          type: array
          description: >-
            List of event types to subscribe to (e.g.,
            payment.completed, payment.failed)
          items:
            type: string
          minItems: 1
    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
  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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'