How to create a single payout via API

Overview

Single payout API allows you to create one crypto payout from a merchant account to a recipient wallet address.

Use this guide to create a payout, track its processing status, and receive webhook notifications until the payout reaches a final status.

Integration flow

1. Check account balance and ensure enough funds for the payout are available by using the method - [POST] account
2. Optionally pre-calculate payout commissions using Commission pre-calculation
3. Create the payout by using the method - [POST] payout/create
   • After creating a payout request, Calypso sends PAYOUT_CHANGE_STATUS with state CREATION_IN_PROGRESS.
4. If payout verification is enabled, Calypso sends PAYOUT_CHANGE_STATUS (state: PENDING_CONFIRMATION)
   • Once the payout is confirmed, Calypso sends PAYOUT_CONFIRMED.
   • If the payout is declined, Calypso sends PAYOUT_CHANGE_STATUS with state CANCELED.
5. Once the payout is processed, Calypso sends PAYOUT_CHANGE_STATUS (state: IN_PROGRESS)
   • If the payout is not validated before being created on the network, Calypso sends PAYOUT_VALIDATION_ERROR.
   • If the payout cannot be processed, Calypso sends PAYOUT_CHANGE_STATUS with state FAILED.
6. Optional: when the payout receives a blockchain transaction hash, Calypso sends PAYOUT_HASH_RECEIVED.
7. After a successful payout, Calypso sends PAYOUT_CHANGE_STATUS with state COMPLETED.
8. Get payout details and current status by using the method - [POST] payout

Sequence

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

API methods

Create new payout - [POST] payout/create

Request fields

Field	Type	Required	Description
account	string	Yes	Merchant account ID. The request will be sent for this account.
timestamp	number	Yes	Current Unix UTC timestamp in milliseconds. The value must not be less than 3 minutes in the past or greater than 3 minutes in the future.
payload	object	Yes	Object with payout creation data.

Payload fields

Field	Type	Required	Description
depositAddress	string	Yes	Recipient's crypto address.
amount	number	Yes	Withdrawal amount.
currency	string	Yes	Currency associated with the payout amount.
comment	string	No	Comment for the payout. Maximum length: 1000 characters.
executionDate	string	No	Execution date of the payout in date-time format. Can be used to schedule a payout for a specific date.
idempotencyKey	string	No	External ID in UUID format. Can be generated by the merchant while creating the payout to prevent duplicate requests.
externalId	string	No	Merchant-side external ID for the payout. Maximum length: 255 characters.

Request example

{
  "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 fields

Field	Type	Description
id	string	Calypso payout ID.
account	string	Merchant account ID.
depositAddress	string	Recipient's crypto address.
amount	number	Withdrawal amount.
currency	string	Currency associated with the payout amount.
fee	number	Service fee for the payout.
feePercentage	number	Service fee in percentage.
state	string	Current payout status.
createdDate	string	Date and time when the payout was created.
transactionHash	string	Blockchain transaction hash, if it has already been received.
comment	string	Comment for the payout, if provided.
executionDate	string	Execution date of the payout, if provided.
idempotencyKey	string	External ID in UUID format provided during payout creation.
errors	object	Validation errors grouped by withdrawal, if any errors occurred.
cancellation	object	Cancellation details, if the payout was canceled.
belongingType	string	Payout belonging type: INTERNAL or EXTERNAL.
externalId	string	Merchant-side external ID for the payout, if provided.

Response example 200 OK

{
  "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"
}

Status lifecycle

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

Status	Description
CREATION_IN_PROGRESS	Payout creation has started.
PENDING_CONFIRMATION	A payout is awaiting confirmation from other process participants.
CONFIRMED	A payout has been confirmed by all required process participants and is ready for processing.
CANCELED	A payout has been canceled by merchant.
IN_PROGRESS	• Transaction for a payout has been created and is waiting to be sent to the network. • Transaction for a payout has been sent to the network 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.
COMPLETED	Funds are successfully credited to destination wallet.

Webhooks

Webhook event	Trigger	Merchant action
PAYOUT_CHANGE_STATUS	Payout status changed to CREATION_IN_PROGRESS, PENDING_CONFIRMATION, IN_PROGRESS, FAILED, CANCELED, or COMPLETED.	Update payout status in your system and request payout details if needed.
PAYOUT_CONFIRMED	Payout was confirmed by all required process participants.	Continue tracking payout status.
PAYOUT_HASH_RECEIVED	Blockchain transaction hash was received for the payout.	Save the transaction hash and use it for blockchain tracking, if needed.
PAYOUT_VALIDATION_ERROR	Payout validation failed before the transaction was created on the network.	Check validation errors and create a new payout with corrected data, if needed.

After receiving a status change webhook, we recommend checking the reliability of the payout information via a request - [POST] payout

Errors and edge cases

Case	Description
Not enough funds	Check the account balance before creating a payout.
Payout verification is enabled	The payout may wait for confirmation before processing starts.
Validation error	The payout was not validated before being created on the network. Check the validation error details.
Processing failed	The payout was not completed. You can create a new payout with corrected data or contact technical support.

Related docs

Document	Link
Account API	[POST] account
Commission pre-calculation	Commission pre-calculation
Payout API reference	Payout API
Payout webhooks	Payout webhooks