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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.iyzico.com/en/products/mass-payout/mass-payout-integration/retrieve-mass-payout.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.