> For the complete documentation index, see [llms.txt](https://docs.iyzico.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.iyzico.com/en/products/mass-payout/mass-payout-integration/retrieve-mass-payout.md).

# Retrieve Mass Payout

## Retrieve Mass Payout and Items Detail

> Retrieves the details of a \*\*Mass Payout\*\* and its contained payout items.\
> You must provide \*\*either\*\* \`requestId\` \*\*or\*\* \`externalMassPayoutId\` (or both), along with pagination parameters.<br>

```json
{"openapi":"3.0.3","info":{"title":"Mass Payout API","version":"1.0.0"},"tags":[{"name":"Mass Payout","description":"Mass payout operations"}],"servers":[{"url":"https://api.iyzipay.com","description":"Production"},{"url":"https://sandbox-api.iyzipay.com","description":"Sandbox"}],"paths":{"/v1/mass/payout/retrieve":{"post":{"tags":["Mass Payout"],"summary":"Retrieve Mass Payout and Items Detail","description":"Retrieves the details of a **Mass Payout** and its contained payout items.\nYou must provide **either** `requestId` **or** `externalMassPayoutId` (or both), along with pagination parameters.\n","parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"$ref":"#/components/parameters/LocaleQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MassPayoutRetrieveRequest"}}}},"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MassPayoutRetrieveResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}},"LocaleQuery":{"name":"locale","in":"query","required":true,"description":"Response language.","schema":{"type":"string","enum":["tr","en"]}}},"schemas":{"MassPayoutRetrieveRequest":{"type":"object","description":"Retrieve mass payout and item details.","required":["page","size"],"anyOf":[{"required":["requestId"]},{"required":["externalMassPayoutId"]}],"properties":{"requestId":{"type":"string","description":"Correlation / tracking identifier for the mass payout."},"externalMassPayoutId":{"type":"string","description":"Unique id for the mass payout request (idempotency)."},"page":{"type":"integer","description":"Page number to retrieve."},"size":{"type":"integer","description":"Number of results per page."}}},"MassPayoutRetrieveResponse":{"type":"object","description":"Mass payout and items detail response.","properties":{"status":{"type":"string","enum":["success","failure"]},"systemTime":{"type":"integer","description":"System time (epoch ms)."},"locale":{"type":"string"},"massPayout":{"$ref":"#/components/schemas/MassPayoutSummary"},"massPayoutItems":{"$ref":"#/components/schemas/MassPayoutItemsPage"},"page":{"type":"integer"},"size":{"type":"integer"},"total":{"type":"integer"}}},"MassPayoutSummary":{"type":"object","description":"Summary information for a mass payout.","properties":{"externalId":{"type":"string"},"merchantId":{"type":"integer"},"totalAmount":{"type":"decimal"},"totalSuccessfulAmount":{"type":"decimal"},"massPayoutStatus":{"type":"string","description":"Mass payout lifecycle status (enum).","enum":["INIT","IN_PROGRESS","PUBLISHED_TO_QUEUE","COMPLETED","FAIL","INSUFFICIENT_BALANCE","CANCELED"]},"totalCommissionAmount":{"type":"decimal"},"currency":{"type":"string"}}},"MassPayoutItemsPage":{"type":"object","description":"Paged list of mass payout items.","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MassPayoutItemDetail"}}}},"MassPayoutItemDetail":{"type":"object","description":"Mass payout item detail.","properties":{"itemExternalId":{"type":"string"},"referenceCode":{"type":"string"},"recipientType":{"type":"string","enum":["PHONE","IBAN","IDENTITY_NUMBER","MEMBER_ID"]},"recipientInfo":{"type":"string"},"recipientName":{"type":"string"},"description":{"type":"string"},"itemStatus":{"type":"string","description":"Mass payout item lifecycle status (enum).","enum":["FAILED","SUCCESS","INIT","INVALID","PROCESSING","MASS_PAYOUT_CANCELED","QUEUED","DEPOSIT_SUCCESS","DEPOSIT_FAIL"]},"errorMessages":{"type":"array","items":{"type":"string"}},"totalAmount":{"type":"decimal"},"commissionAmount":{"type":"decimal"},"currencyCode":{"type":"string"}}}}}}
```

### Mass Payout Status List <a href="#masspayoutapidoc-masspayoutstatuslist" id="masspayoutapidoc-masspayoutstatuslist"></a>

<table data-full-width="true"><thead><tr><th>Status	</th><th>Description</th></tr></thead><tbody><tr><td>INIT</td><td>Mass payout request received but not yet authorized.</td></tr><tr><td>IN_PROGRESS</td><td>Request has been authorized and marked as in progress with a valid requestId.</td></tr><tr><td>PUBLISHED_TO_QUEUE </td><td>Request published to iyzico internal queue. At least one payment has been sent to the bank.</td></tr><tr><td>COMPLETED</td><td>All items related to the mass payout have been successfully processed.</td></tr><tr><td>FAIL</td><td>All items within the mass payout failed at the bank.</td></tr><tr><td>INSUFFICIENT_BALANCE</td><td>Insufficient merchant mass payout balance to execute the request.</td></tr><tr><td>CANCELED </td><td>Mass payout request has been canceled.</td></tr></tbody></table>

### Mass Payout Item Status List

<table data-full-width="true"><thead><tr><th>Status</th><th>Description</th></tr></thead><tbody><tr><td>FAILED</td><td>Item was sent to the bank but failed. Includes errors returned from the bank or general processing errors. Validation errors will also result in this status.</td></tr><tr><td>SUCCESS</td><td>Item was sent to the bank and completed successfully.</td></tr><tr><td>INIT</td><td>When the mass payout is created, items are stored in waiting state before auth</td></tr><tr><td>INVALID</td><td>Parameter(s) are invalid, missing, or inconsistent.</td></tr><tr><td>PROCESSING</td><td>Item has been sent to the bank and is being processed.</td></tr><tr><td>MASS_PAYOUT_CANCELED</td><td>Item was canceled because the parent mass payout was canceled.</td></tr><tr><td>QUEUED</td><td>Item has been queued (for both bank transfer and wallet/deposit flows)</td></tr><tr><td>DEPOSIT_SUCCESS</td><td>Failed item and its commission amount were successfully refunded to the merchant mass payout balance</td></tr><tr><td>DEPOSIT_FAIL</td><td>Failed payment amount and commission amount could not be refunded to the mass payout balance. An error was returned.</td></tr></tbody></table>