# Mass Payout Integration

The **Mass Payout** service allows merchants to send payments to multiple recipients in a single transaction.\
This service is designed especially for marketplaces, freelance platforms, financial technology solutions, and systems where multiple payments are processed regularly.

With the **Mass Payout API**, you can make payments to several recipients in one request instead of initiating separate transactions for each payment.

### Pre-Integration Requirements

{% hint style="info" %}
Internal control and approval are required to use this feature.\
You can contact the iyzico Support Team to perform the necessary checks and activate the feature.
{% endhint %}

## Integration Steps

1. [Mass Payout Initialize](https://docs.iyzico.com/en/products/mass-payout/mass-payout-integration/mass-payout-initalize)
2. [Mass Payout Auth](https://docs.iyzico.com/en/products/mass-payout/mass-payout-integration/mass-payout-auth)
3. [Retrieve Mass Payout](https://docs.iyzico.com/en/products/mass-payout/mass-payout-integration/retrieve-mass-payout)

## Sample Case

### Initialize Mass Payout

#### Example Request

```json
{
    "externalId": "massPayoutId-323ddd",
    "conversationId": "conversationId-323f",
    "purpose" : "SALARY",
    "items": [
        {
            "itemExternalId": "ext-65656",
            "recipientType": "IBAN",
            "recipientInfo": "TR920086402100002353983528",
            "amount": {
                "value": 100,
                "currency": "TRY"
            },
            "description": "Payment for services",
            "recipientName": "John Doe"
        },
        {
            "itemExternalId": "ext-9545455",
            "recipientType": "MEMBER_ID",
            "recipientInfo": "2228853",
            "amount": {
                "value": 8000,
                "currency": "TRY"
            }
        },
        {
            "itemExternalId": "ext-545454542",
            "recipientType": "IDENTITY_NUMBER",
            "recipientInfo": "2222222817",
            "amount": {
                "value": 20000,
                "currency": "TRY"
            }
        },
         {
            "itemExternalId": "ext-50070945",
            "recipientType": "PHONE",
            "recipientInfo": "+905555856935",
            "amount": {
                "value": 7000,
                "currency": "TRY"
            }
        }

    ]
}
```

#### Example Response

```json
{
    "status": "success",
    "systemTime": 1759231970716,
    "conversationId": "conversationId-894",
    "requestId": "79cdefc1-3ce6-4f51-bdd9-0c050274db64"
}
```

### Auth Mass Payout

#### Example Request

```json
{
    "requestId" : "79cdefc1-3ce6-4f51-bdd9-0c050274db64"
}
```

#### Example Response

```json
{
    "status": "success",
    "systemTime": 1759231995145
}
```

### Retrieve Mass Payout

#### Example Request

```json
{
    "requestId": "c95e344a-c7c9-4605-91b8-3f48ee9dece6",
    "externalMassPayoutId": "massPayoutId-323",
    "page": 0,
    "size": 40
}
```

#### Example Response

```json
{
    "status": "success",
    "systemTime": 1759155442830,
    "massPayout": {
        "externalId": "massPayoutId-323",
        "merchantId": 000000,
        "totalAmount": 201.00,
        "totalSuccessfulAmount": 0,
        "massPayoutStatus": "PUBLISHED_TO_QUEUE",
        "totalCommissionAmount": 0,
        "currency": "TRY"
    },
    "massPayoutItems": {
        "items": [
            {
                "itemExternalId": "ext-0077",
                "referenceCode": "a97b142a-1e22-4ceb-bafb-38d6c1c4a4f7",
                "recipientType": "IBAN",
                "recipientInfo": "TR920086402100002353983528",
                "recipientName": "John Doe",
                "description": "Payment for services",
                "itemStatus": "INIT",
                "errorMessages": [],
                "totalAmount": 100.50,
                "commissionAmount": 20.00000000,
                "currencyCode": "TRY"
            },
            {
                "itemExternalId": "ext-0099",
                "referenceCode": "050b8f81-aaf7-400d-80fa-21bbed27a816",
                "recipientType": "IBAN",
                "recipientInfo": "TR920086402100002353983528",
                "recipientName": "John Doe",
                "description": "Payment for services",
                "itemStatus": "INIT",
                "errorMessages": [],
                "totalAmount": 100.50,
                "commissionAmount": 20.00000000,
                "currencyCode": "TRY"
            }
        ],
        "page": 0,
        "size": 40,
        "total": 2
    }
}
```