# 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 {% hint style="danger" %} 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. {% endhint %} {% hint style="danger" %} No under circumstances should you completely rely only on webhooks when finalizing the payment on your side. {% endhint %} {% hint style="danger" %} 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](https://developers.coindirect.com/api/payments/read-payment)) to check both the `status` and `displayCurrency.actual` field values. {% endhint %} {% tabs %} {% tab title="status: PROCESSING" %} ```javascript { "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 } } ] } } ``` {% endtab %} {% tab title="status: COMPLETE" %} ```javascript { "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 } } ] } } ``` {% endtab %} {% tab title="status: CANCELLED" %} ```json { "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 } } ] } } ``` {% endtab %} {% endtabs %} ## 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](https://developers.coindirect.com/guides/payouts-how-to) 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 |