Create a Coin Withdrawal

In order to create a coin withdrawal, it is necessary to know the following payment details:

  • Payment amount, for example 100

  • Payment currency, for example, USD

  • Cryptocurrency type in which the payment is to be made, for example, BTC

  • Destination address, for example, 2MvWu1QjMuDWP4x3wZpPxhuVHpvfzBJmyw3

Thus, our API request for a Coin Withdrawal will look like this:

curl -X POST \
https://business-sandbox.cryptopay.me/api/coin_withdrawals \
-H 'Authorization: HMAC ***' \
-H 'Content-Type: application/json' \
-H 'Date: Tue, 19 Mar 2019 10:11:40 GMT' \
-d '{"charged_currency":" USD", "charged_amount_to_send":"100", "address":"2MvWu1QjMuDWP4x3wZpPxhuVHpvfzBJmyw3", "received_currency":"BTC", “custom_id”:”113562013”}'

Let’s go through the parameters that we used in the request above:

  • charged_amount_to_send - the payment amount

  • charged_currency - the currency of payment

  • address - the recipient's wallet address

  • custom_id - we recommend you specify a certain reference by which you associate your customer with the payment, for example 113562013

In the example above, we used the charged_amount_to_send parameter to specify the amount of payment. However, if you look at the endpoint description, you will see that the charged_amount parameter can also be used instead of charged_amount_to_send to specify the payment amount. So what is the difference? The fact is that it will depend on whether the Cryptopay fee and miner fee will be included in the payment amount or whether it will be charged from the merchant balance above it:

  • сharged_amount_to_send - from the example above, when using this parameter, Cryptopay will deduct the entire fee from the merchant balance and not the transaction amount. In this way, the BTC transaction with the amount of 100 USD will be sent to the recipient's address at the rate at the time of processing the payment request.

  • charged_amount - in this case, if we had used this parameter to specify the amount of payment, Cryptopay would have included the amount of all payments in the amount of the transaction sent. Thus, the BTC transaction with an amount less than 100 USD at the exchange rate at the time of the payment request would have been sent to the recipient's address.

We have just sent a Coin Withdrawal request and received the following response from the API:

{
"id": "f04d3cac-837a-4245-840d-1b525a4d693d",
"custom_id": "113562013",
"address": "2MyYeAkU162aMh3otEhYHP9yhUR7xqS7S1r",
"txid": null,
"status": "pending",
"charged_amount": "10.17",
"charged_currency": "EUR",
"received_amount": "0.00103102",
"received_currency": "BTC",
"network_fee": "0.0000054",
"network_fee_level": "average",
"fee": "0.0",
"fee_currency": "BTC",
"exchange": {
"pair": "BTCEUR",
"rate": "9699.0409",
"fee": "0.11",
"fee_currency": "EUR"
},
"risk": null,
"created_at": "2019-05-02T12:08:46Z"
}

The coin withdrawal was created with the initial status “Pending”.

The “Completed” status means that Cryptopay has processed your request and sent the transaction has been sent to the network. This status does not mean that the transaction has shown up on the recipient's wallet balance, since, as explained above, it will take some time for the transaction to be confirmed by the miners.

Sometimes when the transaction status is updated to “Failed” instead of “Completed”, it means that Cryptopay was unable to send the transaction. In this case, the funds charged from the merchant's account will be refunded to the balance. It usually takes from minutes to several hours to return the funds and does not require any action by the merchant.

Once you have created a Coin withdrawal, we recommend that you check the payment status with a separate request, as the delivery of the callbacks is not guaranteed.

To enable the sending of callbacks to your Callback URL, go to the Settings > API page in your account and put the toggle switch "I want to receive callbacks for coin withdrawal transactions" in the active position as in the image below: