openapi: 3.1.0
info:
  title: Axiym Payment API Events
  version: 0.1.0
  description: |-
    This reference describes the webhook events Axiym sends to your registered HTTPS endpoint. These are outbound notifications received by your application, not API operations for you to call.

    Event payloads contain the identifiers and status information needed to recognize and route a resource change. Treat the corresponding Payment API resource as the authoritative source of its current state and retrieve it when your workflow needs additional or up-to-date details. Verify every event signature, use the event `id` to process duplicate deliveries safely, and acknowledge successfully received events with an HTTP `200` response.

    To start receiving events, see [Webhook Registration & Management](/payment-api/webhooks/registration-and-management) and [Verifying Webhook Signatures](/payment-api/webhooks/verifying-signatures).
tags:
  - name: Payout
    description: Notifications about the validation, settlement, execution, and outcome of a payout.
  - name: Account
    description: Notifications about posted Axiym account movements and changes to Axiym account availability.
paths:
  /webhooks/payout.created:
    post:
      tags:
        - Payout
      summary: Payout created
      description: Sent when a payout has been prepared and is awaiting partner confirmation.
      operationId: onPayoutCreated
      security: []
      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/PayoutEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/payout.approved:
    post:
      tags:
        - Payout
      summary: Payout approved
      description: Sent when the exact payout instruction has passed validation and transaction controls.
      operationId: onPayoutApproved
      security: []
      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.approved
                data:
                  $ref: "#/components/schemas/PayoutEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/payout.rejected:
    post:
      tags:
        - Payout
      summary: Payout rejected
      description: Sent when validation or transaction controls reject the payout before local execution.
      operationId: onPayoutRejected
      security: []
      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/PayoutEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/payout.settled:
    post:
      tags:
        - Payout
      summary: Payout settled
      description: Sent when the payout's sell amount and fee have been debited from the funding account.
      operationId: onPayoutSettled
      security: []
      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.settled
                data:
                  $ref: "#/components/schemas/PayoutEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/payout.submitted:
    post:
      tags:
        - Payout
      summary: Payout submitted
      description: Sent when the payout instruction has been submitted to the local payout provider. From this point, cancellation is not guaranteed.
      operationId: onPayoutSubmitted
      security: []
      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.submitted
                data:
                  $ref: "#/components/schemas/PayoutEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/payout.completed:
    post:
      tags:
        - Payout
      summary: Payout completed
      description: Sent when the payout has completed successfully through the local banking route.
      operationId: onPayoutCompleted
      security: []
      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/PayoutEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/payout.canceled:
    post:
      tags:
        - Payout
      summary: Payout canceled
      description: Sent when the payout has been canceled and will not be submitted for local execution.
      operationId: onPayoutCanceled
      security: []
      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/PayoutEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/payout.failed:
    post:
      tags:
        - Payout
      summary: Payout failed
      description: Sent when the payout cannot proceed or complete successfully.
      operationId: onPayoutFailed
      security: []
      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.failed
                data:
                  $ref: "#/components/schemas/PayoutEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  /webhooks/payout.returned:
    post:
      tags:
        - Payout
      summary: Payout returned
      description: Sent when a payout submitted through the local banking route is returned. A returned payout requires operational review and reconciliation.
      operationId: onPayoutReturned
      security: []
      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.returned
                data:
                  $ref: "#/components/schemas/PayoutEventData"
      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: []
      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: []
      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: []
      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: []
      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: []
      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.
components:
  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-08-04T05: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
      enum:
        - ACTIVE
        - SUSPENDED
        - CLOSED
      examples:
        - SUSPENDED
    AccountMovementEventData:
      type: object
      description: A posted ledger movement on a partner-owned 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
            - PAYOUT
          examples:
            - PAYOUT
        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
    AccountStatusEventData:
      type: object
      description: Account lifecycle notification.
      required:
        - accountId
        - status
      properties:
        accountId:
          type: string
          format: uuid
          description: Account identifier (UUID).
          examples:
            - 8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a
        status:
          $ref: "#/components/schemas/AccountStatus"
          description: Account status at the time the event was emitted.
          examples:
            - SUSPENDED
    PayoutStatus:
      type: string
      description: Normalized payout status at the time the event was emitted.
      enum:
        - PENDING_CONFIRMATION
        - PROCESSING
        - APPROVED
        - REJECTED
        - SETTLED
        - SUBMITTED
        - COMPLETED
        - CANCELED
        - FAILED
        - RETURNED
        - EXPIRED
      examples:
        - SETTLED
    PayoutEventData:
      type: object
      description: Compact event payload containing the identifiers and status needed to route and correlate the event. Webhooks are notifications, not state transfer. Fetch the authoritative payout via `GET /payouts/{payoutId}` when current or complete details are required.
      required:
        - payoutId
        - quoteId
        - accountId
        - clientReference
        - status
      properties:
        payoutId:
          type: string
          format: uuid
          description: Payout identifier (UUID).
          examples:
            - 9b4e2a1c-6d3f-4a8e-bc7d-1f2a3b4c5d6e
        quoteId:
          type: string
          format: uuid
          description: Quote used to create the payout.
          examples:
            - 978490c4-4227-4a75-9820-5f90482bb78b
        accountId:
          type: string
          format: uuid
          description: Axiym account funding the payout.
          examples:
            - d96b90c1-b69e-4f5d-8154-46ecfcad8d0a
        clientReference:
          type: string
          description: Partner reference supplied when the payout was created.
          examples:
            - PAYOUT-2026-001
        status:
          $ref: "#/components/schemas/PayoutStatus"
        reasonCode:
          type: string
          description: Provider-neutral reason code when the payout is rejected, canceled, failed, or returned.
          examples:
            - BENEFICIARY_ACCOUNT_CLOSED