openapi: 3.1.0
info:
  title: Remitian Tax Payment Accounts Payments 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: Payments
  description: Initiate, validate, and confirm tax payments across multiple jurisdictions through a single unified gateway.
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'
components:
  schemas:
    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'
    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
    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
    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
    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
    PaymentId:
      name: paymentId
      in: path
      required: true
      description: Unique identifier of the payment
      schema:
        type: string
    StatusFilter:
      name: status
      in: query
      description: Filter by payment status
      schema:
        type: string
        enum:
        - draft
        - validated
        - confirmed
        - processing
        - completed
        - failed
        - cancelled
    JurisdictionFilter:
      name: jurisdictionId
      in: query
      description: Filter by jurisdiction identifier
      schema:
        type: string
    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
  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