# Get withdrawal

Returns the current state of one withdrawal, including its source account, destination, amounts, fee, and any completed wallet transaction hash.

Use this as the authoritative status after creation or confirmation and when processing withdrawal webhooks.

Product: Account API
API reference version: 0.3.0 (current)
OpenAPI contract: https://docs.axiym.io/openapi/account-api/0.3.0.yaml
Canonical page: https://docs.axiym.io/account-api/api-reference/0.3.0/withdrawals/getWithdrawal

[Compact reference](/account-api/api-reference/0.3.0/withdrawals/getWithdrawal.md)

## GET /withdrawals/{withdrawalId}

## 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: withdrawalId

```json
{
  "name": "withdrawalId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "examples": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ]
  },
  "description": "Withdrawal identifier (UUID)."
}
```

### header: X-Request-Id

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

## Responses

### 200

```json
{
  "description": "Withdrawal.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Withdrawal"
      },
      "examples": {
        "Wallet (completed)": {
          "summary": "Wallet (completed)",
          "value": {
            "withdrawalId": "9b4e2a1c-6d3f-4a8e-bc7d-1f2a3b4c5d6e",
            "status": "COMPLETED",
            "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",
            "transactionHash": "9f8e7d6c5b4a39281706f5e4d3c2b1a0998877665544332211ffeeddccbbaa00",
            "reference": "Treasury sweep",
            "externalReference": "wd-2026-0714-01",
            "createdAt": "2026-07-14T20:06:50Z"
          }
        },
        "Bank (completed)": {
          "summary": "Bank (completed)",
          "value": {
            "withdrawalId": "1e7c5a3b-8d2f-4b6e-9a0c-3d5f7b9e1c2a",
            "status": "COMPLETED",
            "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 could not be processed. Two variants share this status: a validation failure, where `errors` is an object keyed by field name, and a business rejection, where `errors` is null and `message` states the reason (e.g. `Documents Not Accepted` when uploading to an already decided onboarding application, or the generic `Unprocessable Request`).",
  "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": "Validation failures: object keyed by field name (camelCase); each value is either an array of ValidationError records (leaf), a nested object for struct fields, or an object keyed by array index for list fields. Business rejections: 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": 40,
  "operationId": "getWithdrawal"
}
```

## Referenced definitions

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

### definition-1

`#/components/parameters/WithdrawalId`

```json
{
  "name": "withdrawalId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "examples": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ]
  },
  "description": "Withdrawal identifier (UUID)."
}
```

### definition-2

`#/components/parameters/RequestId`

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

### definition-3

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

`#/components/schemas/AccountRef`

```json
{
  "type": "object",
  "description": "Compact account reference. Fetch the account via `GET /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-5

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

`#/components/schemas/PaymentRailsCode`

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

### definition-7

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

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

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

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

`#/components/schemas/Bank`

```json
{
  "type": "object",
  "description": "Destination bank details. Present on bank destinations only.\n\nThe bank address country selects the applicable payout corridor rules. Supply `swiftBic`, `clearingCode`, or `clearingSystemCode` when that corridor requires them.",
  "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-12

`#/components/schemas/BankAddress`

```json
{
  "type": "object",
  "description": "Postal address of the destination bank.\n\n`country` is always required because it selects the applicable corridor rules. Supply the remaining address fields when the corridor or a correspondent requires them.",
  "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-13

`#/components/schemas/CountryCode`

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

### definition-14

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

`#/components/schemas/Network`

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

### definition-16

`#/components/schemas/WithdrawalStatus`

```json
{
  "type": "string",
  "description": "- `PENDING_CONFIRMATION` — created and awaiting confirmation.\n- `PENDING` — confirmed and awaiting execution.\n- `HELD` — temporarily on hold; no action is needed.\n- `COMPLETED` — completed successfully.\n- `CANCELED` or `REJECTED` — not completed; see `reasonCode` when present.",
  "enum": [
    "PENDING_CONFIRMATION",
    "PENDING",
    "HELD",
    "COMPLETED",
    "CANCELED",
    "REJECTED"
  ],
  "examples": [
    "PENDING"
  ]
}
```

### definition-17

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

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

`#/components/schemas/ExternalReference`

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

### definition-20

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

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

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

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

`#/components/responses/InvalidParams`

```json
{
  "description": "The request could not be processed. Two variants share this status: a validation failure, where `errors` is an object keyed by field name, and a business rejection, where `errors` is null and `message` states the reason (e.g. `Documents Not Accepted` when uploading to an already decided onboarding application, or the generic `Unprocessable Request`).",
  "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": "Validation failures: object keyed by field name (camelCase); each value is either an array of ValidationError records (leaf), a nested object for struct fields, or an object keyed by array index for list fields. Business rejections: 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-25

`#/components/schemas/ValidationFieldErrors`

```json
{
  "description": "Recursive validation-error structure.\n\n- A leaf field contains an array of `ValidationError` records.\n- A nested object is keyed by field name.\n- A list is keyed by array index.",
  "oneOf": [
    {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ValidationError"
      }
    },
    {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/components/schemas/ValidationFieldErrors"
      },
      "properties": {}
    }
  ]
}
```

### definition-26

`#/components/schemas/ValidationError`

```json
{
  "type": "object",
  "description": "Single validation error from the `validator` crate.",
  "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-27

`#/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"
        ]
      }
    }
  }
}
```