How to create a single payout via API

General API integration rules

Before starting an integration please check our General API integration rules page for more info.

Get balance information via API

Before creating payouts you will probably want to check whether you have enough funds on your wallets or not. To do this please check our Get balance information via API page for more info.

Single payout API integration

Single Payout is a single payment of a reward, dividend, insurance compensation, etc. (i.e. you may need to pay dividends to partners).

To send single payment with fixed amount in cryptocurrency you can use single payout functionality. To make a payment you just need to know receiver address and specify amount and currency of payment.

You can find more information about other features of Public API integration in our documentation: Single Payout

Create single payout

To create a new single payout use the following endpoint: New Payout (POST <<baseUrl2>>/api/v1/payout/create)

You can find the detailed description of all the parameters in the documentation:

New Payout

Here we consider the most important ones.

  • depositAddress - address of the receiver of payment. Pay attention to specify address in the correct blockchain network.
  • amount - amount of the payment.
  • currency - the crypto currency of payment. Calypso supports the following currencies:
    • Bitcoin blockchain: BTC
    • Ethereum blockchain: ETH, USDT, FRAX, BUSD_ETH, USDC, DAI
    • Tron blockchain: TRX, USDT_TRX
    • Binance Smart Chain blockchain: BNB, BUSD
    • Polygon blockchain: MATIC, USDT_MATIC
    • Doge blockchain: XDG
  • comment - some information about payment.
  • idempotencyKey - a specific UUID for the payout which guarantees uniqueness of the request. It’s possible to check the status of the payout by this parameter after creation.

So to create payout without additional options you just have to send request:

curl --location --request POST '<<baseUrl2>>/api/v1/pub/payout/create' \
--header 'key: <your_api_key>' \
--header 'sign: <your_sign>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "timestamp": 13292792792,
  "account": "0xc195df92dd9db2a8f28e597981f113d6e7582f8b",
  "payload": {
    "depositAddress": "0xf127e5B7666F51aA346f374213113298014F5969",
    "amount": 10,
    "currency": "USDT",
    "comment": "payout for the client 1",
    "idempotencyKey": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}'

Some additional options:

  • You can set time of the payout processing by transmitting executionDate field in request body. The payout will be sent on specified date and time.

If the creation was successful you receive the response:

  • Response example 
    {
  "id": 1,
  "account": "0xc195df92dd9db2a8f28e597981f113d6e7582f8b",
  "depositAddress": "0xf127e5B7666F51aA346f374213113298014F5969",
  "amount": 10,
  "currency": "USDT",
  "calypsoFee": 1,
  "calypsoFeePercentage": 10,
  "state": "CONFIRMED",
  "createdDate": "2023-02-21T14:54:48.946Z",
  "transactionHash": "0x55d5eacb1051ff00847093f9a693dec957b87f8f3ce7bf2b45ae6a449c63e66b",
  "comment": "payout for the client 1",
  "idempotencyKey": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

After that you can track state changes until payout will be completed.

Tracking payout state

After creating payout you can receive information about it from the system. There are two options to track changes in payout state:

  1. Get payout data via request by ID.
  2. Set webhooks for payouts.

Get data about specific payout

To receive information about earlier created payout you can use Get Specific Payout endpoint (POST <<baseUrl2>>/api/v1/payout).

You can request payout by id or idempotencyKey.

More info on Get Specific Payout endpoint: Get specific Payout

Example of the request by id:

curl --silent --location --request POST "<<baseUrl2>>/api/v1/payout" \
--header 'Key: <your_api_key>' \
--header 'Sign: <your_sign>' \
--header "Content-Type: application/json" \
--data-raw "{
  "timestamp": 13292792792,
  "account": "0xc195df92dd9db2a8f28e597981f113d6e7582f8b",
  "payload": {
    "id": 13374
  }
}"

