openapi: 3.1.0
info:
  title: Axiym Payment API Events
  version: 0.1.0
  description: |-
    Webhook notifications report payout progress and account changes. Verify the signature, de-duplicate deliveries by event `id`, and acknowledge accepted events with a `2xx` response. Retrieve the related API resource when you need its current state or full details.

    See [Webhook registration and management](/payment-api/webhooks/registration-and-management) and [Verifying webhook signatures](/payment-api/webhooks/verifying-signatures).
tags:
  - name: Payout
    description: Notifications about payout progress and outcomes.
  - name: Account
    description: Notifications about posted Axiym account movements and changes to Axiym account availability.
  - name: Webhook subscription
    description: Test notification sent when you request a delivery to a registered endpoint.
paths:
  /webhooks/payout.created:
    post:
      tags:
        - Payout
      summary: Payout created
      description: "Sent once a payout has been confirmed and accepted for processing."
      operationId: onPayoutCreated
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  $ref: "#/components/schemas/EventId"
                timestamp:
                  $ref: "#/components/schemas/EventTimestamp"
                type:
                  type: string
                  const: payout.created
                data:
                  $ref: "#/components/schemas/PayoutCreatedEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/payout.rejected:
    post:
      tags:
        - Payout
      summary: Payout rejected
      description: "Sent when the payout is rejected and will not complete, by compliance or transaction controls before settlement or by the bank or network during delivery. Reserved funds are released. See `reasonCode` for the reason."
      operationId: onPayoutRejected
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  $ref: "#/components/schemas/EventId"
                timestamp:
                  $ref: "#/components/schemas/EventTimestamp"
                type:
                  type: string
                  const: payout.rejected
                data:
                  $ref: "#/components/schemas/PayoutRejectedEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/payout.held:
    post:
      tags:
        - Payout
      summary: Payout held
      description: Sent when a confirmed payout is temporarily placed on hold.
      operationId: onPayoutHeld
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  $ref: "#/components/schemas/EventId"
                timestamp:
                  $ref: "#/components/schemas/EventTimestamp"
                type:
                  type: string
                  const: payout.held
                data:
                  $ref: "#/components/schemas/PayoutHeldEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/payout.completed:
    post:
      tags:
        - Payout
      summary: Payout completed
      description: Sent when the payout has been delivered successfully to the beneficiary.
      operationId: onPayoutCompleted
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  $ref: "#/components/schemas/EventId"
                timestamp:
                  $ref: "#/components/schemas/EventTimestamp"
                type:
                  type: string
                  const: payout.completed
                data:
                  $ref: "#/components/schemas/PayoutCompletedEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/payout.canceled:
    post:
      tags:
        - Payout
      summary: Payout canceled
      description: "Sent when a payout moves to `CANCELED` because unconfirmed terms expired (`reasonCode: TERMS_EXPIRED`), it was canceled before execution, or funds were returned after delivery. See `reasonCode` for the reason."
      operationId: onPayoutCanceled
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  $ref: "#/components/schemas/EventId"
                timestamp:
                  $ref: "#/components/schemas/EventTimestamp"
                type:
                  type: string
                  const: payout.canceled
                data:
                  $ref: "#/components/schemas/PayoutCanceledEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/account.credited:
    post:
      tags:
        - Account
      summary: Account credited
      description: Sent when a credit has been posted to an account.
      operationId: onAccountCredited
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  $ref: "#/components/schemas/EventId"
                timestamp:
                  $ref: "#/components/schemas/EventTimestamp"
                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: Account debited
      description: Sent when a debit has been posted to an account.
      operationId: onAccountDebited
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  $ref: "#/components/schemas/EventId"
                timestamp:
                  $ref: "#/components/schemas/EventTimestamp"
                type:
                  type: string
                  const: account.debited
                data:
                  $ref: "#/components/schemas/AccountMovementEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/account.activated:
    post:
      tags:
        - Account
      summary: Account activated
      description: Sent when an account becomes active and available for supported operations.
      operationId: onAccountActivated
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  $ref: "#/components/schemas/EventId"
                timestamp:
                  $ref: "#/components/schemas/EventTimestamp"
                type:
                  type: string
                  const: account.activated
                data:
                  $ref: "#/components/schemas/AccountStatusEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/account.suspended:
    post:
      tags:
        - Account
      summary: Account suspended
      description: Sent when an account is suspended and temporarily unavailable for supported operations.
      operationId: onAccountSuspended
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  $ref: "#/components/schemas/EventId"
                timestamp:
                  $ref: "#/components/schemas/EventTimestamp"
                type:
                  type: string
                  const: account.suspended
                data:
                  $ref: "#/components/schemas/AccountStatusEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/account.closed:
    post:
      tags:
        - Account
      summary: Account closed
      description: Sent when an account is permanently closed.
      operationId: onAccountClosed
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  $ref: "#/components/schemas/EventId"
                timestamp:
                  $ref: "#/components/schemas/EventTimestamp"
                type:
                  type: string
                  const: account.closed
                data:
                  $ref: "#/components/schemas/AccountStatusEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/subscription.test:
    post:
      tags:
        - Webhook subscription
      summary: Webhook subscription test
      description: Sent only when you request a test delivery for a webhook subscription.
      operationId: onSubscriptionTest
      security: []
      parameters:
        - $ref: "#/components/parameters/WebhookSignature"
        - $ref: "#/components/parameters/WebhookKeyId"
        - $ref: "#/components/parameters/WebhookAlgorithm"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - timestamp
                - type
                - data
              properties:
                id:
                  $ref: "#/components/schemas/EventId"
                timestamp:
                  $ref: "#/components/schemas/EventTimestamp"
                type:
                  type: string
                  const: subscription.test
                data:
                  type: object
                  required:
                    - test
                  properties:
                    test:
                      type: string
                      const: OK
                      description: Test delivery marker.
      responses:
        "200":
          description: Acknowledged by your endpoint.
