> For the complete documentation index, see [llms.txt](https://developers.coindirect.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.coindirect.com/guides/payments-how-to/payment-webhooks.md). # Payment Webhooks Click the tabs below to see what webhooks you will receive from Coindirect when a customer completes their payment. The scenario in this example is the following: 1. The customer broadcasts their transaction on the Network 2. Coindirect detects the transaction and sends `"event": "transactionDetected"` webhook to notify the merchant 3. Coindirect then updates the payment status from `PENDING` to `PROCESSING` and sends `"event": "statusChanged"` 4. The transaction gets a required number of confirmations on the Network 5. Coindirect sends `"event": "transactionConfirmed"` webhook to notify the merchant 6. Coindirect then updates the payment status from `PROCESSING` to `COMPLETE` and sends `"event": "statusChanged"` {% 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/v1/pay/:uuid/summary` ([link](/api/payments/read-payment.md)) to check both the `status` and `displayCurrency.actual` field values. {% endhint %} {% tabs %} {% tab title="event: transactionDetected" %} ```javascript { "source": "payment", "event": "transactionDetected", "data": { "uuid": "5c75bc40-c1b2-4f57-b96f-79882a6e7c4b", "merchantId": "9a57c17a-1eef-48ff-83d0-b5892c99f767", "dateCreated": 1633010030000, "expiryDate": 1633011226000, "reference": "c71102cf-4ac7-4503-8003-2e63931dd6e6", "type": "IN", "status": "PENDING", "displayCurrency": { "currency": "JPY", "amount": 10000, "actual": 0 }, "walletCurrency": { "currency": "EUR", "amount": 77.11, "actual": 0 }, "paidCurrency": { "currency": "ETH", "amount": 0.0305817, "actual": 0 }, "feeCurrency": { "currency": "EUR", "amount": 0.77, "actual": 0 }, "displayRate": { "base": "ETH", "counter": "JPY", "rate": 326992.94022242059793929 }, "exchangeRate": { "base": "EUR", "counter": "ETH", "rate": 2521.442345707899981442 }, "address": { "protocol": null, "address": "0x6115cfe64f3a8e4d974984a22a01936343bc8156", "tag": null }, "redirectUrl": "https://business.sandbox.coindirect.com/payin?uuid=5c75bc40-c1b2-4f57-b96f-79882a6e7c4b&flow=direct", "returnUrl": "https://yourwebsitename.com", "transactions": [ { "dateCreated": 1633010179620, "dateConfirmed": null, "hash": "0x087bcfd76ae12d6116d35a442e51dfff99e77fbf8330be39017dbdc60df7afea", "amount": 0, "risk": null, "networkFeeCurrency": null, "networkFeeAmount": null, "sources": null, "exchangeRate": null, "displayRate": null } ] } } ``` {% endtab %} {% tab title="event: statusChanged" %} ```javascript { "source": "payment", "event": "statusChanged", "data": { "uuid": "5c75bc40-c1b2-4f57-b96f-79882a6e7c4b", "merchantId": "9a57c17a-1eef-48ff-83d0-b5892c99f767", "dateCreated": 1633010030000, "expiryDate": 1633011226000, "reference": "c71102cf-4ac7-4503-8003-2e63931dd6e6", "type": "IN", "status": "PROCESSING", "displayCurrency": { "currency": "JPY", "amount": 10000, "actual": 0 }, "walletCurrency": { "currency": "EUR", "amount": 77.11, "actual": 0 }, "paidCurrency": { "currency": "ETH", "amount": 0.0305817, "actual": 0 }, "feeCurrency": { "currency": "EUR", "amount": 0.77, "actual": 0 }, "displayRate": { "base": "ETH", "counter": "JPY", "rate": 326992.94022242059793929 }, "exchangeRate": { "base": "EUR", "counter": "ETH", "rate": 2521.442345707899981442 }, "address": { "protocol": null, "address": "0x6115cfe64f3a8e4d974984a22a01936343bc8156", "tag": null }, "redirectUrl": "https://business.sandbox.coindirect.com/payin?uuid=5c75bc40-c1b2-4f57-b96f-79882a6e7c4b&flow=direct", "returnUrl": "https://yourwebsitename.com", "transactions": [ { "dateCreated": 1633010179620, "dateConfirmed": null, "hash": "0x087bcfd76ae12d6116d35a442e51dfff99e77fbf8330be39017dbdc60df7afea", "amount": 0, "risk": null, "networkFeeCurrency": null, "networkFeeAmount": null, "sources": null, "exchangeRate": null, "displayRate": null } ] } } ``` {% endtab %} {% tab title="event: transactionConfirmed" %} ```javascript { "source": "payment", "event": "transactionConfirmed", "data": { "uuid": "5c75bc40-c1b2-4f57-b96f-79882a6e7c4b", "merchantId": "9a57c17a-1eef-48ff-83d0-b5892c99f767", "dateCreated": 1633010030000, "expiryDate": 1633011226000, "reference": "c71102cf-4ac7-4503-8003-2e63931dd6e6", "type": "IN", "status": "PROCESSING", "displayCurrency": { "currency": "JPY", "amount": 10000, "actual": 0 }, "walletCurrency": { "currency": "EUR", "amount": 77.11, "actual": 0 }, "paidCurrency": { "currency": "ETH", "amount": 0.0305817, "actual": 0.0305817 }, "feeCurrency": { "currency": "EUR", "amount": 0.77, "actual": 0 }, "displayRate": { "base": "ETH", "counter": "JPY", "rate": 326992.94022242059793929 }, "exchangeRate": { "base": "EUR", "counter": "ETH", "rate": 2521.442345707899981442 }, "address": { "protocol": null, "address": "0x6115cfe64f3a8e4d974984a22a01936343bc8156", "tag": null }, "redirectUrl": "https://business.sandbox.coindirect.com/payin?uuid=5c75bc40-c1b2-4f57-b96f-79882a6e7c4b&flow=direct", "returnUrl": "https://yourwebsitename.com", "transactions": [ { "dateCreated": 1633010180000, "dateConfirmed": 1633010241637, "hash": "0x087bcfd76ae12d6116d35a442e51dfff99e77fbf8330be39017dbdc60df7afea", "amount": 0.0305817, "risk": { "level": "UNKNOWN", "resourceName": null, "resourceCategory": null }, "networkFeeCurrency": "ETH", "networkFeeAmount": 0.000031500000252, "sources": [ "0x1a2e97fd13c0610239c0b1cdbb0806f35adff3f0" ], "exchangeRate": { "base": "EUR", "counter": "ETH", "rate": 0.0003965984 }, "displayRate": { "base": "ETH", "counter": "JPY", "rate": 326992.9402224206 } } ] } } ``` {% endtab %} {% tab title="event: statusChanged" %} ```javascript { "source": "payment", "event": "statusChanged", "data": { "uuid": "5c75bc40-c1b2-4f57-b96f-79882a6e7c4b", "merchantId": "9a57c17a-1eef-48ff-83d0-b5892c99f767", "dateCreated": 1633010030000, "expiryDate": 1633011226000, "reference": "c71102cf-4ac7-4503-8003-2e63931dd6e6", "type": "IN", "status": "COMPLETE", "displayCurrency": { "currency": "JPY", "amount": 10000, "actual": 10000 }, "walletCurrency": { "currency": "EUR", "amount": 77.11, "actual": 77.11 }, "paidCurrency": { "currency": "ETH", "amount": 0.0305817, "actual": 0.0305817 }, "feeCurrency": { "currency": "EUR", "amount": 0.77, "actual": 0.77 }, "displayRate": { "base": "ETH", "counter": "JPY", "rate": 326992.94022242059793929 }, "exchangeRate": { "base": "EUR", "counter": "ETH", "rate": 2521.442345707899981442 }, "address": { "protocol": null, "address": "0x6115cfe64f3a8e4d974984a22a01936343bc8156", "tag": null }, "redirectUrl": "https://business.sandbox.coindirect.com/payin?uuid=5c75bc40-c1b2-4f57-b96f-79882a6e7c4b&flow=direct", "returnUrl": "https://yourwebsitename.com", "transactions": [ { "dateCreated": 1633010180000, "dateConfirmed": 1633010241637, "hash": "0x087bcfd76ae12d6116d35a442e51dfff99e77fbf8330be39017dbdc60df7afea", "amount": 0.0305817, "risk": { "level": "UNKNOWN", "resourceName": null, "resourceCategory": null }, "networkFeeCurrency": "ETH", "networkFeeAmount": 0.000031500000252, "sources": [ "0x1a2e97fd13c0610239c0b1cdbb0806f35adff3f0" ], "exchangeRate": { "base": "EUR", "counter": "ETH", "rate": 0.0003965984 }, "displayRate": { "base": "ETH", "counter": "JPY", "rate": 326992.9402224206 } } ] } } ``` {% endtab %} {% endtabs %} ## Webhook Payload Data | Parameter | Type | Description | | ------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `source` | string | Webhook source e.g. a payment | | `event` | string |

Can be

| | `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 Payments 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 target wallet currency and the amount | | `data.walletCurrency.currency` | string | The merchant's target wallet currency that the cryptocurrency payment will be converted and credited to | | `data.walletCurrency.amount` | big decimal | The amount that will be received into the merchant's wallet if the customer sends the exact amount of cryptocurrency that they are supposed to send (see `paidCurrency.amount`) | | `data.walletCurrency.actual` | big decimal | The actual amount that the merchant receives into their wallet after Coindirect converts cryptocurrency | | `data.paidCurrency` | object | Contains data about the `amount` of cryptocurrency that the customer is supposed to send to the payment address. 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 will be debited from the merchant's wallet balance if the customer sends the exact amount of cryptocurrency that they are supposed to send | | `data.feeCurrency.actual` | big decimal | The actual fee amount that Coindirect debited from the merchant's wallet balance after processing the payment | | `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 a customer needs to send their cryptocurrency to | | `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 received cryptocurrency transactions and exchange rates. If no transaction is received, it is empty | | `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 currency | | `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 | See the Webhooks page to get basic information on webhooks and validation. {% content-ref url="/pages/-MgeT5ibtD8TzrOSeD8a" %} [Webhooks](/guides/webhooks.md) {% endcontent-ref %}