Retrieve Mass Payout
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.
Response language.
Authorization header; a signed hash value that starts with IYZWSv2 and is generated in Base64 format.
IYZWSv2 aXBzaWduYXR1cmU...
Content-Type value.
application/json
Retrieve mass payout and item details.
Correlation / tracking identifier for the mass payout.
c95e344a-c7c9-4605-91b8-3f48ee9dece6
Unique id for the mass payout request (idempotency).
massPayoutId-323
Page number to retrieve.
0
Number of results per page.
40
Successful
POST /v1/mass/payout/retrieve?locale=en HTTP/1.1
Host: api.iyzipay.com
Authorization: IYZWSv2 aXBzaWduYXR1cmU...
Content-Type: application/json
{
"requestId": "c95e344a-c7c9-4605-91b8-3f48ee9dece6",
"externalMassPayoutId": "massPayoutId-323",
"page": 0,
"size": 40
}
Successful
{
"status": "success",
"systemTime": 1759155442830,
"massPayout": {
"externalId": "massPayoutId-323",
"merchantId": 1,
"totalAmount": 201,
"totalSuccessfulAmount": 0,
"massPayoutStatus": "PUBLISHED_TO_QUEUE",
"totalCommissionAmount": 0,
"currency": "TRY"
},
"massPayoutItems": {
"items": [
{
"itemExternalId": "ext-0077",
"referenceCode": "a97b14a2-1e22-4ceb-bafb-38b61c4c4477",
"recipientType": "IBAN",
"recipientInfo": "TR920086402100005482986178",
"recipientName": "Jane Customer",
"description": "Payment for services",
"itemStatus": "INIT",
"errorMessages": [],
"totalAmount": 100.5,
"commissionAmount": 20,
"currencyCode": "TRY"
},
{
"itemExternalId": "ext-0099",
"referenceCode": "05b8f881-aaf7-4004-8f0a-21bbed27a816",
"recipientType": "IBAN",
"recipientInfo": "TR920086402100005482986178",
"recipientName": "Alice Example",
"description": "Payment for services",
"itemStatus": "INIT",
"errorMessages": [],
"totalAmount": 100.5,
"commissionAmount": 20,
"currencyCode": "TRY"
}
]
},
"page": 0,
"size": 40,
"total": 2
}
Mass Payout Status List
INIT
Mass payout request received but not yet authorized.
IN_PROGRESS
Request has been authorized and marked as in progress with a valid requestId.
PUBLISHED_TO_QUEUE
Request published to iyzico internal queue. At least one payment has been sent to the bank.
COMPLETED
All items related to the mass payout have been successfully processed.
FAIL
All items within the mass payout failed at the bank.
INSUFFICIENT_BALANCE
Insufficient merchant mass payout balance to execute the request.
CANCELED
Mass payout request has been canceled.
Mass Payout Item Status List
FAILED
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.
SUCCESS
Item was sent to the bank and completed successfully.
INIT
When the mass payout is created, items are stored in waiting state before auth
INVALID
Parameter(s) are invalid, missing, or inconsistent.
PROCESSING
Item has been sent to the bank and is being processed.
MASS_PAYOUT_CANCELED
Item was canceled because the parent mass payout was canceled.
QUEUED
Item has been queued (for both bank transfer and wallet/deposit flows)
DEPOSIT_SUCCESS
Failed item and its commission amount were successfully refunded to the merchant mass payout balance
DEPOSIT_FAIL
Failed payment amount and commission amount could not be refunded to the mass payout balance. An error was returned.
Last updated