In response you will receive payout data:

  • Response example 
    {
  "id": 1,
  "account": "0xc195df92dd9db2a8f28e597981f113d6e7582f8b",
  "depositAddress": "0xf127e5B7666F51aA346f374213113298014F5969",
  "amount": 10,
  "currency": "USDT",
  "calypsoFee": 1,
  "calypsoFeePercentage": 10,
  "state": "CONFIRMED",
  "createdDate": "2023-02-21T14:54:48.946Z",
  "transactionHash": "0x55d5eacb1051ff00847093f9a693dec957b87f8f3ce7bf2b45ae6a449c63e66b",
  "comment": "payout for the client 1",
  "idempotencyKey": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

The most important fields you need to pay attention to:

  • state - represents status of the payout. More info about possible states in documentation: Single Payout
  • calypsoFee - service fee you paid for payout.

Receive information about payout state via Webhooks

To track state of your created Payout you can use Calypso Payment functionality which is called Webhooks.

Webhook is a way for an app to provide other applications with real-time information.
The Webhooks API allows you to subscribe to events happening with your created objects (Invoices or Payouts) in Calypso. Rather than making an API call to check status of invoice or payout during processing, Calypso can send an HTTP request to an endpoint you configure.

More detailed information about Calypso Webhooks functionality: Webhooks

  1. First of all, to receive information about Payout state change you need to create a subscription for system events which you want to track.

There are several types of events which you need to track in order to understand what is happening to your Invoices.

The main events are:

Event typeDescription
PAYOUT_CHANGE_STATUSPayout has changed state to In Progress, Canceled, Failed or Completed
PAYOUT_VALIDATION_ERRORValidation error has been occurred during payout processing

More info on Calypso Webhooks event types: Types of events

We’ll look at more scenarios of using Webhooks in following sections.

To create a subscription for those events you can use the Create Webhook Public API endpoint: POST <<baseUrl2>>/api/v1/subscription/webhook/create

curl --location --request POST '<<baseUrl2>>/api/v1/subscription/webhook/create' \
--header 'Key: <your_api_key>' \
--header 'Sign: <your_sign>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "timestamp": 13292792792,
  "account": "0xc195df92dd9db2a8f28e597981f113d6e7582f8b",
  "payload": {
    "notificationEventTypes": [
      "PAYOUT_CHANGE_STATUS",
			"PAYOUT_VALIDATION_ERROR"
    ],
    "requestId": "bf9348b7-2c14-46d7-868c-b597852da319",
    "url": "Your App URL"
  }
}'

You can subscribe to all types of events if you specify value “PAYOUT” in the notificationServiceTypes field instead of enumeration all types of events in notificationEventTypes.

In the response you will get:

{
    "requestId": "bf9348b7-2c14-46d7-868c-b597852da319",
    "notificationEventTypes": [
      "PAYOUT_CHANGE_STATUS",
			"PAYOUT_VALIDATION_ERROR"
    ],
    "url": "Your App URL",
    "createdDate": "2022-08-22T08:24:00.307535"
}

More info on Webhooks management in Calypso Pay system: Webhook API

  1. After successful creation of subscription for payout state changes you should wait while the payout is processing.

Successful Payout scenario

If payout was successfully processed you will receive webhook with type PAYOUT_CHANGE_STATUS where the field payoutStatus will be COMPLETED.

  • The example of webhook payload: 
    {
  "requestId": "bf9348b7-2c14-46d7-868c-b597852da319",
	"id":74146,
	"createdDate":"2022-10-10T11:54:52.191723",
	"level":"SUCCESS",
	"service":"PAYOUT",
	"data": {
			"hash":"0x3b4420311222002ec01631d2623d7a710494048402cd17e5c0338468d5ed3dae",
			"type":"PAYOUT_CHANGE_STATUS",
			"currency":"ETH",
			"createdDate":"2022-10-06T15:54:23.925926",
			"payoutStatus":"COMPLETED",
			"idempotencyKey":"e318f10d-d470-4605-898f-680be65a5380",
			"parentExternalId":13374
	}
}

To get detailed information about payout you can use Get Specific Payout endpoint (POST <<baseUrl2>>/api/v1/payout) using idempotencyKey or parentExternalId (id in request).

The value of the field state will be changed to COMPLETED.

Negative Payout scenario

If payout was finished due to the error you will receive webhook with type PAYOUT_CHANGE_STATUS where the field payoutStatus will be FAILED.

  • The example of webhook payload: 
    {
  "requestId": "bf9348b7-2c14-46d7-868c-b597852da319",
	"id":74146,
	"createdDate":"2022-10-10T11:54:52.191723",
	"level":"WARNING",
	"service":"PAYOUT",
	"data": {
			"hash":null,
			"type":"PAYOUT_CHANGE_STATUS",
			"currency":"ETH",
			"createdDate":"2022-10-06T15:54:23.925926",
			"payoutStatus":"FAILED",
			"idempotencyKey":"e318f10d-d470-4605-898f-680be65a5380",
			"parentExternalId":13374
	}
}

To get detailed information about payout you can use Get Specific Payout endpoint (POST <<baseUrl2>>/api/v1/pub/payout) using idempotencyKey or parentExternalId (id in request).

The value of the field state will be changed to FAILED.

This state means that the error occurred on the side of Calypso system. You should resend this payout or ask our technical support about the problem.

Updated 6 months ago