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.

{
  "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
        }
      }
    ]
  }
}

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

PreviousPayout WorkflowNextCreating Payouts

Last updated