> For the complete documentation index, see [llms.txt](https://www.pionex.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.pionex.com/docs/api-docs/institution-api/payout.md).
# Payout
Fiat withdrawal (payout) orders (requires platform KYB APPROVED).
## Create a payout (fiat withdrawal)
> Create a payout (fiat withdrawal). Requires the \`userId\`'s platform KYB to\
> be \`APPROVED\`.\
> \
> \*\*Idempotency:\*\* always send a unique \`clientOrderId\`; on timeout/no-response,\
> re-send with the \*\*same\*\* \`clientOrderId\` (or query first via List/Get\
> Payout Order) - never retry with a new key.
```json
{"openapi":"3.0.3","info":{"title":"Pionex Institution Open API (v2)","version":"2.0.0"},"tags":[{"name":"Payout","description":"Fiat withdrawal (payout) orders (requires platform KYB APPROVED)."}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"ApiKey":[],"Signature":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-APIKEY","description":"Your institution API Key, in the form `webot_xxxxxxxx`. Used to look up\nyour registered public key. Must be accompanied by the `X-Signature`\nheader. See the Authentication section for the full signing algorithm\n(RSA-PSS over SHA-256, or Ed25519) and the canonical-string construction.\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current time in **seconds** (Unix). Required on every signed request and\nparticipates in the signature. Must be within +/-5 seconds of server time.\n","schema":{"type":"integer","format":"int64"}}},"schemas":{"KeyValue":{"type":"object","description":"A generic key/value pair.","properties":{"key":{"type":"string"},"value":{"type":"string"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Success indicator."},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds."},"code":{"type":"string","description":"Error code (present only on failure)."},"message":{"type":"string","description":"Error message (present only on failure)."}}},"Reason":{"type":"object","description":"Failure/return reason, present only when a channel returns one.","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean","description":"Whether the same request/order may be retried."}}}},"responses":{"BadRequest":{"description":"Bad Request - the request body could not be read.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"Unauthorized":{"description":"Unauthorized - authentication failed (missing key, bad signature, etc.).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"InternalError":{"description":"Internal or business error. Note that most business failures are returned\nas HTTP `200` with `result: false` and a `code`; this `500` covers\nserver-side internal errors.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}}}},"paths":{"/api/v2/institution/wire/payout/order/create":{"post":{"tags":["Payout"],"summary":"Create a payout (fiat withdrawal)","description":"Create a payout (fiat withdrawal). Requires the `userId`'s platform KYB to\nbe `APPROVED`.\n\n**Idempotency:** always send a unique `clientOrderId`; on timeout/no-response,\nre-send with the **same** `clientOrderId` (or query first via List/Get\nPayout Order) - never retry with a new key.\n","operationId":"institutionPayoutOrderCreate","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["userId","clientOrderId"],"properties":{"userId":{"type":"string","description":"Sub-account UUID."},"clientOrderId":{"type":"string","description":"Globally unique idempotency key. Retries must reuse the original value."},"channel":{"type":"string"},"payoutAccountId":{"type":"string","description":"Target payout account (`accountId` from Create/List Payout Account)."},"sourceCurrency":{"type":"string","description":"Debit asset code (e.g. `USDT`)."},"targetCurrency":{"type":"string","description":"Credited asset code (e.g. `USD`)."},"amount":{"type":"string","description":"Total debit amount, in `sourceCurrency`."},"channelExtra":{"type":"array","items":{"$ref":"#/components/schemas/KeyValue"}}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"orderId":{"type":"string"},"status":{"type":"string"},"amount":{"type":"string"},"feeAmount":{"type":"string"},"finalAmount":{"type":"string"},"reason":{"$ref":"#/components/schemas/Reason"}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```
## List payout orders
> List payout orders for a \`userId\`. Requires the \`userId\`'s platform KYB to\
> be \`APPROVED\`.
```json
{"openapi":"3.0.3","info":{"title":"Pionex Institution Open API (v2)","version":"2.0.0"},"tags":[{"name":"Payout","description":"Fiat withdrawal (payout) orders (requires platform KYB APPROVED)."}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"ApiKey":[],"Signature":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-APIKEY","description":"Your institution API Key, in the form `webot_xxxxxxxx`. Used to look up\nyour registered public key. Must be accompanied by the `X-Signature`\nheader. See the Authentication section for the full signing algorithm\n(RSA-PSS over SHA-256, or Ed25519) and the canonical-string construction.\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current time in **seconds** (Unix). Required on every signed request and\nparticipates in the signature. Must be within +/-5 seconds of server time.\n","schema":{"type":"integer","format":"int64"}},"UserIdQueryRequired":{"name":"userId","in":"query","required":true,"description":"Target sub-account UUID. Participates in the signature.","schema":{"type":"string"}},"StartTime":{"name":"startTime","in":"query","required":false,"description":"Start time, millisecond Unix timestamp.","schema":{"type":"integer","format":"int64"}},"EndTime":{"name":"endTime","in":"query","required":false,"description":"End time, millisecond Unix timestamp.","schema":{"type":"integer","format":"int64"}},"Page":{"name":"page","in":"query","required":false,"description":"Page number, starting from 1.","schema":{"type":"integer"}},"Size":{"name":"size","in":"query","required":false,"description":"Page size.","schema":{"type":"integer"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Success indicator."},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds."},"code":{"type":"string","description":"Error code (present only on failure)."},"message":{"type":"string","description":"Error message (present only on failure)."}}},"PayoutOrder":{"type":"object","properties":{"orderId":{"type":"string"},"clientOrderId":{"type":"string"},"channel":{"type":"string"},"payoutAccountId":{"type":"string"},"sourceCurrency":{"type":"string"},"targetCurrency":{"type":"string"},"amount":{"type":"string"},"feeAmount":{"type":"string"},"finalAmount":{"type":"string"},"rate":{"type":"string"},"status":{"type":"string","enum":["PENDING","IN_REVIEW","PROCESSING","COMPLETED","FAILED","RETURNED","REFUNDING","REFUNDED"],"description":"`COMPLETED` / `FAILED` are final."},"reason":{"$ref":"#/components/schemas/Reason"},"rail":{"type":"string"},"createdAt":{"type":"integer","format":"int64"},"updatedAt":{"type":"integer","format":"int64"},"completedAt":{"type":"integer","format":"int64","description":"`0` before the order is final."},"refundedAt":{"type":"integer","format":"int64","description":"`0` before any refund."}}},"Reason":{"type":"object","description":"Failure/return reason, present only when a channel returns one.","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean","description":"Whether the same request/order may be retried."}}}},"responses":{"BadRequest":{"description":"Bad Request - the request body could not be read.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"Unauthorized":{"description":"Unauthorized - authentication failed (missing key, bad signature, etc.).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"InternalError":{"description":"Internal or business error. Note that most business failures are returned\nas HTTP `200` with `result: false` and a `code`; this `500` covers\nserver-side internal errors.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}}}},"paths":{"/api/v2/institution/wire/payout/orders":{"get":{"tags":["Payout"],"summary":"List payout orders","description":"List payout orders for a `userId`. Requires the `userId`'s platform KYB to\nbe `APPROVED`.\n","operationId":"institutionPayoutOrdersList","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"$ref":"#/components/parameters/UserIdQueryRequired"},{"name":"channel","in":"query","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/StartTime"},{"$ref":"#/components/parameters/EndTime"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/Size"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/PayoutOrder"}},"total":{"type":"integer"}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```
## Get a payout order
> Get a single payout order by \`orderId\` \*\*or\*\* \`clientOrderId\`. Requires the\
> \`userId\`'s platform KYB to be \`APPROVED\`.
```json
{"openapi":"3.0.3","info":{"title":"Pionex Institution Open API (v2)","version":"2.0.0"},"tags":[{"name":"Payout","description":"Fiat withdrawal (payout) orders (requires platform KYB APPROVED)."}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"ApiKey":[],"Signature":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-APIKEY","description":"Your institution API Key, in the form `webot_xxxxxxxx`. Used to look up\nyour registered public key. Must be accompanied by the `X-Signature`\nheader. See the Authentication section for the full signing algorithm\n(RSA-PSS over SHA-256, or Ed25519) and the canonical-string construction.\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current time in **seconds** (Unix). Required on every signed request and\nparticipates in the signature. Must be within +/-5 seconds of server time.\n","schema":{"type":"integer","format":"int64"}},"UserIdQueryRequired":{"name":"userId","in":"query","required":true,"description":"Target sub-account UUID. Participates in the signature.","schema":{"type":"string"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Success indicator."},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds."},"code":{"type":"string","description":"Error code (present only on failure)."},"message":{"type":"string","description":"Error message (present only on failure)."}}},"PayoutOrder":{"type":"object","properties":{"orderId":{"type":"string"},"clientOrderId":{"type":"string"},"channel":{"type":"string"},"payoutAccountId":{"type":"string"},"sourceCurrency":{"type":"string"},"targetCurrency":{"type":"string"},"amount":{"type":"string"},"feeAmount":{"type":"string"},"finalAmount":{"type":"string"},"rate":{"type":"string"},"status":{"type":"string","enum":["PENDING","IN_REVIEW","PROCESSING","COMPLETED","FAILED","RETURNED","REFUNDING","REFUNDED"],"description":"`COMPLETED` / `FAILED` are final."},"reason":{"$ref":"#/components/schemas/Reason"},"rail":{"type":"string"},"createdAt":{"type":"integer","format":"int64"},"updatedAt":{"type":"integer","format":"int64"},"completedAt":{"type":"integer","format":"int64","description":"`0` before the order is final."},"refundedAt":{"type":"integer","format":"int64","description":"`0` before any refund."}}},"Reason":{"type":"object","description":"Failure/return reason, present only when a channel returns one.","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean","description":"Whether the same request/order may be retried."}}}},"responses":{"BadRequest":{"description":"Bad Request - the request body could not be read.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"Unauthorized":{"description":"Unauthorized - authentication failed (missing key, bad signature, etc.).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"InternalError":{"description":"Internal or business error. Note that most business failures are returned\nas HTTP `200` with `result: false` and a `code`; this `500` covers\nserver-side internal errors.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}}}},"paths":{"/api/v2/institution/wire/payout/order":{"get":{"tags":["Payout"],"summary":"Get a payout order","description":"Get a single payout order by `orderId` **or** `clientOrderId`. Requires the\n`userId`'s platform KYB to be `APPROVED`.\n","operationId":"institutionPayoutOrderGet","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"$ref":"#/components/parameters/UserIdQueryRequired"},{"name":"orderId","in":"query","required":false,"description":"Provide `orderId` or `clientOrderId`.","schema":{"type":"string"}},{"name":"clientOrderId","in":"query","required":false,"description":"Provide `orderId` or `clientOrderId`.","schema":{"type":"string"}},{"name":"channel","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PayoutOrder"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```