openapi: 3.1.0
info:
  title: Remitian Tax Payment Accounts Webhooks 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: Webhooks
  description: Manage webhook subscriptions for real-time payment status updates and event notifications.
paths:
  /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:
  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'
  schemas:
    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
    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