# Withdrawal rejected

Sent when a withdrawal has been rejected and will not complete.

Product: Direct Trade API
Event reference version: 0.1.0 (current)
OpenAPI contract: https://docs.axiym.io/openapi/direct-trade-api/events/0.1.0.yaml
Canonical page: https://docs.axiym.io/direct-trade-api/events/0.1.0/withdrawal/onWithdrawalRejected

[Compact reference](/direct-trade-api/events/0.1.0/withdrawal/onWithdrawalRejected.md)

## POST /webhooks/withdrawal.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 sign the delivery."
}
```

### 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
{
  "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-07-14T20:08:00Z"
            ]
          },
          "type": {
            "type": "string",
            "const": "withdrawal.rejected"
          },
          "data": {
            "$ref": "#/components/schemas/WithdrawalEventData"
          }
        }
      }
    }
  }
}
```

## Responses

### 200

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

## Operation metadata

```json
{
  "tags": [
    "Withdrawal"
  ],
  "operationId": "onWithdrawalRejected"
}
```

## Referenced definitions

- [`#/components/parameters/WebhookSignature`](#definition-1)
- [`#/components/parameters/WebhookKeyId`](#definition-2)
- [`#/components/parameters/WebhookAlgorithm`](#definition-3)
- [`#/components/schemas/WithdrawalEventData`](#definition-4)
- [`#/components/schemas/WithdrawalStatus`](#definition-5)
- [`#/components/schemas/ExternalReference`](#definition-6)

### 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 sign the delivery."
}
```

### 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/WithdrawalEventData`

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

### definition-5

`#/components/schemas/WithdrawalStatus`

```json
{
  "type": "string",
  "description": "`PENDING` is queued for execution. `HELD` is temporarily on hold — no action needed from you. `COMPLETED` is done. `CANCELED` and `REJECTED` did not complete (see `reasonCode`).\n",
  "enum": [
    "PENDING",
    "HELD",
    "COMPLETED",
    "CANCELED",
    "REJECTED"
  ],
  "examples": [
    "PENDING"
  ]
}
```

### definition-6

`#/components/schemas/ExternalReference`

```json
{
  "type": "string",
  "maxLength": 255,
  "description": "Your own identifier for this object, for correlation with your system. Optional, echoed back on reads.\n",
  "examples": [
    "wd-2026-0714-01"
  ]
}
```