# Create withdrawal

Creates a withdrawal from the selected client's Axiym account to one of the client's address book entries.

**Requirements**

- `sourceAccountId` and `destinationId` must belong to the client.
- Both accounts must be `ACTIVE` and use the same currency.
- Partner-owned and third-party external accounts are not allowed.

The response includes the withdrawal, source account, and destination details and has status `PENDING_CONFIRMATION`. Creation does not begin execution; confirm the returned `withdrawalId` with `POST /clients/{clientId}/withdrawals/{withdrawalId}/confirm`.

Product: Client Trade API
API reference version: 0.3.0 (current)
OpenAPI contract: https://docs.axiym.io/openapi/trade-api/0.3.0.yaml
Canonical page: https://docs.axiym.io/trade-api/api-reference/0.3.0/withdrawals/createWithdrawal

[Compact reference](/trade-api/api-reference/0.3.0/withdrawals/createWithdrawal.md)

## POST /clients/{clientId}/withdrawals

## Servers

```json
[
  {
    "url": "https://partner-api.sandbox.axiym.io/api/v1",
    "description": "Sandbox"
  },
  {
    "url": "https://partner-api.axiym.io/api/v1",
    "description": "Production"
  }
]
```

## Authentication

```json
{
  "security": [
    {
      "Default": []
    }
  ],
  "securitySchemes": {
    "Default": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "JWT"
    }
  }
}
```

## Parameters

### path: clientId

```json
{
  "name": "clientId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "examples": [
      "1d2f7f5e-8a3b-4c6d-9e0f-2a4b6c8d0e2f"
    ]
  },
  "description": "Client identifier (UUID) assigned when an onboarding case is created. It identifies the onboarding case and, once active, the client's Client Trade API resources. The client must belong to your partnership; anyone else's id returns 404."
}
```

### header: X-Request-Id

```json
{
  "name": "X-Request-Id",
  "in": "header",
  "required": false,
  "description": "Optional identifier for tracing a request end to end. A UUID is recommended. Axiym returns it in the `X-Request-Id` response header and records it in logs. If omitted, Axiym generates one. Include it when contacting support.\n",
  "schema": {
    "type": "string",
    "format": "uuid",
    "examples": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ]
  }
}
```

### header: Idempotency-Key

```json
{
  "name": "Idempotency-Key",
  "in": "header",
  "required": true,
  "description": "A unique key that makes a funds-moving request safe to retry. Reusing the key returns the original result instead of creating a duplicate. A UUID is recommended.",
  "schema": {
    "type": "string",
    "maxLength": 255,
    "examples": [
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    ]
  }
}
```

## Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/WithdrawalRequest"
      },
      "examples": {
        "Wallet": {
          "summary": "Wallet",
          "value": {
            "sourceAccountId": "8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a",
            "sourceAmount": {
              "amount": "500.00",
              "currency": "USDT"
            },
            "destinationId": "e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c",
            "reference": "Treasury sweep",
            "externalReference": "wd-2026-0714-01"
          }
        },
        "Bank": {
          "summary": "Bank",
          "value": {
            "sourceAccountId": "5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e",
            "sourceAmount": {
              "amount": "12500.00",
              "currency": "USD"
            },
            "destinationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "reference": "Invoice INV-20416",
            "externalReference": "wd-2026-0714-02"
          }
        }
      }
    }
  }
}
```

## Responses

### 201

```json
{
  "description": "Withdrawal created and awaiting confirmation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Withdrawal"
      },
      "examples": {
        "Wallet": {
          "summary": "Wallet",
          "value": {
            "withdrawalId": "9b4e2a1c-6d3f-4a8e-bc7d-1f2a3b4c5d6e",
            "status": "PENDING_CONFIRMATION",
            "sourceAccount": {
              "accountId": "8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a",
              "currency": "USDT",
              "paymentRails": "TRON"
            },
            "sourceAmount": {
              "amount": "500.00",
              "currency": "USDT"
            },
            "destinationAmount": {
              "amount": "500.00",
              "currency": "USDT"
            },
            "fee": {
              "amount": "0.00",
              "currency": "USDT"
            },
            "destination": {
              "destinationId": "e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c",
              "currency": "USDT",
              "walletAddress": "TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL",
              "network": "TRON"
            },
            "code": "AXI00000418",
            "reference": "Treasury sweep",
            "externalReference": "wd-2026-0714-01",
            "createdAt": "2026-07-14T20:06:50Z"
          }
        },
        "Bank": {
          "summary": "Bank",
          "value": {
            "withdrawalId": "1e7c5a3b-8d2f-4b6e-9a0c-3d5f7b9e1c2a",
            "status": "PENDING_CONFIRMATION",
            "sourceAccount": {
              "accountId": "5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e",
              "currency": "USD",
              "paymentRails": "ZENUS_BANK"
            },
            "sourceAmount": {
              "amount": "12500.00",
              "currency": "USD"
            },
            "destinationAmount": {
              "amount": "12500.00",
              "currency": "USD"
            },
            "fee": {
              "amount": "0.00",
              "currency": "USD"
            },
            "destination": {
              "destinationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
              "currency": "USD",
              "accountNumber": "0123456789",
              "bank": {
                "bankName": "Bank of America",
                "address": {
                  "city": "New York",
                  "country": "US"
                },
                "swiftBic": "BOFAUS3NXXX"
              }
            },
            "code": "AXI00000419",
            "reference": "Invoice INV-20416",
            "externalReference": "wd-2026-0714-02",
            "createdAt": "2026-07-14T20:06:50Z"
          }
        }
      }
    }
  }
}
```

### 400

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "message": {
                "type": "string"
              }
            },
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Malformed JSON body": {
          "summary": "Malformed JSON body",
          "value": {
            "code": 400,
            "message": "Bad Request",
            "errors": {
              "message": "Failed to parse the request body as JSON: expected value at line 1 column 5"
            }
          }
        },
        "Generic": {
          "summary": "Generic",
          "value": {
            "code": 400,
            "message": "Invalid cursor",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 401

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 401,
            "message": "Unauthorized",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 403

```json
{
  "description": "Forbidden",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 403,
            "message": "Forbidden",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 404

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message: either the generic 'Not Found' or a domain-specific one such as 'Client Not Found'."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Generic": {
          "summary": "Generic",
          "value": {
            "code": 404,
            "message": "Not Found",
            "errors": null
          }
        },
        "Client not found": {
          "summary": "Client not found",
          "value": {
            "code": 404,
            "message": "Client Not Found",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 422

```json
{
  "description": "The request failed validation or a business rule. Validation failures return `errors` keyed by request field. Business rejections return `errors: null` and explain the reason in `message`.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "`Invalid Parameters` for validation failures; the rejection reason otherwise."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "For validation failures, keys follow the request fields and values contain field errors or nested errors. Business rejections return `null`.",
            "additionalProperties": {
              "$ref": "#/components/schemas/ValidationFieldErrors"
            }
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Flat field errors": {
          "summary": "Flat field errors",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "legalEntityName": [
                {
                  "code": "length",
                  "message": null,
                  "params": {
                    "value": "",
                    "min": 1
                  }
                }
              ],
              "currency": [
                {
                  "code": "invalid_currency",
                  "message": null,
                  "params": {
                    "value": "ZZZ"
                  }
                }
              ]
            }
          }
        },
        "Nested struct errors": {
          "summary": "Nested struct errors",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "legalAddress": {
                "country": [
                  {
                    "code": "invalid_country",
                    "message": null,
                    "params": {
                      "value": "INVALID"
                    }
                  }
                ],
                "postalCode": [
                  {
                    "code": "length",
                    "message": null,
                    "params": {
                      "value": "",
                      "min": 1
                    }
                  }
                ]
              }
            }
          }
        },
        "List item errors": {
          "summary": "List item errors",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "authorizedDirectors": {
                "0": {
                  "firstName": [
                    {
                      "code": "length",
                      "message": null,
                      "params": {
                        "value": "",
                        "min": 1
                      }
                    }
                  ],
                  "email": [
                    {
                      "code": "email",
                      "message": null,
                      "params": {
                        "value": "not-an-email"
                      }
                    }
                  ]
                }
              }
            }
          }
        },
        "Custom validator": {
          "summary": "Custom validator",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "disbursementAccount": [
                {
                  "code": "disbursement_account_required",
                  "message": null,
                  "params": {
                    "value": null
                  }
                }
              ]
            }
          }
        },
        "Business rejection": {
          "summary": "Business rejection",
          "value": {
            "code": 422,
            "message": "Documents Not Accepted",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### 500

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 500,
            "message": "Internal Error",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

## Operation metadata

```json
{
  "tags": [
    "Withdrawals"
  ],
  "x-axiym-navigation-order": 20,
  "operationId": "createWithdrawal"
}
```

## Referenced definitions

- [`#/components/parameters/ClientId`](#definition-1)
- [`#/components/parameters/RequestId`](#definition-2)
- [`#/components/parameters/IdempotencyKey`](#definition-3)
- [`#/components/schemas/WithdrawalRequest`](#definition-4)
- [`#/components/schemas/Money`](#definition-5)
- [`#/components/schemas/Decimal`](#definition-6)
- [`#/components/schemas/Currency`](#definition-7)
- [`#/components/schemas/SupportingDocumentInput`](#definition-8)
- [`#/components/schemas/SupportingDocumentType`](#definition-9)
- [`#/components/schemas/ExternalReference`](#definition-10)
- [`#/components/schemas/Withdrawal`](#definition-11)
- [`#/components/schemas/AccountRef`](#definition-12)
- [`#/components/schemas/PaymentRailsCode`](#definition-13)
- [`#/components/schemas/Destination`](#definition-14)
- [`#/components/schemas/BankDestination`](#definition-15)
- [`#/components/schemas/Bank`](#definition-16)
- [`#/components/schemas/BankAddress`](#definition-17)
- [`#/components/schemas/CountryCode`](#definition-18)
- [`#/components/schemas/WalletDestination`](#definition-19)
- [`#/components/schemas/Network`](#definition-20)
- [`#/components/schemas/WithdrawalStatus`](#definition-21)
- [`#/components/schemas/SupportingDocument`](#definition-22)
- [`#/components/responses/BadRequest`](#definition-23)
- [`#/components/responses/Unauthorized`](#definition-24)
- [`#/components/responses/Forbidden`](#definition-25)
- [`#/components/responses/NotFound`](#definition-26)
- [`#/components/responses/InvalidParams`](#definition-27)
- [`#/components/schemas/ValidationFieldErrors`](#definition-28)
- [`#/components/schemas/ValidationError`](#definition-29)
- [`#/components/responses/InternalError`](#definition-30)

### definition-1

`#/components/parameters/ClientId`

```json
{
  "name": "clientId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "examples": [
      "1d2f7f5e-8a3b-4c6d-9e0f-2a4b6c8d0e2f"
    ]
  },
  "description": "Client identifier (UUID) assigned when an onboarding case is created. It identifies the onboarding case and, once active, the client's Client Trade API resources. The client must belong to your partnership; anyone else's id returns 404."
}
```

### definition-2

`#/components/parameters/RequestId`

```json
{
  "name": "X-Request-Id",
  "in": "header",
  "required": false,
  "description": "Optional identifier for tracing a request end to end. A UUID is recommended. Axiym returns it in the `X-Request-Id` response header and records it in logs. If omitted, Axiym generates one. Include it when contacting support.\n",
  "schema": {
    "type": "string",
    "format": "uuid",
    "examples": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ]
  }
}
```

### definition-3

`#/components/parameters/IdempotencyKey`

```json
{
  "name": "Idempotency-Key",
  "in": "header",
  "required": true,
  "description": "A unique key that makes a funds-moving request safe to retry. Reusing the key returns the original result instead of creating a duplicate. A UUID is recommended.",
  "schema": {
    "type": "string",
    "maxLength": 255,
    "examples": [
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    ]
  }
}
```

### definition-4

`#/components/schemas/WithdrawalRequest`

```json
{
  "type": "object",
  "description": "A withdrawal from `sourceAccountId` to an address book entry. `sourceAmount` is debited from the source account in its currency. The `destinationId` must be `ACTIVE` and use the same currency. Creating the withdrawal returns `PENDING_CONFIRMATION`; call `POST /clients/{clientId}/withdrawals/{withdrawalId}/confirm` to begin execution.\n",
  "additionalProperties": false,
  "required": [
    "sourceAccountId",
    "sourceAmount",
    "destinationId"
  ],
  "properties": {
    "sourceAccountId": {
      "type": "string",
      "format": "uuid",
      "description": "Source account identifier (UUID).",
      "examples": [
        "8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a"
      ]
    },
    "sourceAmount": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Money"
        }
      ],
      "description": "Amount to debit from the source account. Its currency must be the source account currency."
    },
    "destinationId": {
      "type": "string",
      "format": "uuid",
      "description": "Identifier of the address book entry to pay. It must be `ACTIVE` and in the source Axiym account's currency.",
      "examples": [
        "e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c"
      ]
    },
    "reference": {
      "type": "string",
      "maxLength": 140,
      "description": "Text shown to the recipient, typically the invoice number.",
      "examples": [
        "Invoice INV-20416"
      ]
    },
    "supportingDocuments": {
      "type": "array",
      "maxItems": 10,
      "items": {
        "$ref": "#/components/schemas/SupportingDocumentInput"
      },
      "description": "Documents supporting the payment, such as an invoice. Required where the destination corridor requires evidence."
    },
    "externalReference": {
      "$ref": "#/components/schemas/ExternalReference",
      "description": "Your reference for correlation, echoed back on related objects.",
      "examples": [
        "wd-2026-0714-01"
      ]
    }
  }
}
```

### definition-5

`#/components/schemas/Money`

```json
{
  "type": "object",
  "description": "Monetary amount and its currency.",
  "additionalProperties": false,
  "required": [
    "amount",
    "currency"
  ],
  "properties": {
    "amount": {
      "$ref": "#/components/schemas/Decimal"
    },
    "currency": {
      "$ref": "#/components/schemas/Currency"
    }
  }
}
```

### definition-6

`#/components/schemas/Decimal`

```json
{
  "type": "string",
  "description": "Decimal number serialized as a string to preserve precision. Amounts sent to Axiym are positive and carry at most 8 decimal places.",
  "examples": [
    "1000.00"
  ]
}
```

### definition-7

`#/components/schemas/Currency`

```json
{
  "type": "string",
  "description": "Currency code — ISO 4217 (e.g. USD, EUR) or a supported digital currency (USDT, USDC).",
  "examples": [
    "USD"
  ]
}
```

### definition-8

`#/components/schemas/SupportingDocumentInput`

```json
{
  "type": "object",
  "description": "A document supporting the payment, such as an invoice or contract. One item is one file of up to 10 MB in PDF, JPEG or PNG format; supply the file content as base64.",
  "additionalProperties": false,
  "required": [
    "documentType",
    "data",
    "name"
  ],
  "properties": {
    "documentType": {
      "$ref": "#/components/schemas/SupportingDocumentType"
    },
    "data": {
      "type": "string",
      "contentEncoding": "base64",
      "description": "Complete file encoded as base64 from its raw bytes. Do not include a data-URL prefix."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "File name, including the extension.",
      "examples": [
        "INV-20416.pdf"
      ]
    }
  }
}
```

### definition-9

`#/components/schemas/SupportingDocumentType`

```json
{
  "type": "string",
  "description": "Axiym classification of evidence supplied with a payout.",
  "enum": [
    "PASSPORT",
    "NATIONAL_ID",
    "DRIVER_LICENSE",
    "RESIDENCE_PERMIT",
    "PROOF_OF_ADDRESS",
    "UTILITY_BILL",
    "BANK_STATEMENT",
    "TAX_CERTIFICATE",
    "CERTIFICATE_OF_INCORPORATION",
    "REGISTRY_EXTRACT",
    "ARTICLES_OF_ASSOCIATION",
    "SHAREHOLDER_REGISTER",
    "DIRECTOR_REGISTER",
    "UBO_DECLARATION",
    "POWER_OF_ATTORNEY",
    "BOARD_RESOLUTION",
    "REGULATORY_LICENSE",
    "BUSINESS_LICENSE",
    "FINANCIAL_STATEMENT",
    "AUDIT_REPORT",
    "SOURCE_OF_FUNDS",
    "INVOICE",
    "CONTRACT",
    "PURCHASE_ORDER",
    "PAYROLL_FILE",
    "LOAN_AGREEMENT",
    "SHIPPING_DOCUMENT",
    "CUSTOMS_DECLARATION",
    "OTHER"
  ],
  "examples": [
    "INVOICE"
  ]
}
```

### definition-10

`#/components/schemas/ExternalReference`

```json
{
  "type": "string",
  "maxLength": 255,
  "description": "Your optional identifier for correlating the resource with your system. Axiym returns it on reads. It does not make retries safe; use `Idempotency-Key` for that.\n",
  "examples": [
    "wd-2026-0714-01"
  ]
}
```

### definition-11

`#/components/schemas/Withdrawal`

```json
{
  "type": "object",
  "required": [
    "withdrawalId",
    "sourceAccount",
    "sourceAmount",
    "destinationAmount",
    "fee",
    "destination",
    "status",
    "createdAt"
  ],
  "properties": {
    "withdrawalId": {
      "type": "string",
      "format": "uuid",
      "description": "Withdrawal identifier (UUID).",
      "examples": [
        "9b4e2a1c-6d3f-4a8e-bc7d-1f2a3b4c5d6e"
      ]
    },
    "sourceAccount": {
      "allOf": [
        {
          "$ref": "#/components/schemas/AccountRef"
        }
      ],
      "description": "The source account, embedded as a compact reference."
    },
    "sourceAmount": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Money"
        }
      ],
      "description": "Amount debited from the source account, in the source account currency."
    },
    "destinationAmount": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Money"
        }
      ],
      "description": "Amount delivered to the destination, in the destination currency. Equals `sourceAmount` less `fee`."
    },
    "fee": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Money"
        }
      ],
      "description": "Total deducted from `sourceAmount` before delivery, in the source account currency. Zero when no fee applies."
    },
    "destination": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Destination"
        }
      ],
      "description": "Snapshot of the destination selected by `destinationId` at creation time."
    },
    "status": {
      "$ref": "#/components/schemas/WithdrawalStatus",
      "description": "Withdrawal status.",
      "examples": [
        "COMPLETED"
      ]
    },
    "code": {
      "type": "string",
      "description": "System-assigned payment code, shown on the payment.",
      "examples": [
        "AXI00000418"
      ]
    },
    "reference": {
      "type": "string",
      "description": "Text shown to the recipient, as submitted.",
      "examples": [
        "Treasury sweep"
      ]
    },
    "supportingDocuments": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SupportingDocument"
      },
      "description": "Documents accepted with the payment. File content is not returned."
    },
    "externalReference": {
      "$ref": "#/components/schemas/ExternalReference",
      "description": "Your reference for correlation, echoed back on related objects.",
      "examples": [
        "wd-2026-0714-01"
      ]
    },
    "transactionHash": {
      "type": "string",
      "description": "The transaction hash on the network. Present for wallet withdrawals once the withdrawal is `COMPLETED`.",
      "examples": [
        "9f8e7d6c5b4a39281706f5e4d3c2b1a0998877665544332211ffeeddccbbaa00"
      ]
    },
    "reasonCode": {
      "type": "string",
      "description": "Present when `status` is `CANCELED` or `REJECTED` — the cancellation/rejection reason as reported by the bank, the network, or Axiym operations. Example: `INSUFFICIENT_BENEFICIARY_DETAILS`."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Creation timestamp. Formatted in ISO 8601.",
      "examples": [
        "2026-07-14T20:06:50Z"
      ]
    }
  }
}
```

### definition-12

`#/components/schemas/AccountRef`

```json
{
  "type": "object",
  "description": "Compact account reference. Fetch the account via `GET /clients/{clientId}/accounts/{accountId}` for the current balance and status; deposit instructions serve its payment details.",
  "required": [
    "accountId",
    "currency",
    "paymentRails"
  ],
  "properties": {
    "accountId": {
      "type": "string",
      "format": "uuid",
      "description": "Account identifier (UUID).",
      "examples": [
        "5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e"
      ]
    },
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Account currency.",
      "examples": [
        "USD"
      ]
    },
    "paymentRails": {
      "$ref": "#/components/schemas/PaymentRailsCode",
      "description": "Rail the account settles on.",
      "examples": [
        "ZENUS_BANK"
      ]
    }
  }
}
```

### definition-13

`#/components/schemas/PaymentRailsCode`

```json
{
  "type": "string",
  "description": "Payment rail code the account settles on (e.g. `ZENUS_BANK`, `TRON`).",
  "examples": [
    "ZENUS_BANK"
  ]
}
```

### definition-14

`#/components/schemas/Destination`

```json
{
  "description": "Where the funds are delivered, as recorded on the operation at creation time. This is a snapshot: it carries the account or wallet details and, when the destination was taken from the address book, its `destinationId`. It does not carry the address book entry's status or creation date; read the address book entry for its current state.\n\n- A bank destination contains `accountNumber` and `bank`.\n- A wallet destination contains `walletAddress` and `network`.\n\nThe two field sets never appear together.",
  "oneOf": [
    {
      "$ref": "#/components/schemas/BankDestination"
    },
    {
      "$ref": "#/components/schemas/WalletDestination"
    }
  ]
}
```

### definition-15

`#/components/schemas/BankDestination`

```json
{
  "type": "object",
  "title": "Bank account",
  "required": [
    "currency",
    "accountNumber",
    "bank"
  ],
  "properties": {
    "destinationId": {
      "type": "string",
      "format": "uuid",
      "description": "Address book entry the destination was taken from, when applicable.",
      "examples": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    },
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Currency delivered to the destination.",
      "examples": [
        "USD"
      ]
    },
    "accountNumber": {
      "type": "string",
      "description": "Bank account number or IBAN.",
      "examples": [
        "0123456789"
      ]
    },
    "bank": {
      "$ref": "#/components/schemas/Bank",
      "description": "Destination bank details."
    }
  }
}
```

### definition-16

`#/components/schemas/Bank`

```json
{
  "type": "object",
  "description": "Destination bank details. Present on bank destinations only. The address country selects the applicable corridor rules.",
  "additionalProperties": false,
  "required": [
    "bankName",
    "address"
  ],
  "properties": {
    "bankName": {
      "type": "string",
      "minLength": 1,
      "description": "Bank name.",
      "examples": [
        "Bank of America"
      ]
    },
    "address": {
      "$ref": "#/components/schemas/BankAddress"
    },
    "swiftBic": {
      "type": "string",
      "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$",
      "description": "ISO 9362 SWIFT/BIC, when required for the corridor.",
      "examples": [
        "BOFAUS3NXXX"
      ]
    },
    "clearingCode": {
      "type": "string",
      "description": "Local clearing or routing code, when required for the corridor.",
      "examples": [
        "026009593"
      ]
    },
    "clearingSystemCode": {
      "type": "string",
      "description": "Clearing system the code belongs to. Axiym derives it from the bank country; supply it where a country has more than one system.",
      "examples": [
        "USABA"
      ]
    }
  }
}
```

### definition-17

`#/components/schemas/BankAddress`

```json
{
  "type": "object",
  "description": "Postal address of the bank. Only the country is required — it selects the corridor rules. Supply the rest when the corridor or a correspondent asks for it.",
  "additionalProperties": false,
  "required": [
    "country"
  ],
  "properties": {
    "streetName": {
      "type": "string"
    },
    "buildingNumber": {
      "type": "string"
    },
    "city": {
      "type": "string",
      "examples": [
        "New York"
      ]
    },
    "region": {
      "type": "string"
    },
    "postalCode": {
      "type": "string"
    },
    "country": {
      "$ref": "#/components/schemas/CountryCode"
    }
  }
}
```

### definition-18

`#/components/schemas/CountryCode`

```json
{
  "type": "string",
  "pattern": "^[A-Z]{2}$",
  "description": "ISO 3166-1 alpha-2 country code.",
  "examples": [
    "US"
  ]
}
```

### definition-19

`#/components/schemas/WalletDestination`

```json
{
  "type": "object",
  "title": "Wallet address",
  "required": [
    "currency",
    "walletAddress",
    "network"
  ],
  "properties": {
    "destinationId": {
      "type": "string",
      "format": "uuid",
      "description": "Address book entry the destination was taken from, when applicable.",
      "examples": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    },
    "currency": {
      "$ref": "#/components/schemas/Currency",
      "description": "Currency delivered to the destination.",
      "examples": [
        "USDT"
      ]
    },
    "walletAddress": {
      "type": "string",
      "description": "Wallet address on the given network.",
      "examples": [
        "TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL"
      ]
    },
    "network": {
      "$ref": "#/components/schemas/Network",
      "description": "Network of the wallet address.",
      "examples": [
        "TRON"
      ]
    }
  }
}
```

### definition-20

`#/components/schemas/Network`

```json
{
  "type": "string",
  "description": "Wallet network.",
  "enum": [
    "TRON",
    "AVALANCHE"
  ],
  "examples": [
    "TRON"
  ]
}
```

### definition-21

`#/components/schemas/WithdrawalStatus`

```json
{
  "type": "string",
  "description": "`PENDING_CONFIRMATION` is awaiting explicit confirmation and has not started execution. `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_CONFIRMATION",
    "PENDING",
    "HELD",
    "COMPLETED",
    "CANCELED",
    "REJECTED"
  ],
  "examples": [
    "PENDING"
  ]
}
```

### definition-22

`#/components/schemas/SupportingDocument`

```json
{
  "type": "object",
  "description": "Metadata of a document accepted with the payment. File content is not returned.",
  "additionalProperties": false,
  "required": [
    "documentType",
    "fileId",
    "name",
    "contentType",
    "size"
  ],
  "properties": {
    "documentType": {
      "$ref": "#/components/schemas/SupportingDocumentType"
    },
    "fileId": {
      "type": "string",
      "format": "uuid",
      "description": "Identifier of the stored file."
    },
    "name": {
      "type": "string",
      "description": "File name supplied with the document."
    },
    "contentType": {
      "type": "string",
      "description": "MIME type detected from the file content.",
      "examples": [
        "application/pdf"
      ]
    },
    "size": {
      "type": "integer",
      "description": "File size in bytes."
    }
  }
}
```

### definition-23

`#/components/responses/BadRequest`

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "message": {
                "type": "string"
              }
            },
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Malformed JSON body": {
          "summary": "Malformed JSON body",
          "value": {
            "code": 400,
            "message": "Bad Request",
            "errors": {
              "message": "Failed to parse the request body as JSON: expected value at line 1 column 5"
            }
          }
        },
        "Generic": {
          "summary": "Generic",
          "value": {
            "code": 400,
            "message": "Invalid cursor",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### definition-24

`#/components/responses/Unauthorized`

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 401,
            "message": "Unauthorized",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### definition-25

`#/components/responses/Forbidden`

```json
{
  "description": "Forbidden",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 403,
            "message": "Forbidden",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### definition-26

`#/components/responses/NotFound`

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message: either the generic 'Not Found' or a domain-specific one such as 'Client Not Found'."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Generic": {
          "summary": "Generic",
          "value": {
            "code": 404,
            "message": "Not Found",
            "errors": null
          }
        },
        "Client not found": {
          "summary": "Client not found",
          "value": {
            "code": 404,
            "message": "Client Not Found",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### definition-27

`#/components/responses/InvalidParams`

```json
{
  "description": "The request failed validation or a business rule. Validation failures return `errors` keyed by request field. Business rejections return `errors: null` and explain the reason in `message`.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "`Invalid Parameters` for validation failures; the rejection reason otherwise."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "For validation failures, keys follow the request fields and values contain field errors or nested errors. Business rejections return `null`.",
            "additionalProperties": {
              "$ref": "#/components/schemas/ValidationFieldErrors"
            }
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Flat field errors": {
          "summary": "Flat field errors",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "legalEntityName": [
                {
                  "code": "length",
                  "message": null,
                  "params": {
                    "value": "",
                    "min": 1
                  }
                }
              ],
              "currency": [
                {
                  "code": "invalid_currency",
                  "message": null,
                  "params": {
                    "value": "ZZZ"
                  }
                }
              ]
            }
          }
        },
        "Nested struct errors": {
          "summary": "Nested struct errors",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "legalAddress": {
                "country": [
                  {
                    "code": "invalid_country",
                    "message": null,
                    "params": {
                      "value": "INVALID"
                    }
                  }
                ],
                "postalCode": [
                  {
                    "code": "length",
                    "message": null,
                    "params": {
                      "value": "",
                      "min": 1
                    }
                  }
                ]
              }
            }
          }
        },
        "List item errors": {
          "summary": "List item errors",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "authorizedDirectors": {
                "0": {
                  "firstName": [
                    {
                      "code": "length",
                      "message": null,
                      "params": {
                        "value": "",
                        "min": 1
                      }
                    }
                  ],
                  "email": [
                    {
                      "code": "email",
                      "message": null,
                      "params": {
                        "value": "not-an-email"
                      }
                    }
                  ]
                }
              }
            }
          }
        },
        "Custom validator": {
          "summary": "Custom validator",
          "value": {
            "code": 422,
            "message": "Invalid Parameters",
            "errors": {
              "disbursementAccount": [
                {
                  "code": "disbursement_account_required",
                  "message": null,
                  "params": {
                    "value": null
                  }
                }
              ]
            }
          }
        },
        "Business rejection": {
          "summary": "Business rejection",
          "value": {
            "code": 422,
            "message": "Documents Not Accepted",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```

### definition-28

`#/components/schemas/ValidationFieldErrors`

```json
{
  "description": "Nested validation errors keyed by field name or array index. Leaf values are arrays of `ValidationError` objects.",
  "oneOf": [
    {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ValidationError"
      }
    },
    {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/components/schemas/ValidationFieldErrors"
      },
      "properties": {}
    }
  ]
}
```

### definition-29

`#/components/schemas/ValidationError`

```json
{
  "type": "object",
  "description": "One field-level validation error.",
  "properties": {
    "code": {
      "type": "string",
      "description": "Validation rule code (e.g. 'length', 'email', 'invalid_currency', 'disbursement_account_required').",
      "examples": [
        "length"
      ]
    },
    "message": {
      "type": [
        "string",
        "null"
      ],
      "description": "Human-readable message.",
      "examples": [
        "string"
      ]
    },
    "params": {
      "type": "object",
      "description": "Rule-specific parameters. Always includes `value` (the offending input). Additional keys depend on the rule (e.g. `min`, `max` for length).",
      "properties": {
        "value": {
          "description": "The submitted value that failed validation.",
          "examples": [
            "string"
          ]
        }
      }
    }
  },
  "required": [
    "code",
    "params"
  ]
}
```

### definition-30

`#/components/responses/InternalError`

```json
{
  "description": "",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "HTTP status code, duplicated in the body."
          },
          "message": {
            "type": "string",
            "description": "Human-readable message describing the error."
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "Additional error details; null when there are none."
          }
        },
        "required": [
          "code",
          "message",
          "errors"
        ]
      },
      "examples": {
        "Example 1": {
          "summary": "Example 1",
          "value": {
            "code": 500,
            "message": "Internal Error",
            "errors": null
          }
        }
      }
    }
  },
  "headers": {
    "X-Request-Id": {
      "description": "Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "examples": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    }
  }
}
```