Create a Coin Withdrawal Using Cryptopay API

·

Managing cryptocurrency withdrawals efficiently is essential for businesses operating in the digital asset space. The Cryptopay API offers a robust solution for creating coin withdrawals with precision and control. This guide walks you through the entire process—step by step—covering required parameters, key differences between payment amount options, and how to interpret API responses effectively.

Whether you're integrating automated payouts or enabling crypto disbursements, understanding the nuances of the coin_withdrawals.create endpoint ensures accurate, secure transactions.

Required Payment Details for a Coin Withdrawal

To successfully initiate a coin withdrawal via the Cryptopay API, you must provide several critical pieces of information:

For certain cryptocurrencies like XRP and XLM, additional identifiers are required due to shared wallet infrastructure:

These function similarly to reference numbers in traditional banking, ensuring funds reach the correct recipient when multiple users share a single deposit address.

⚠️ Important: A destination tag cannot be left blank. If the recipient has a unique XRP address, use "0" as the value. However, never set the destination tag to "0" for shared addresses, as doing so will result in permanent loss of funds.

👉 Learn how to securely manage crypto withdrawals with advanced tools

Sample API Request: Creating a Coin Withdrawal

Below is an example curl command that sends a POST request to create a BTC withdrawal of 100 EUR:

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 break down the core parameters:

For XRP or XLM withdrawals, append the destination tag or memo ID directly to the address:

address?dt=123456789

Understanding charged_amount vs charged_amount_to_send

One of the most important distinctions in the Cryptopay API is between two similar yet functionally different parameters: charged_amount and charged_amount_to_send.

Using charged_amount_to_send

When this parameter is used:

This ensures predictable payout amounts, ideal for payroll, refunds, or fixed disbursements.

Using charged_amount

When this parameter is used:

👉 Discover secure platforms that simplify crypto transactions

Example API Responses

Case 1: Using charged_amount

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

In this case, the user receives less than 100 EUR worth of BTC because fees are included in the charged amount.

Case 2: Using charged_amount_to_send

{
  "data": {
    "id": "c7969faa-a080-4c4d-aeaf-d631b687cc5f",
    "custom_id": "113562013",
    "address": "2MyYeAkU162aMh3otEhYHP9yhUR7xqS7S1r",
    "network": "bitcoin",
    "status": "pending",
    "charged_amount": "101.19",
    "charged_currency": "EUR",
    "received_amount": "0.00324701",
    "received_currency": "BTC",
    "network_fee": "0.0000054",
    "exchange": {
      "pair": "BTCEUR",
      "rate": "30797.564",
      "fee": "1.02",
      "fee_currency": "EUR"
    },
    "created_at": "2019-05-02T12:08:46Z"
  }
}

Here, the recipient gets exactly 100 EUR equivalent in BTC; additional fees are pulled from your balance.

Monitoring Withdrawal Status

After creating a withdrawal, its initial status will be "pending".

Possible Statuses:

Since webhook callbacks aren’t guaranteed, always verify status using the retrieve withdrawal endpoint.

Frequently Asked Questions

What happens if I don’t include a destination tag for XRP?

You must include a destination tag. Omitting it may lead to irreversible loss of funds. Use "0" only if the recipient uses a dedicated XRP address.

Can I change the network after initiating a withdrawal?

No. The network parameter is final upon request. Ensure accuracy before submission.

Why do I see two different exchange rates in responses?

Exchange rates fluctuate between requests. Each transaction locks in the rate at processing time.

How long does it take for a withdrawal to complete?

Processing time is near-instant, but blockchain confirmation depends on network congestion—ranging from seconds (XLM) to minutes (BTC).

Is there a way to cancel a pending withdrawal?

Only if force_commit is enabled and not yet confirmed. Otherwise, once processed, it cannot be canceled.

Should I rely solely on webhooks to track transactions?

No. Always use the retrieval API to confirm status, as webhooks may fail or be delayed.

Core Keywords

coin withdrawal API, Cryptopay API, crypto payout integration, BTC withdrawal, XRP destination tag, XLM memo ID, charged_amount vs charged_amount_to_send, blockchain transaction fees

👉 Explore reliable platforms for executing seamless crypto withdrawals