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:
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": "b5d7778c-6cf2-43fa-86eb-c5efbb89cb0a", "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:
- Get payout data via request by ID.
- 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": "b5d7778c-6cf2-43fa-86eb-c5efbb89cb0a"
}
}"
In response you will receive payout data:
- Response example
{ "id": "b5d7778c-6cf2-43fa-86eb-c5efbb89cb0a", "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 PayoutcalypsoFee
- 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
- 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 type | Description |
---|---|
PAYOUT_CHANGE_STATUS | Payout has changed state to In Progress, Canceled, Failed or Completed |
PAYOUT_VALIDATION_ERROR | Validation 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
- 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":"b5d7778c-6cf2-43fa-86eb-c5efbb89cb0a" } }
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":"b5d7778c-6cf2-43fa-86eb-c5efbb89cb0a" } }
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