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, EUR

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

• Destination address, for example, 2MvWu1QjMuDWP4x3wZpPxhuVHpvfzBJmyw3

XRP and XLM addresses may require additional parameters specified:

• Destination tag for XRP

• Memo ID for XLM

Destination tag and Memo ID are similar to a reference number for bank transfers. They help to identify transactions when a single address is used by multiple users.

Destination tag can’t be left blank. Put “0” if the recipient has a unique XRP address. IMPORTANT: If you put “0“ as a destination tag for a wallet used by multiple users, your funds will be lost PERMANENTLY.

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":"EUR", "charged_amount_to_send":"100", "address":"2MyYeAkU162aMh3otEhYHP9yhUR7xqS7S1r", "received_currency":"BTC", "network": "bitcoin", "custom_id":"113562013", "force_commit":"false"}' 

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

XRP and XLM addresses require additional parameters specified by adding destination tag or memo ID to address like this: address?dt=destination_tag

• network - the blockchain in which the withdrawal is going to be created. The list of available networks can be found here.

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

• force_commit - the setting to set up the two-step withdrawal process. If false the coin withdrawal transaction needs to be committed within 30 seconds. Is false if omitted.

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 EUR 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 fees in the amount of the transaction sent. Thus, the BTC transaction with an amount of less than 100 EUR 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 100 EUR Coin Withdrawal request and received the following response from the API.

In case we used charged_amount:

{
  "data": {
    "id": "945965c5-737f-4716-a55d-0392129843f5",
    "custom_id": "113562013",
    "customer_id": null,
    "address": "2MyYeAkU162aMh3otEhYHP9yhUR7xqS7S1r",
    "network": "bitcoin",
    "txid": null,
    "status": "pending",
    "charged_amount": "100.0",
    "charged_currency": "EUR",
    "received_amount": "0.00318659",
    "received_currency": "BTC",
    "network_fee": "0.0000054",
    "network_fee_level": "average",
    "fee": "0.0",
    "fee_currency": "BTC",
    "exchange": {
      "pair": "BTCEUR",
      "rate": "31015.045",
      "fee": "1.0",
      "fee_currency": "EUR"
    },
    "risk": null,
    "created_at": "2019-05-02T12:08:46Z"
  }
}

In case we used charged_amount_to_send:

{
  "data": {
    "id": "c7969faa-a080-4c4d-aeaf-d631b687cc5f",
    "custom_id": "113562013",
    "customer_id": null,
    "address": "2MyYeAkU162aMh3otEhYHP9yhUR7xqS7S1r",
    "network": "bitcoin",
    "txid": null,
    "status": "pending",
    "charged_amount": "101.19",
    "charged_currency": "EUR",
    "received_amount": "0.00324701",
    "received_currency": "BTC",
    "network_fee": "0.0000054",
    "network_fee_level": "average",
    "fee": "0.0",
    "fee_currency": "BTC",
    "exchange": {
      "pair": "BTCEUR",
      "rate": "30797.564",
      "fee": "1.02",
      "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: