➕Create a withdrawal

Creates a new withdrawal request.

This method requires authorization We're using different API keys for authorizing Invoicing & withdrawal requests.

Make sure you use correct one.

POST https://api.silus.io/v1/withdrawals

Request body

Name	Type	Definition
amount	string numeric required_without:fiat_amount	Amount to be paid in crypto currency. If there are pennies in the amount, then send them with a separator '.' Example: 10.28 You can omit this parameter and send fiat amount using parameters below
fiat_currency	string required_with:fiat_amount	Fiat currency ISO 4217 code. List of supported fiat currencies
fiat_amount	string numeric required_without:amount	Amount to be paid in fiat currency. If there are pennies in the amount, then send them with a separator '.' Example: 10.28 You can omit this parameter and send crypto amount using amount parameter. When provided, we will automatically convert it to the target crypto currency based on our exchange rates.
order_id*	string min: 1 max: 255 alpha_dash	Order identifier from your system. We will send this ID in every webhook request. ⚠️ The order_id must be unique within the merchant withdrawals. When we find an existing withdrawal request with order_id, we return its details, a new withdrawal request will not be created.
network*	string	Currency identifier in our system
currency*	string	Network identifier in our system
address*	string	The address of the wallet to which the withdrawal will be made
is_subtract*	boolean	Defines where the withdrawal fee will be deducted true - from your balance false - from payout amount, the payout amount will be decreased
additional_data	nullable array|object max: 255 KB	You can send any additional data with this request, it will be returned to you with the webhook. user_id field is reserved and value from this field will be displayed in the backoffice.
sign*	string	Request signature. Generation example is provided below

* - mandatory parameter

Request example

curl https://api.silus.io/v1/withdrawals
\-X POST
\-H 'Authorization: Bearer superSecretPrivateKey'
\-H 'Content-Type: application/json'
\-d '{
     "amount": "0.05",
     "order_id": "1",
     "network": "BTC",
     "currency": "BTC",
     "address": "bc1qa7pumxw8rf7srg74adtks0ramsfv6c3vjvefrm",
     "is_subtract": false,
     "sign": "1fb726bed664e5115840b6af666f8bdc6ef87cc214ca112b052452019de8d442"
}'

Response

Successful response

{
    "id": "9c3288f5-3aef-464d-a3fd-57c170163eab",
    "network": "BTC",
    "currency": "BTC",
    "address": "bc1qa7pumxw8rf7srg74adtks0ramsfv6c3vjvefrm",
    "amount": 0.05,
    "status": "pending",
    "order_id": "1",
    "additional_data": null,
    "created_at": 1717434398,
    "updated_at": 1717434398
}

Parameter	Description
id*	Withdrawal id. Can be used to check it's status
amount*	Withdrawal amount in crypto currency
currency*	Currency identifier in our system
network*	Network identifier in our system
address*	Crypto wallet address where coins should be sent to
status*	Withdrawal status
additional_data*	Any data provided during Withdrawal creation request. It will be null if you didn't specify it during invoice creation request.
created_at*	Unix time for withdrawal creation date
update_at*	Unix time for withdrawal last update date

* - mandatory parameter

Possible errors

401 Unauthorized

In case of providing invalid API credentials, you will receive response in the following format:

{
  "error": "unauthorized"
}

422 Validation failed

In case of validation error, you will get response in the following format:

{
  "message": "Human friendly error description.",
  
  // This object can have multiple case in case of multiple invalid fields
  // In actual response {fieldName} will be replace with actual field name
  // for example, "network".
  "errors": {
    "{fieldName}": [
      "Human friendly error description about specific field."
    ]
  }
}

422 Insufficient funds

In case of insufficient funds, you will get response in the following format:

{
  "error": "insufficient_funds"
}

422 Invalid sign

In case of invalid signature, you will get response in the following format:

{
  "error": "invalid_sign"
}

Sign generation

Each request should be signed with a signature. The concept of signature generation is similar to the one used for verifying webhooks. To ensure that the signature in the request is valid, you must encode the entire webhook payload to JSON (except for the "sign" value). The entire result should be converted to SHA256 using HMAC with a secret key (the one you use to authenticate requests to the Silus Invoice API).

Why are we using the Invoice API key for sign generation?

To provide better security, we're using it as a second protection layer. In case the Withdrawals Key is compromised, it will still be impossible to take any harmful action.

There is a difference when encoding data in PHP compared to other languages. PHP escapes slashes, unlike some other languages. Therefore, you may encounter sign a mismatch.

You have to escape slashes with a backslash to make it work properly.

Example on PHP

<?php

// Pay attention! We're using Invoice API key here, not Withdrawals one.
$secretKey = 'uZfQ0GYNurpCjU5iaB9JSOSrBsNTSPGZAnhNRkMO1MNsq2Qep70cyOiLD5jVDiky';

$payload = [
   'amount' => '0.05',
   'order_id' => '1',
   'network' => 'BTC',
   'currency' => 'BTC',
   'address' => 'bc1qa7pumxw8rf7srg74adtks0ramsfv6c3vjvefrm',
   'is_subtract' => false,
];

$signData = json_encode($payload, JSON_UNESCAPED_UNICODE);

$payload['sign'] = hash_hmac('sha256', $signData, $secretKey);

print_r($payload); // expected body object for request.