> For the complete documentation index, see [llms.txt](https://docs.calypso.money/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.calypso.money/payouts/how-to-create-a-mass-payout-via-api.md). # How to create a mass payout via API ### **Process description** {% stepper %} {% step %} Check account balance and ensure enough funds for payouts are available by using the method - [**\[POST\] account**](https://docs.calypso.money/api-reference/account-api) {% endstep %} {% step %} You can pre-calculate commissions using a special feature - [**Commission pre-calculation**](https://docs.calypso.money/payouts/commission-pre-calculation) {% endstep %} {% step %} Create the mass payouts by using the method - [**\[POST\] payout/mass/create**](https://docs.calypso.money/api-reference/payout-api#post-api-v1-payout-mass-create) * After creating a payout request, you will receive a webhook - PAYOUT\_CHANGE\_STATUS (state: CREATION\_IN\_PROGRESS) {% endstep %} {% step %} 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) {% endstep %} {% step %} 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) {% endstep %} {% step %} After a successful payment, you will receive a webhook - PAYOUT\_CHANGE\_STATUS (state: COMPLETED) {% endstep %} {% step %} Get the data on the payout and its status by using the method - [**\[POST\] payout/mass**](https://docs.calypso.money/api-reference/payout-api#post-api-v1-payout-mass) {% endstep %} {% endstepper %} ### 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**](https://docs.calypso.money/api-reference/payout-api#post-api-v1-payout-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": "string", "idempotencyKey": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "companyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "account": "string", "state": "CREATION_IN_PROGRESS", "comment": "string", "name": "string", "currency": "string", "totalWithdrawalAmount": 0, "totalFee": 0, "totalFeePercentage": 0, "executionDate": "2025-12-16T10:52:46.659Z", "errors": { "withdrawalErrors": [ { "withdrawalId": "string", "errors": [ { "id": 0, "status": "SUCCESS", "errorResolved": true, "errorMessage": "string" } ] } ] }, "externalId": "string" } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.calypso.money/payouts/how-to-create-a-mass-payout-via-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.