# Events

Understand Payment API event types, payloads, and processing rules.

Product: Payment API
Guides follow API reference 0.1.0 and event reference 0.1.0.
Canonical page: https://docs.axiym.io/payment-api/webhooks/events

The Payment API emits events for payout status changes and Axiym account
changes. The event name tells you what changed.

## Payout events

Payout creation and confirmation are separate steps. The events below report
creation and subsequent status changes.

| Event              | Sent when                                                                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `payout.created`   | The payout was confirmed and accepted for processing.                                                                                                                    |
| `payout.held`      | The confirmed payout was stopped by a review, compliance, or operational gate (`HELD`).                                                                                  |
| `payout.completed` | The payout was delivered to the beneficiary (`COMPLETED`).                                                                                                               |
| `payout.canceled`  | The payout moved to `CANCELED` because unconfirmed terms expired (`reasonCode: TERMS_EXPIRED`), it was canceled before execution, or funds were returned after delivery. |
| `payout.rejected`  | The payout was rejected and will not complete (`REJECTED`), by compliance before settlement or by the bank or network during delivery. Reserved funds are released.      |

`payout.canceled` and `payout.rejected` carry `reasonCode`. Intermediate steps
while the payout is `PENDING` (approval, settlement, submission) are not
reported as events; read the payout for its current state.

## Subscription test event

| Event               | Sent when                                                       |
| ------------------- | --------------------------------------------------------------- |
| `subscription.test` | A test delivery is requested. Its `data` is `{ "test": "OK" }`. |

## Axiym account events

| Event               | Sent when                                                                           |
| ------------------- | ----------------------------------------------------------------------------------- |
| `account.credited`  | A posted movement credits the Axiym account. The event carries the movement amount. |
| `account.debited`   | A posted movement debits the Axiym account. The event carries the movement amount.  |
| `account.activated` | The Axiym account becomes active, initially or after a suspension.                  |
| `account.suspended` | The Axiym account is suspended.                                                     |
| `account.closed`    | The Axiym account is permanently closed.                                            |

Account credit and debit events describe immutable posted movements, so the
movement amount is included but the current balance is not. Fetch the account
when you need its latest balance. When a movement is associated with a payout,
`relatedResourceType` is `PAYOUT` and `relatedResourceId` contains its
`paymentId`.

Webhooks are notifications, not state transfer. Fetch the corresponding payout
or account through its resource endpoint when you need the complete or
latest state.

## Event envelope

```json
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "timestamp": "2026-09-07T10:12:00Z",
  "type": "payout.completed",
  "data": {
    "paymentId": "c3d65312-6575-43de-b8ae-728d8d0a9371",
    "externalReference": "PAYOUT-2026-001",
    "status": "COMPLETED"
  }
}
```

| Field       | Description                                                                       |
| ----------- | --------------------------------------------------------------------------------- |
| `id`        | Unique event identifier used for de-duplication.                                  |
| `timestamp` | Time Axiym created the event.                                                     |
| `type`      | Event name.                                                                       |
| `data`      | Compact identifiers and status information used to route and correlate the event. |

The [Events reference](/payment-api/events) is the source of truth for the event
catalogue and payload schemas.

## Processing guidance

* Verify the signature before parsing or processing the payload.
* Process each event `id` once.
* Use the resource identifiers and partner references to correlate the notification.
* Retain the resource identifiers and use the corresponding Payment API path for reads.
* Do not move internal state backward because an older event arrives late.
* Fetch the corresponding resource before taking an action that depends on its latest state.