This page describes the data received from the Withdrawals API endpoints.
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": "[email protected]"
}
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.