Payout Webhooks

Click the tabs below to see what webhooks you will receive from Coindirect while processing payout requests.

The scenario in this example is the following:

1. The Customer requests a payout in cryptocurrency in the Merchant's platform

2. The Merchant makes a POST /api/v1/pay/summary call to request a payout

3. Coindirect receives the API call and creates a payout with the status of PENDING and then immediately updates the status to PROCESSING

4. Once the payout status is updated to PROCESSING, Coindirect sends a relevant webhook - see examples below

5. As soon as Coindirect sends a cryptocurrency transaction to a destination address, the payout updates its status from PROCESSING to COMPLETE - Coindirect sends a relevant webhook

6. If the payout status updates from PROCESSING to CANCELLED instead of being updated to COMPLETE, it means that the payout request has been failed and no cryptocurrency transaction has been sent

Once you finalize the payment on your side, please ensure that no more transactions will appear on the customer's balance in case you receive further webhooks with the same payment UUID from us - this is to avoid potential issues with duplicate balance transactions.

No under circumstances should you completely rely only on webhooks when finalizing the payment on your side.

Once a webhook is received, we highly recommend making an additional API call to retrieve the payment details via GET /api/pay/v1/:uuid/summary (link) to check both the status and displayCurrency.actual field values.

status: PROCESSING

{
  "source": "payment",
  "event": "statusChanged",
  "data": {
    "uuid": "0e135a7e-82e5-4b59-8682-d6e7db362c1d",
    "merchantId": "9a57c17a-1eef-48ff-83d0-b5892c99f767",
    "dateCreated": 1633010474797,
    "expiryDate": 1633014067303,
    "reference": "af1f5c35-a818-4493-957b-8678f6b90ff6",
    "type": "OUT",
    "status": "PROCESSING",
    "displayCurrency": {
      "currency": "JPY",
      "amount": 5000,
      "actual": 5000
    },
    "walletCurrency": {
      "currency": "EUR",
      "amount": 38.59,
      "actual": 38.59
    },
    "paidCurrency": {
      "currency": null,
      "amount": 0,
      "actual": 0
    },
    "feeCurrency": {
      "currency": "EUR",
      "amount": 0.38,
      "actual": 0.38
    },
    "displayRate": {
      "base": "EUR",
      "counter": "JPY",
      "rate": 129.567245400362788287
    },
    "exchangeRate": {
      "base": "USDT",
      "counter": "EUR",
      "rate": 0.545751261991275176
    },
    "address": {
      "protocol": null,
      "address": "THr6oYBp7mgUHiLoxYcqKtoKneKvEhyE22",
      "tag": "[]"
    },
    "redirectUrl": null,
    "returnUrl": "https://yourwebsitename.com",
    "transactions": [
      {
        "dateCreated": 1633010478635,
        "dateConfirmed": null,
        "hash": null,
        "amount": 21.0605412,
        "risk": "UNKNOWN",
        "networkFeeCurrency": null,
        "networkFeeAmount": null,
        "sources": null,
        "exchangeRate": {
          "base": "USDT",
          "counter": "EUR",
          "rate": 1.8323365783
        },
        "displayRate": {
          "base": "JPY",
          "counter": "USDT",
          "rate": 0.007718
        }
      }
    ]
  }
}

status: COMPLETE