components:
  parameters:
    WebhookSignature:
      name: X-Signature
      in: header
      required: true
      schema:
        type: string
      description: Ed25519 signature of the raw request body.
    WebhookKeyId:
      name: X-Key-Id
      in: header
      required: true
      schema:
        type: string
        format: uuid
      description: "Identifier of the public key used to verify the delivery signature."
    WebhookAlgorithm:
      name: X-Algorithm
      in: header
      required: true
      schema:
        type: string
        const: Ed25519
      description: Signature algorithm used for the delivery.
  schemas:
    EventId:
      type: string
      format: uuid
      description: Event ID. Use this for de-duplication.
      examples:
        - f47ac10b-58cc-4372-a567-0e02b2c3d479
    EventTimestamp:
      type: string
      format: date-time
      description: Time Axiym created the event. Formatted in ISO 8601.
      examples:
        - 2026-09-07T10:07:30Z
    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
      description: Current availability of an Axiym account.
      enum:
        - ACTIVE
        - SUSPENDED
        - CLOSED
      examples:
        - SUSPENDED
    AccountMovementEventData:
      type: object
      description: "Posted credit or debit on an Axiym account accessible to your integration. The event contains the movement amount; retrieve the current account balance with `GET /accounts/{accountId}`."
      required:
        - accountId
        - amount
        - currency
        - occurredAt
      properties:
        accountId:
          type: string
          format: uuid
          description: Account identifier (UUID).
          examples:
            - 5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e
        amount:
          allOf:
            - $ref: "#/components/schemas/Decimal"
          description: Positive movement amount in the account currency; direction is in the event type.
          examples:
            - "1010.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
            - PAYOUT
          examples:
            - PAYOUT
        relatedResourceId:
          type: string
          format: uuid
          description: Identifier of the linked resource, where present.
          examples:
            - c3d65312-6575-43de-b8ae-728d8d0a9371
        occurredAt:
          type: string
          format: date-time
          description: When the movement occurred. Formatted in ISO 8601.
          examples:
            - 2026-09-07T20:07:31Z
    AccountStatusEventData:
      type: object
      description: Account lifecycle notification.
      required:
        - accountId
        - status
      properties:
        accountId:
          type: string
          format: uuid
          description: Account identifier (UUID).
          examples:
            - 5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e
        status:
          $ref: "#/components/schemas/AccountStatus"
          description: Account status at the time the event was emitted.
          examples:
            - SUSPENDED
    PayoutStatus:
      type: string
      description: "Payout status at the time the event was emitted."
      enum:
        - PENDING
        - HELD
        - COMPLETED
        - CANCELED
        - REJECTED
      examples:
        - PENDING
    PayoutEventData:
      type: object
      description: "Payment identifier and payout status at the time of the event. Retrieve `GET /payouts/{paymentId}` for the current payment."
      required:
        - paymentId
        - status
      properties:
        paymentId:
          type: string
          format: uuid
          description: Payment identifier (UUID).
          examples:
            - c3d65312-6575-43de-b8ae-728d8d0a9371
        externalReference:
          type: string
          description: Your reference supplied when the payout was created.
          examples:
            - PAYOUT-2026-001
        status:
          $ref: "#/components/schemas/PayoutStatus"
    PayoutOutcomeEventData:
      description: Payout event data for an unsuccessful final outcome.
      allOf:
        - $ref: "#/components/schemas/PayoutEventData"
        - type: object
          required:
            - reasonCode
          properties:
            reasonCode:
              type: string
              description: Machine-readable reason the payout was canceled or rejected.
    PayoutCreatedEventData:
      description: Event data for a payout that has been confirmed and accepted for processing.
      allOf:
        - $ref: "#/components/schemas/PayoutEventData"
        - type: object
          properties:
            status:
              type: string
              const: PENDING
              description: The payout is confirmed and being processed.
    PayoutHeldEventData:
      description: Event data for a payout temporarily placed on hold.
      allOf:
        - $ref: "#/components/schemas/PayoutEventData"
        - type: object
          properties:
            status:
              type: string
              const: HELD
              description: The payout is temporarily on hold.
    PayoutCompletedEventData:
      description: Event data for a successfully completed payout.
      allOf:
        - $ref: "#/components/schemas/PayoutEventData"
        - type: object
          properties:
            status:
              type: string
              const: COMPLETED
              description: The payout completed successfully.
    PayoutRejectedEventData:
      description: Event data for a rejected payout.
      allOf:
        - $ref: "#/components/schemas/PayoutOutcomeEventData"
        - type: object
          properties:
            status:
              type: string
              const: REJECTED
              description: The payout was rejected; see `reasonCode`.
    PayoutCanceledEventData:
      description: Event data for a payout canceled before completion.
      allOf:
        - $ref: "#/components/schemas/PayoutOutcomeEventData"
        - type: object
          properties:
            status:
              type: string
              const: CANCELED
              description: The payout was canceled; see `reasonCode`.