Mass Payout

What are Mass Payouts?

Mass Payout is a method of paying up to 10,000 recipients simultaneously. Since mass payouts are submitted online, they are processed instantly which helps organizations to save time, money and resources.

The Calypso Payout API is great for merchants needing to automate sending payments in real time. The company provides the ability to simultaneously make up to 10,000 payments.

Mass payouts are perfect for sending salaries to subordinates, payouts to partners or e-commerce marketplaces.

Before integrating, please review the limits for creating mass payouts - Limits

Process description

1

Check account balance and ensure enough funds for payouts are available by using the method - [POST] account

2

You can pre-calculate commissions using a special feature - Commission pre-calculation

3

Create the mass payouts by using the method - [POST] payout/mass/create

• After creating a payout request, you will receive a webhook - PAYOUT_CHANGE_STATUS (state: CREATION_IN_PROGRESS)

4

If you have payout verification enabled, you will receive a webhook - PAYOUT_CHANGE_STATUS (state: PENDING_CONFIRMATION)

• Once the payout is confirmed, you will receive a webhook - PAYOUT_CONFIRMED

• If your payout was declined, you will receive a webhook - PAYOUT_CHANGE_STATUS (state: CANCELED)

5

Once your payout request is processed, you will receive a webhook - PAYOUT_CHANGE_STATUS (state: IN_PROGRESS)

• If these payout are not validated before being created on the network, you will receive a webhook - PAYOUT_VALIDATION_ERROR

• If there are any issues with the payout and it is not processed, you will receive a webhook - PAYOUT_CHANGE_STATUS (state: FAILED)

• If one or more payouts from the entire list fail, you will receive a webhook - PAYOUT_CHANGE_STATUS (state: PARTIAL)

6

After a successful payment, you will receive a webhook - PAYOUT_CHANGE_STATUS (state: COMPLETED)

7

Get the data on the payout and its status by using the method - [POST] payout/mass

Sequence

Names of requests on the scheme indicate certain payment API methods

Mass payout statuses

Diagram nodes indicate mass payout statuses, arrows indicate processes a successful completion of which transfers a payout from one status to another

ENUM value	Description
CREATION_IN_PROGRESS	Payout started creation
PENDING_CONFIRMATION	A payout is created via UI and is awaiting confirmation from other process participants.
CONFIRMED	• A payout is created via UI and confirmed by other process participants. • A payout created via API is automatically created with this status.
CANCELED	A payout has been canceled by merchant.
IN_PROGRESS	• Transaction for a payout is created and is awaiting to be sent to the network. •Transaction for a payout is sent to the network to be sent to a block and is awaiting confirmation from nodes.
FAILED	An error occurred when sending funds. There can be many reasons of the error. You may follow these remediation steps: 1. Wait a while and create a new similar payout. 2. Contact our technical support.
PARTIAL	One or more transactions from the payout list were not completed successfully, you can get a list of unsuccessful transactions in your personal Calypso account. You can read about the process of resending these transactions via UI in the guide - How to resend unsuccessful mass payouts transaction via UI
COMPLETED	Funds are successfully credited to destination wallet.

Request examples

New Payout - [POST] payout/mass/create

Request:

{
  "account": "text",
  "timestamp": 1,
  "payload": {
    "currency": "text",
    "name": "text",
    "comment": "text",
    "massAddresses": [
      {
        "depositAddress": "text",
        "amount": 1,
        "comment": "text"
      }
    ],
    "executionDate": "2025-11-17T09:55:55.567Z",
    "idempotencyKey": "123e4567-e89b-12d3-a456-426614174000",
    "externalId": "text"
  }
}

Response:

{
  "id": "text",
  "idempotencyKey": "123e4567-e89b-12d3-a456-426614174000",
  "companyId": "123e4567-e89b-12d3-a456-426614174000",
  "account": "text",
  "state": "CREATION_IN_PROGRESS",
  "comment": "text",
  "name": "text",
  "currency": "text",
  "totalWithdrawalAmount": 1,
  "totalCalypsoFee": 1, - [deprecated]
  "totalFee": 1,
  "totalCalypsoFeePercentage": 1, - [deprecated]
  "totalFeePercentage": 1,
  "executionDate": "2025-11-17T09:55:55.567Z",
  "errors": {
    "withdrawalErrors": [
      {
        "withdrawalId": "text",
        "errors": [
          {
            "id": 1,
            "status": "SUCCESS",
            "errorResolved": true,
            "errorMessage": "text"
          }
        ]
      }
    ]
  }
}