🚧
Important:
We do not consider adding a new property to the Withdrawals payload as a breaking change to the API. Please build your integration to allow for new properties to be added to this and other resources.

The withdrawal resource is a JSON object. When calling the Withdrawals API endpoints, you get the following response:

{
    "id": "0aa5224a-6881-4c82-8959-31bee75f3190",
    "merchant": {
        "id": "d560b17e-bae5-4fbf-8822-518273498c7a",
        "name": "Demo payment merchant"
    },
    "subaccount": {
        "id": "fcfc4042-6051-4e24-b321-fcdbb402e94d",
        "name": "FlowerShop"
    },
    "orderId": "abcd_1234",
    "state": "created",
    "amounts": {
        "baseAmount": "30",
        "baseCurrency": "USD",
        "finalAmount": "29.7",
        "finalCurrency": "USDC"
    },
    "destination": {
        "address": "0x8c58D12ce7219B6F53B1803d00b7021CB8e9A4c6",
        "tag": null
    },
		"transactionId": null,
    "context": null,
    "memo": null,
    "customerId": "6af46318-9e60-4390-8bf0-e042d7b96b21",
  	"customerEmail": "customeri@email.com"
}

Please find the descriptions of the Withdrawals resource properties below:

id

The ID of the specific Withdrawal.

merchant

A Withdrawal instance is created from a Merchant for their Customer.
Merchant data are captured within the merchant JSON object.

Property	Type	Description
id	string	The Merchant ID in Coinify's system.
name	string	The Merchant name as set in Coinify's system

For example:

{
	"id": "d560b17e-bae5-4fbf-8822-518273498c7a",
	"name": "Demo payment merchant"
}

subaccount

The subaccount object tells you which specific merchant sub-account created the Withdrawal. If no subaccountId is provided when creating the PaymentIntent, the value of the object will equal to null. You can find the properties of the object in the following table:

Property	Type	Description
id	string	Unique identifier of a sub-account.
name	string	Name given when creating the sub-account.

orderId

The ID of an order from the merchant system. Must be unique for each new Withdrawal request.

state

Shows the state of the withdrawal. Each state has the value created upon withdrawal creation. Once the transaction to the designated address has been initiated, the value changes to completed.

state	Description
created	Withdrawal has been created and is waiting for the withdrawal transaction to be initiated on the blockchain.
completed	The blockchain transaction related to the withdrawal request has been initiated.
cancelled	The withdrawal has been cancelled by Coinify's system. For clarification on the specific cancellation reason, feel free to contact Coinify API support.

amounts

The amounts object provides you with the information on which currency was used for creating the Withdrawal request and how much of the specific currency was requested.
Furthermore, it shows you which cryptocurrency was the requested FIAT currency converted into.

You can find the properties of the amounts object described in continuation:

Property	Type	Description
baseAmount	string	The amount requested by the Merchant which will be deducted from the Merchant's balance and converted to the selected cryptocurrency.
baseCurrency	string	FIAT currency which will be used to convert the specified `baseAmount` to the selected cryptocurrency.
finalAmount	string	The amount of cryptocurrency that the specified address will receive after the conversion. Directly related to the `finalCurrency`.
finalCurrency	string	The cryptocurrency ticker in which the withdrawal will be finalised. Directly related to the `finalAmount`.

For example:

{
  "baseAmount": "30",
  "baseCurrency": "USD",
  "finalAmount": "29.7",
  "finalCurrency": "USDC"
}

destination

This object provides the information about where the specific withdrawal will be sent to.

Property	Type	Description
address	string	The address where the withdrawal amount and currency are sent to. The address must belong to the specific network of the `finalCurrency` you specify in the Create Withdrawal request.
tag	string	The `addressTag` specified in the Create Withdrawal request. Also called memo, depending on the cryptocurrency. Learn more about the destination tags here.

For example:

{
  "address": "0x8c58D12ce7219B6F53B1803d00b7021CB8e9A4c6",
  "tag": null
}

transactionId

The ID of the transaction as seen on the blockchain. You can search for this value on a blockchain explorer, depending on which blockchain was the transaction executed.

context

Arbitrary data associated with a Withdrawal. Can be used to store things like ID of the shop that issued the Withdrawal etc. Please refrain from storing any personal data in here as this context is public information. When provided, must be a key-value hash where both the keys and their values are strings. Can accept up to 50 keys.

For example:

{
  "shopId":"12345",
  "dateTime":"1678291098"
}

memo

Human-readable description of the withdrawal request.

customerId

Unique identifier of the Merchant's customer, as provided by the Merchant.

customerEmail

The email of the Merchant's customer, as provided by the Merchant.