Retrieve Mass Payout

Retrieve Mass Payout and Items Detail

post

https://api.iyzipay.comhttps://sandbox-api.iyzipay.com

/v1/mass/payout/retrieve

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.

Query parameters

localestring · enumRequired

Response language.

Possible values:

Header parameters

AuthorizationstringRequired

Authorization header; a signed hash value that starts with IYZWSv2 and is generated in Base64 format.

Example: IYZWSv2 aXBzaWduYXR1cmU...

Content-TypestringRequired

Content-Type value.

Example: application/json

Body

application/json

Retrieve mass payout and item details.

requestIdstringOptional

Correlation / tracking identifier for the mass payout.

Example: c95e344a-c7c9-4605-91b8-3f48ee9dece6

externalMassPayoutIdstringOptional

Unique id for the mass payout request (idempotency).

Example: massPayoutId-323

pageintegerRequired

Page number to retrieve.

Example: 0

sizeintegerRequired

Number of results per page.

Example: 40

Responses

200

Successful

application/json

post

/v1/mass/payout/retrieve

HTTPcURL

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
}

200

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

Status	Description
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

Status	Description
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.