openapi: 3.1.0
info:
  title: Axiym Account API events
  version: 0.2.0
  description: >-
    Webhook events Axiym delivers to your registered endpoint. These are outbound notifications —
    your service receives them at the URL you register; there is nothing to call here. Each event
    is signed and carries the payload shown below.


    To start receiving events, see [Webhook Registration &
    Management](/account-api/webhooks/registration-management) and [Verifying Webhook
    Signatures](/account-api/webhooks/verifying-signatures).
tags:
  - name: Withdrawal
    description: "`withdrawal.*` webhook events."
  - name: Account
    description: "`account.*` webhook events."
  - name: Subscription
    description: "`subscription.*` webhook events."
  - name: Whitelisted own account
    description: "`destination.*` webhook events."
paths:
  /webhooks/withdrawal.created:
    post:
      tags:
        - Withdrawal
      summary: Created
      operationId: onWithdrawalCreated
      security: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: Event ID. Use this for de-duplication.
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - "2026-06-23T14:05:09Z"
                type:
                  type: string
                  const: withdrawal.created
                data:
                  $ref: "#/components/schemas/WithdrawalEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/withdrawal.held:
    post:
      tags:
        - Withdrawal
      summary: Held
      operationId: onWithdrawalHeld
      security: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: Event ID. Use this for de-duplication.
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - "2026-06-23T14:05:09Z"
                type:
                  type: string
                  const: withdrawal.held
                data:
                  $ref: "#/components/schemas/WithdrawalEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/withdrawal.completed:
    post:
      tags:
        - Withdrawal
      summary: Completed
      operationId: onWithdrawalCompleted
      security: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: Event ID. Use this for de-duplication.
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - "2026-06-23T14:05:09Z"
                type:
                  type: string
                  const: withdrawal.completed
                data:
                  $ref: "#/components/schemas/WithdrawalEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/withdrawal.canceled:
    post:
      tags:
        - Withdrawal
      summary: Canceled
      operationId: onWithdrawalCanceled
      security: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: Event ID. Use this for de-duplication.
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - "2026-06-23T14:05:09Z"
                type:
                  type: string
                  const: withdrawal.canceled
                data:
                  $ref: "#/components/schemas/WithdrawalEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/withdrawal.rejected:
    post:
      tags:
        - Withdrawal
      summary: Rejected
      operationId: onWithdrawalRejected
      security: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: Event ID. Use this for de-duplication.
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - "2026-06-23T14:05:09Z"
                type:
                  type: string
                  const: withdrawal.rejected
                data:
                  $ref: "#/components/schemas/WithdrawalEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/account.credited:
    post:
      tags:
        - Account
      summary: Credited
      operationId: onAccountCredited
      security: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: Event ID. Use this for de-duplication.
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - "2026-06-23T14:05:09Z"
                type:
                  type: string
                  const: account.credited
                data:
                  $ref: "#/components/schemas/AccountMovementEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/account.debited:
    post:
      tags:
        - Account
      summary: Debited
      operationId: onAccountDebited
      security: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: Event ID. Use this for de-duplication.
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - "2026-06-23T14:05:09Z"
                type:
                  type: string
                  const: account.debited
                data:
                  $ref: "#/components/schemas/AccountMovementEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/subscription.test:
    post:
      tags:
        - Subscription
      summary: Test
      operationId: onSubscriptionTest
      security: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: Event ID. Use this for de-duplication.
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - "2026-06-23T14:05:09Z"
                type:
                  type: string
                  const: subscription.test
                data:
                  type: object
                  required:
                    - test
                  properties:
                    test:
                      type: string
                      const: OK
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/destination.created:
    post:
      tags:
        - Whitelisted own account
      summary: Created
      operationId: onDestinationCreated
      security: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: Event ID. Use this for de-duplication.
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - "2026-06-23T14:05:09Z"
                type:
                  type: string
                  const: destination.created
                data:
                  $ref: "#/components/schemas/DestinationEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/destination.activated:
    post:
      tags:
        - Whitelisted own account
      summary: Activated
      operationId: onDestinationActivated
      security: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: Event ID. Use this for de-duplication.
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - "2026-06-23T14:05:09Z"
                type:
                  type: string
                  const: destination.activated
                data:
                  $ref: "#/components/schemas/DestinationEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/destination.suspended:
    post:
      tags:
        - Whitelisted own account
      summary: Suspended
      operationId: onDestinationSuspended
      security: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: Event ID. Use this for de-duplication.
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - "2026-06-23T14:05:09Z"
                type:
                  type: string
                  const: destination.suspended
                data:
                  $ref: "#/components/schemas/DestinationEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/destination.closed:
    post:
      tags:
        - Whitelisted own account
      summary: Closed
      operationId: onDestinationClosed
      security: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  type: string
                  format: uuid
                  description: Event ID. Use this for de-duplication.
                  examples:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp. Formatted in ISO 8601.
                  examples:
                    - "2026-06-23T14:05:09Z"
                type:
                  type: string
                  const: destination.closed
                data:
                  $ref: "#/components/schemas/DestinationEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
