# Payout rejected

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.

Product: Payment API
Event reference version: 0.1.0 (current)
OpenAPI contract: https://docs.axiym.io/openapi/payment-api/events/0.1.0.yaml
Canonical page: https://docs.axiym.io/payment-api/events/0.1.0/payout/onPayoutRejected

[Compact reference](/payment-api/events/0.1.0/payout/onPayoutRejected.md)

## POST /webhooks/payout.rejected

## Authentication

```json
{
  "security": [],
  "securitySchemes": {}
}
```

## Parameters

### header: X-Signature

```json
{
  "name": "X-Signature",
  "in": "header",
  "required": true,
  "schema": {
    "type": "string"
  },
  "description": "Ed25519 signature of the raw request body."
}
```

### header: X-Key-Id

```json
{
  "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."
}
```

### header: X-Algorithm

```json
{
  "name": "X-Algorithm",
  "in": "header",
  "required": true,
  "schema": {
    "type": "string",
    "const": "Ed25519"
  },
  "description": "Signature algorithm used for the delivery."
}
```

## Request body

```json
{
  "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

```json
{
  "description": "Acknowledged by your endpoint."
}
```

## Operation metadata

```json
{
  "tags": [
    "Payout"
  ],
  "operationId": "onPayoutRejected"
}
```

## Referenced definitions

- [`#/components/parameters/WebhookSignature`](#definition-1)
- [`#/components/parameters/WebhookKeyId`](#definition-2)
- [`#/components/parameters/WebhookAlgorithm`](#definition-3)
- [`#/components/schemas/EventId`](#definition-4)
- [`#/components/schemas/EventTimestamp`](#definition-5)
- [`#/components/schemas/PayoutRejectedEventData`](#definition-6)
- [`#/components/schemas/PayoutOutcomeEventData`](#definition-7)
- [`#/components/schemas/PayoutEventData`](#definition-8)
- [`#/components/schemas/PayoutStatus`](#definition-9)

### definition-1

`#/components/parameters/WebhookSignature`

```json
{
  "name": "X-Signature",
  "in": "header",
  "required": true,
  "schema": {
    "type": "string"
  },
  "description": "Ed25519 signature of the raw request body."
}
```

### definition-2

`#/components/parameters/WebhookKeyId`

```json
{
  "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."
}
```

### definition-3

`#/components/parameters/WebhookAlgorithm`

```json
{
  "name": "X-Algorithm",
  "in": "header",
  "required": true,
  "schema": {
    "type": "string",
    "const": "Ed25519"
  },
  "description": "Signature algorithm used for the delivery."
}
```

### definition-4

`#/components/schemas/EventId`

```json
{
  "type": "string",
  "format": "uuid",
  "description": "Event ID. Use this for de-duplication.",
  "examples": [
    "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  ]
}
```

### definition-5

`#/components/schemas/EventTimestamp`

```json
{
  "type": "string",
  "format": "date-time",
  "description": "Time Axiym created the event. Formatted in ISO 8601.",
  "examples": [
    "2026-09-07T10:07:30Z"
  ]
}
```

### definition-6

`#/components/schemas/PayoutRejectedEventData`

```json
{
  "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`."
        }
      }
    }
  ]
}
```

### definition-7

`#/components/schemas/PayoutOutcomeEventData`

```json
{
  "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."
        }
      }
    }
  ]
}
```

### definition-8

`#/components/schemas/PayoutEventData`

```json
{
  "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"
    }
  }
}
```

### definition-9

`#/components/schemas/PayoutStatus`

```json
{
  "type": "string",
  "description": "Payout status at the time the event was emitted.",
  "enum": [
    "PENDING",
    "HELD",
    "COMPLETED",
    "CANCELED",
    "REJECTED"
  ],
  "examples": [
    "PENDING"
  ]
}
```