# How to create a single payout via API

## **Process description** <a href="#process-description" id="process-description"></a>

{% stepper %}
{% step %}
Check account balance and ensure enough funds for payouts are available by using the method - [**\[POST\] account**](https://docs.calypso.finance/api-reference/account-api)
{% endstep %}

{% step %}
You can pre-calculate commissions using a special feature - [**Commission pre-calculation**](https://docs.calypso.finance/payouts/commission-pre-calculation)
{% endstep %}

{% step %}
Create the payout by using the method - [**\[POST\] payout/create**](https://docs.calypso.finance/api-reference/payout-api#post-api-v1-payout-create)

* After creating a payout request, you will receive a webhook - PAYOUT\_CHANGE\_STATUS (state: CREATED)
  {% 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)
  {% 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**](https://docs.calypso.finance/api-reference/payout-api#post-api-v1-payout)

{% endstep %}
{% endstepper %}

### Sequence

Names of requests on the scheme indicate certain payout API methods.

<figure><img src="https://1242099714-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlF2vAHahCu7Gtgm1PkXe%2Fuploads%2FV3eCl7Sea4Z9F0UzXeXl%2Fimage.png?alt=media&#x26;token=2bf08fbc-134b-44e5-ba3b-c845a8c990a7" alt=""><figcaption></figcaption></figure>

### **Payout statuses**

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

<figure><img src="https://1242099714-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlF2vAHahCu7Gtgm1PkXe%2Fuploads%2FFYYWUcxVFKNAIq5wOghi%2F%D0%A1%D0%BD%D0%B8%D0%BC%D0%BE%D0%BA%20%D1%8D%D0%BA%D1%80%D0%B0%D0%BD%D0%B0%202025-10-29%20%D0%B2%2014.54.09.png?alt=media&#x26;token=813f06d3-5c39-4348-91b8-a45e1ea4b831" alt=""><figcaption></figcaption></figure>

| Status                | Description                                                                                                                                                                                                                                                 |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CREATED               | A payout is created.                                                                                                                                                                                                                                        |
| PENDING\_CONFIRMATION | A payout is created via UI and is awaiting confirmation from other process participants.                                                                                                                                                                    |
| CONFIRMED             | <p>• A payout is created via UI and confirmed by other process participants.<br>• A payout created via API is automatically created with this status.</p>                                                                                                   |
| CANCELED              | A payout has been canceled by merchant.                                                                                                                                                                                                                     |
| IN\_PROGRESS          | <p>• Transaction for a payout is created and is awaiting to be sent to the network.<br>•Transaction for a payout is sent to the network to be sent to a block and is awaiting confirmation from nodes.</p>                                                  |
| FAILED                | <p>An error occurred when sending funds. There can be many reasons of the error. You may follow these remediation steps:<br>1. Wait a while and create a new similar payout.<br>2. Contact our <a href="https://t.me/calypsosup">technical support</a>.</p> |
| COMPLETED             | Funds are successfully credited to destination wallet.                                                                                                                                                                                                      |

### **Request examples** <a href="#request-examples" id="request-examples"></a>

#### New Payout - [**\[POST\] payout/create**](https://docs.calypso.finance/api-reference/payout-api#post-api-v1-payout-create) <a href="#post-api-v1-payout-create" id="post-api-v1-payout-create"></a>

**Request:**

```
{
  "account": "text",
  "timestamp": 1,
  "payload": {
    "depositAddress": "text",
    "amount": 1,
    "currency": "text",
    "comment": "text",
    "executionDate": "2025-10-29T11:20:32.438Z",
    "idempotencyKey": "123e4567-e89b-12d3-a456-426614174000",
    "externalId": "text"
  }
}
```

\
**Response&#x20;**<mark style="color:$success;">**200 OK**</mark>**:**

```
{
  "id": "string",
  "account": "string",
  "depositAddress": "string",
  "amount": 0,
  "currency": "string",
  "fee": 0,
  "feePercentage": 0,
  "state": "CREATION_IN_PROGRESS",
  "createdDate": "2025-12-16T10:51:48.429Z",
  "transactionHash": "string",
  "comment": "string",
  "executionDate": "2025-12-16T10:51:48.429Z",
  "idempotencyKey": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "errors": {
    "withdrawalErrors": [
      {
        "withdrawalId": "string",
        "errors": [
          {
            "id": 0,
            "status": "SUCCESS",
            "errorResolved": true,
            "errorMessage": "string"
          }
        ]
      }
    ]
  },
  "cancellation": {
    "canceledByUserId": "string",
    "canceledByFirstname": "string",
    "canceledByLastname": "string",
    "cancelMessage": "string"
  },
  "belongingType": "INTERNAL",
  "externalId": "string"
}
```