Withdrawals Webhooks

This page provides information on the context object of payment intent webhooks.
Find out how to set a webhook, basic structure of the callbacks, and more here.

Both withdrawal.created and withdrawal.completed events have the same context structure. In the following table, an explanation for the Withdrawal context property is provided:

Property	Type	Description
id	string	Unique identifier of the particular Withdrawal.
merchant	object	Contains the information about the merchant ID.
id	string	The Merchant ID in Coinify's system.
subaccount	object / null	The ID of the sub-account involved in the Withdrawal. Is equal to null if no subaccount was provided.
id	string	The unique identifier of the subaccount.
orderId	string	Merchant's internal ID of the order.
state	string	The current state of the Withdrawal. Can be created or completed.
amounts	object	Contains the information about the base FIAT amount used to create a withdrawal and the final cryptocurrency amount that will be sent out.
baseAmount	string	The FIAT amount used for creating the withdrawal.
baseCurrency	string	The FIAT currency of the base amount. Three-letter ISO currency code.
finalAmount	string	The cryptocurrency amount that is sent to the withdrawal address.
finalCurrency	string	The cryptocurrency that the withdrawal will be executed in. Shown as a cryptocurrency ticker.
destination	object	Contains the information of the receiving cryptocurrency address.
tag	string / null	The addressTag specified in the Create Withdrawal request. Also called memo, depending on the cryptocurrency.
address	string	The address to which the finalAmount is sent.
transactionId	string / null	The ID of the cryptocurrency transaction on the blockchain. Only visible after the withdrawal is sent out and is in the completed state.
context	object / null	The context provided upon creating the withdrawal. Check Create Withdrawal for more info.
memo	string / null	The optional text provided at the moment of creating the withdrawal.

Please find the available Withdrawal webhook events and their payload examples in the following text.

withdrawal.created

Event name: withdrawal.created

This event is sent once the Withdrawal is created.

withdrawal.created

{
  "id": "b03c1269-fb84-454c-8d3a-8bf0251d5910",
  "time": "2023-03-17T09:19:31.916Z",
  "event": "withdrawal.created",
  "context": {
    "id": "ef9f5df9-3669-4a3e-a298-783623bdfa9a",
    "merchant": {
      "id": "d560b17e-bae5-4fbf-8822-518273498c7a"
    },
    "subaccount": null,
    "orderId": "12345671234567",
    "state": "created",
    "amounts": {
      "baseAmount": "30",
      "baseCurrency": "USD",
      "finalAmount": null,
      "finalCurrency": "USDC"
    },
    "destination": {
      "tag": null,
      "address": "0x8c58D12ce7219B6F53B1803d00b7021CB8e9A4c6"
    },
    "transactionId": null,
    "context": {"purpose":"settlement"},
    "memo": "Re-ocurring withdrawal"
  }
}

withdrawal.completed

Event name: withdrawal.completed

This event is sent once the requested Withdrawal cryptocurrency has been sent to the designated address.

withdrawal.completed

{
  "id": "dfc1f3ec-cd6a-4a6a-afb6-2f38a4661dd4",
  "time": "2023-03-17T09:21:01.029Z",
  "event": "withdrawal.completed",
  "context": {
    "id": "ef9f5df9-3669-4a3e-a298-783623bdfa9a",
    "merchant": {
      "id": "d560b17e-bae5-4fbf-8822-518273498c7a"
    },
    "subaccount": null,
    "orderId": "12345671234567",
    "state": "completed",
    "amounts": {
      "baseAmount": "30",
      "baseCurrency": "USD",
      "finalAmount": "29.7",
      "finalCurrency": "USDC"
    },
    "destination": {
      "tag": null,
      "address": "0x8c58D12ce7219B6F53B1803d00b7021CB8e9A4c6"
    },
    "transactionId": "0xdc7ca76fc3b59c6462323811b36dc3fbaee350e0984482e842657ea28da3d4dc",
    "context": {"purpose":"settlement"},
    "memo": "Re-ocurring withdrawal"
  }
}

withdrawal.cancelled

Event name: withdrawal.cancelled

In very rare cases Coinify may need to intervene into the otherwise fully automated Withdrawal process. As a result, the Withdrawal may end up in the cancelled state. When that happens our system will send out the following webhook:

withdrawal.cancelled

{
  "id": "1e43e74b-4244-43a1-8951-c07b86bca218",
  "time": "2024-01-30T13:00:59.286Z",
  "event": "withdrawal.cancelled",
  "context": {
    "id": "2ee7d806-b075-4899-ad4e-659360f45068",
    "merchant": {
      "id": "d560b17e-bae5-4fbf-8822-518273498c7a"
    },
    "subaccount": null,
    "orderId": "d7bff15b-a109-43d5-a2ea-cacde1909643",
    "state": "cancelled",
    "amounts": {
      "baseAmount": "30",
      "baseCurrency": "USD",
      "finalAmount": "29.54444526",
      "finalCurrency": "USDC"
    },
    "destination": {
      "tag": null,
      "address": "0x965933D5C73ef443f3a2E4B370c3b6C964fc76eC"
    },
    "transactionId": null,
    "context": null,
    "memo": null
  }
}

There are a couple of reasons a withdrawal might be cancelled, like for example if a receiving blockchain address triggers Coinify's risk engine. For further clarification on why a withdrawal was cancelled feel free to contact our API support.