{
  "source": "payment",
  "event": "statusChanged",
  "data": {
    "uuid": "0e135a7e-82e5-4b59-8682-d6e7db362c1d",
    "merchantId": "9a57c17a-1eef-48ff-83d0-b5892c99f767",
    "dateCreated": 1633010475000,
    "expiryDate": 1633014067000,
    "reference": "af1f5c35-a818-4493-957b-8678f6b90ff6",
    "type": "OUT",
    "status": "COMPLETE",
    "displayCurrency": {
      "currency": "JPY",
      "amount": 5000,
      "actual": 5000
    },
    "walletCurrency": {
      "currency": "EUR",
      "amount": 38.59,
      "actual": 38.59
    },
    "paidCurrency": {
      "currency": null,
      "amount": 0,
      "actual": 0
    },
    "feeCurrency": {
      "currency": "EUR",
      "amount": 0.38,
      "actual": 0.38
    },
    "displayRate": {
      "base": "EUR",
      "counter": "JPY",
      "rate": 129.567245400362788287
    },
    "exchangeRate": {
      "base": "USDT",
      "counter": "EUR",
      "rate": 0.545751261991275176
    },
    "address": {
      "protocol": null,
      "address": "THr6oYBp7mgUHiLoxYcqKtoKneKvEhyE22",
      "tag": "[]"
    },
    "redirectUrl": null,
    "returnUrl": "https://yourwebsitename.com",
    "transactions": [
      {
        "dateCreated": 1633010479000,
        "dateConfirmed": null,
        "hash": null,
        "amount": 21.0605412,
        "risk": "UNKNOWN",
        "networkFeeCurrency": null,
        "networkFeeAmount": null,
        "sources": null,
        "exchangeRate": {
          "base": "USDT",
          "counter": "EUR",
          "rate": 1.8323365783
        },
        "displayRate": {
          "base": "JPY",
          "counter": "USDT",
          "rate": 0.007718
        }
      }
    ]
  }
}

status: CANCELLED

{
  "source": "payment",
  "event": "statusChanged",
  "data": {
    "uuid": "0e135a7e-82e5-4b59-8682-d6e7db362c1d",
    "merchantId": "9a57c17a-1eef-48ff-83d0-b5892c99f767",
    "dateCreated": 1633010474797,
    "expiryDate": 1633014067303,
    "reference": "af1f5c35-a818-4493-957b-8678f6b90ff6",
    "type": "OUT",
    "status": "CANCELLED",
    "displayCurrency": {
      "currency": "JPY",
      "amount": 5000,
      "actual": 5000
    },
    "walletCurrency": {
      "currency": "EUR",
      "amount": 38.59,
      "actual": 38.59
    },
    "paidCurrency": {
      "currency": null,
      "amount": 0,
      "actual": 0
    },
    "feeCurrency": {
      "currency": "EUR",
      "amount": 0.38,
      "actual": 0.38
    },
    "displayRate": {
      "base": "EUR",
      "counter": "JPY",
      "rate": 129.567245400362788287
    },
    "exchangeRate": {
      "base": "USDT",
      "counter": "EUR",
      "rate": 0.545751261991275176
    },
    "address": {
      "protocol": null,
      "address": "THr6oYBp7mgUHiLoxYcqKtoKneKvEhyE22",
      "tag": "[]"
    },
    "redirectUrl": null,
    "returnUrl": "https://yourwebsitename.com",
    "transactions": [
      {
        "dateCreated": 1633010478635,
        "dateConfirmed": null,
        "hash": null,
        "amount": 21.0605412,
        "risk": "UNKNOWN",
        "networkFeeCurrency": null,
        "networkFeeAmount": null,
        "sources": null,
        "exchangeRate": {
          "base": "USDT",
          "counter": "EUR",
          "rate": 1.8323365783
        },
        "displayRate": {
          "base": "JPY",
          "counter": "USDT",
          "rate": 0.007718
        }
      }
    ]
  }
}

Webhook Payload Data

