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"

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/v1/pay/:uuid/summary (link) to check both the status and displayCurrency.actual field values.

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

Webhook Payload Data

Parameter

Type

Description

source

string

Webhook source e.g. a payment

event

string

Can be

  • transactiondDetected

  • transactionConfirmed

  • statusChanged

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.

PreviousPayment WorkflowNextCreating Payments

Last updated