components:
  schemas:
    DestinationStatus:
      type: string
      description: >
        `PENDING_REVIEW` awaiting compliance review, `ACTIVE` usable for withdrawals, `SUSPENDED`
        temporarily unusable, `CLOSED` permanently retired.
      enum:
        - PENDING_REVIEW
        - ACTIVE
        - SUSPENDED
        - CLOSED
      examples:
        - ACTIVE
    DestinationEventData:
      type: object
      description: Whitelisted own account lifecycle notification.
      required:
        - destinationId
        - status
      properties:
        destinationId:
          type: string
          format: uuid
          description: Destination identifier (UUID).
          examples:
            - e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c
        status:
          $ref: "#/components/schemas/DestinationStatus"
          description: Whitelisted own account status at the time the event was emitted.
          examples:
            - ACTIVE
    Currency:
      type: string
      description: Currency code — ISO 4217 (e.g. USD, EUR) or a supported digital currency (USDT, USDC).
      examples:
        - USD
    Decimal:
      type: string
      description: Decimal number serialized as a string to preserve precision.
      examples:
        - "1000.00"
    AccountStatus:
      type: string
      enum:
        - ACTIVE
        - SUSPENDED
        - CLOSED
      examples:
        - SUSPENDED
    AccountMovementEventData:
      type: object
      description: >-
        A posted ledger movement on an account. Movements are immutable facts, so the amount is
        carried in the event; the current balance is not — fetch it via `GET /accounts/{accountId}`.
      required:
        - accountId
        - amount
        - currency
        - occurredAt
      properties:
        accountId:
          type: string
          format: uuid
          description: Account identifier (UUID).
          examples:
            - 8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a
        amount:
          allOf:
            - $ref: "#/components/schemas/Decimal"
          description: Positive movement amount in the account currency; direction is in the event type.
          examples:
            - "1000.00"
        currency:
          $ref: "#/components/schemas/Currency"
          description: Account currency.
          examples:
            - USD
        relatedResourceType:
          type: string
          description: >-
            Type of the linked money movement; absent for movements with no linked API resource.
          enum:
            - DEPOSIT
            - WITHDRAWAL
            - CONVERSION
          examples:
            - WITHDRAWAL
        relatedResourceId:
          type: string
          format: uuid
          description: Identifier of the linked resource, where present.
          examples:
            - 9b4e2a1c-6d3f-4a8e-bc7d-1f2a3b4c5d6e
        occurredAt:
          type: string
          format: date-time
          description: When the movement occurred. Formatted in ISO 8601.
          examples:
            - "2026-06-14T20:07:31Z"
    ExternalReference:
      type: string
      maxLength: 255
      description: >
        Your own identifier for this object, for correlation with your system. Optional, echoed back
        on reads.
      examples:
        - wd-2026-0614-01
    WithdrawalStatus:
      type: string
      description: >
        `PENDING` awaiting execution, `HELD` temporarily on hold — no action needed from you,
        `COMPLETED` done, `CANCELED`/`REJECTED` not completed (see `reasonCode`).
      enum:
        - PENDING
        - HELD
        - COMPLETED
        - CANCELED
        - REJECTED
      examples:
        - PENDING
    WithdrawalEventData:
      type: object
      description: >-
        Compact event payload: enough to route the event and correlate it with your records.
        Webhooks are notifications, not state transfer — fetch the authoritative withdrawal via
        `GET /withdrawals/{withdrawalId}` when you need amounts, fees, or the transaction hash.
      required:
        - withdrawalId
        - status
      properties:
        withdrawalId:
          type: string
          format: uuid
          description: Withdrawal identifier (UUID).
          examples:
            - 9b4e2a1c-6d3f-4a8e-bc7d-1f2a3b4c5d6e
        status:
          $ref: "#/components/schemas/WithdrawalStatus"
          description: Withdrawal status at the time the event was emitted.
          examples:
            - COMPLETED
        externalReference:
          $ref: "#/components/schemas/ExternalReference"
          description: Your reference submitted on creation, where present.
          examples:
            - wd-2026-0714-01
        reasonCode:
          type: string
          description: >-
            Present on `withdrawal.canceled` / `withdrawal.rejected` — the reason as reported by
            the bank, the network, or Axiym operations. Example:
            `INSUFFICIENT_BENEFICIARY_DETAILS`.