Parameter	Type	Description
source	string	Webhook source e.g. a payment
event	string	Can be statusChanged only
data	object	An object that contains the payment data
data.uuid	string	Payment UUID
data.merchantId	string	Merchant ID
data.dateCreated	long	Payment creation date and time
data.expiryDate	long	Payment expiry date
data.quoteExpiryDate	long	Quote expiry date
data.reference	string	Payment external ID
data.type	string	IN for inbound payments. OUT for outbound payments
data.status	string	Payment status. See the list of payment statuses in Payouts How-Tos on the left
data.displayCurrency	object	Contains data about the payment price currency and amount
data.displayCurrency.currency	string	Payment price currency e.g. JPY
data.displayCurrency.amount	big decimal	Payment price amount
data.displayCurrency.actual	big decimal	The actual payment amount in price currency that the payment resulted in
data.walletCurrency	object	Contain data about both the payment's source wallet currency and the amount
data.walletCurrency.currency	string	The merchant's target wallet currency that the cryptocurrency payment was converted and debited from
data.walletCurrency.amount	big decimal	The amount that was debited from the merchant's wallet
data.walletCurrency.actual	big decimal	The amount that was debited from the merchant's wallet
data.paidCurrency	object	Contains data about the amount of cryptocurrency that the customer is supposed to receive into their wallet. It also contains both the currency code and the actual amount of received cryptocurrency
data.paidCurrency.currency	string	Cryptocurrency code e.g. ETH
data.paidCurrency.amount	big decimal	The amount of cryptocurrency that is supposed to be sent to the payment address
data.paidCurrency.actual	big decimal	The actual amount of received cryptocurrency
data.feeCurrency	object	Contains data about payment fees
data.feeCurrency.currency	string	Fee currency code
data.feeCurrency.amount	big decimal	Fee amount that was debited from the merchant's wallet balance
data.feeCurrency.actual	big decimal	Fee amount that was debited from the merchant's wallet balance
data.displayRate	object	An object that contain data about the display rate.
data.displayRate.base	string	Base currency type
data.displayRate.counter	string	Couter currency type
data.displayRate.rate	big decmal	Rate
data.exchangeRate	object	An object that contains data about the paymen exchange rate
data.exchangeRate.base	string	Base currency code
data.exchangeRate.counter	string	Counter currency code
data.exchangeRate.rate	big decimal	Rate
data.address	object	Contains data about the cryptocurrency address and destination tag (in case of XRP)
data.address.protocol	string	The protocol type supported by the payment. If there are multiple protocols supported, see the data.address.alternatives array below
data.address.address	string	The payment address. This is the address that the customer specified as their wallet address
data.address.tag	string	This is a payment destination tag. This fields isn't null when the paidCurrency.currency vlau is XRP. A destination tag should be viewable to the customer as destination tags indicate the beneficiary or destination for a payment. For example, a payment to an exchange or gateway address can use a destination tag to indicate which customer to credit for the amount of the payment in that business's own systems. A payment to a merchant could indicate what item or cart the payment is buying
data.address.uri	string	The destination address URI
data.address.alternatives[]	array	Fields are the same as in the case of the data.address array
data.redirectUrl	string	URL to the payment page that you can redirect your customers to
data.returnUrl	string	URL that the customer will be redirected to if they click a "Back to Merchant" button on the payment page
data.transactions[]	array	Contains data about cryptocurrency transactions and exchange rates
data.transactions[].dateCreated	long	Cryptocurrency transaction detection timestamp
data.transactions[].dateConfirmed	long	Cryptocurrency transaction confirmation timestamp
data.transactions[].hash	string	Cryptocurrency transaction hash
data.transactions[].amount	big decimal	Cryptocurrency transaction amount
data.transactions[].risk	object	Cryptocurrency transaction risk details
data.transactions[].risk.level	string	Cryptocurrency transaction risk levl. Can unknonw, low, medium or high
data.transactions[].resourceName	string	Cryptocurrency transaction resource name
data.transactions[].risk.resourceCategory	string	Cryptocurrency transaction resource category
data.transactions[].netwokFeeCurrency	string	Cryptocurrency transaction network fee details
data.transactions[].networkFeeAmount	big decimal	Network fee amount
data.transactions[].sources	array, string	The wallet addresses that the cryptocurrency transaction was sent from
data.transactions[].exchangeRate	object	The exchange rate that was used to convert cryptocurrency to the wallet currency
data.transactions[].exchangeRate.base	string	Base currency
data.transactions[].exchangeRate.counter	string	Counter currency
data.transactions[].exchangeRate.rate	big decimal	Exhange rate
data.transactions[].displayRate	object	The display rate
data.transactions[].displayRate.base	string	Base currency
data.transactions[].displayRate.counter	string	Counter currency
data.transactions[].displayRate.rate	big decimal	Rate