Retrieve Mass Payout

Retrieve Mass Payout and Items Detail

post

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

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

Last updated