Webhook Events

This page describes the payloads Lydian delivers to your webhook endpoints. To register an endpoint, see Webhooks. For guidance on receiving and processing events, see Handle Webhook Events.

The Event Envelope

Every webhook — regardless of type — is delivered as the same JSON envelope over an HTTP POST with Content-Type: application/json. The envelope identifies the event and the account it belongs to, while the event-specific details live in the data object.

Name
accountUUID
Type
string
Description
UUID of the account the event belongs to.
Name
type
Type
string
Description
The event type — see Event Types below.
Name
timestamp
Type
string
Description
RFC 3339 timestamp of when the event was emitted.
Name
data
Type
object
Description
The event payload. Its structure depends on type.

envelope

{
    "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
    "type": "transaction.success",
    "timestamp": "2025-08-15T10:15:44.762134-04:00",
    "data": { }
}

Timestamps in webhook payloads are RFC 3339 strings. Some use UTC (Z) and others a numeric offset such as -04:00, so parse the offset rather than assuming every timestamp ends in Z.

Event Types

A webhook only receives the event types it subscribed to when it was created (the events array — see Create Webhook). The event types currently documented are listed below; treat this as the currently documented set rather than a guaranteed-exhaustive catalog:

`type`	Sent when
`transaction.success`	A transaction is fully paid and confirmed on-chain.
`transaction.failed`	A transaction fails or is cancelled before it completes.
`refund.success`	A refund has completed successfully.
`refund.failed`	A refund has failed.
`session.promoted`	A session has been promoted and a transaction is being created.
`session.canceled`	A session has been canceled and is no longer active.
`session.timedout`	A session has timed out and is no longer active.
`settlement.closed`	A settlement period has ended and the net amount owed to you is final.
`settlement.paid`	The settlement's funds have been sent to your registered payout destination.
`reconciliation_report.generated`	A daily reconciliation report has been generated for your account.

transaction.success

Sent when a transaction has been fully paid and confirmed. The data object is the complete transaction record — identical in structure to the Get Transaction Response. A successful transaction has status 1 and no remaining balance.

Name
data
Type
object
Description
The full transaction object. See the Get Transaction Response for the complete field list.

transaction.success

{
    "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
    "type": "transaction.success",
    "timestamp": "2025-08-15T10:15:44.762134-04:00",
    "data": {
        "transactionID": "236118b0-b43e-421e-998d-0d0f84b99e5a",
        "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
        "merchantID": "7da1d36d-c995-4e99-bfb4-758fd2c94c99",
        "externalMID": "",
        "descriptor": "Order #1234",
        "referenceNumber": "d83fba40-87ea-4a62-bafa-a2601a673f51",
        "status": 1,
        "paymentStatus": 1,
        "amounts": {
            "currency": "USD",
            "totalLocal": 9.34,
            "totalUSD": 9.34,
            "receivedUSD": 9.34,
            "customerFeeUSD": 1.25,
            "fxRateToUSD": 1
        },
        "compliance": {
            "kycTriggered": false,
            "travelRuleTriggered": false
        },
        "payments": [
            {
                "paymentRequestID": "a8f2c1e0-1234-4abc-9def-0123456789ab",
                "cryptoAsset": "USDT",
                "cryptoNetwork": "ethereum",
                "cryptoRatePerUSD": 1,
                "address": "0xe095f9f7b75213d86767c0a6c5de4f2d93c9c4dd",
                "walletName": "metamask",
                "walletType": "non-custodial",
                "expectedCrypto": 9.34,
                "receivedCrypto": 9.34,
                "expectedUSD": 9.34,
                "receivedUSD": 9.34,
                "txnHash": "0x9f2c...c4dd",
                "fromAddress": "0x3a1f9c8b7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b",
                "confirmationCount": 12,
                "completedAt": "2025-08-12T03:21:40.512Z",
                "gasFee": 0.42,
                "gasFeeUnits": "ETH",
                "status": 1,
                "qrData": "ethereum:0xdAC17F958D2ee523a2206206994597C13D831ec7/transfer?address=0xe095f9f7b75213d86767c0a6c5de4f2d93c9c4dd",
                "expiration": "2025-08-12T03:35:02.769Z"
            }
        ],
        "refunds": [],
        "remainingLocal": 0,
        "remainingUSD": 0,
        "cancellationReason": "",
        "createdAt": "2025-08-12T03:20:02.769Z",
        "updatedAt": "2025-08-12T03:21:44.762Z",
        "expiration": "2025-08-12T03:35:02.769Z"
    }
}

transaction.failed

Sent when a transaction fails or is cancelled before it completes. The data object has the same structure as transaction.success — the Get Transaction Response — with the transaction's status reflecting the failure (for example -2 cancelled or -4 forfeited) and cancellationReason set where applicable.

Name
data
Type
object
Description
The full transaction object, with status reflecting the failure. See the Get Transaction Response for the complete field list and the full set of status values.

transaction.failed

{
    "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
    "type": "transaction.failed",
    "timestamp": "2025-08-15T10:22:03.114902-04:00",
    "data": {
        "transactionID": "236118b0-b43e-421e-998d-0d0f84b99e5a",
        "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
        "merchantID": "7da1d36d-c995-4e99-bfb4-758fd2c94c99",
        "descriptor": "Order #1234",
        "referenceNumber": "d83fba40-87ea-4a62-bafa-a2601a673f51",
        "status": -2,
        "paymentStatus": 0,
        "amounts": {
            "currency": "USD",
            "totalLocal": 9.34,
            "totalUSD": 9.34,
            "receivedUSD": 0,
            "customerFeeUSD": 1.25,
            "fxRateToUSD": 1
        },
        "payments": [
            {
                "paymentRequestID": "a8f2c1e0-1234-4abc-9def-0123456789ab",
                "cryptoAsset": "USDT",
                "cryptoNetwork": "ethereum",
                "cryptoRatePerUSD": 1,
                "address": "0xe095f9f7b75213d86767c0a6c5de4f2d93c9c4dd",
                "walletName": "metamask",
                "walletType": "non-custodial",
                "expectedCrypto": 9.34,
                "receivedCrypto": 0,
                "expectedUSD": 9.34,
                "receivedUSD": 0,
                "txnHash": "",
                "fromAddress": "",
                "confirmationCount": 0,
                "completedAt": "0001-01-01T00:00:00Z",
                "gasFee": 0,
                "gasFeeUnits": "",
                "status": 0,
                "qrData": "ethereum:0xdAC17F958D2ee523a2206206994597C13D831ec7/transfer?address=0xe095f9f7b75213d86767c0a6c5de4f2d93c9c4dd",
                "expiration": "2025-08-12T03:35:02.769Z"
            }
        ],
        "remainingLocal": 9.34,
        "remainingUSD": 9.34,
        "cancellationReason": "Payment window expired",
        "createdAt": "2025-08-12T03:20:02.769Z",
        "updatedAt": "2025-08-12T03:35:02.769Z",
        "expiration": "2025-08-12T03:35:02.769Z"
    }
}

refund.success

Sent when a refund completes successfully. The data object is the refund payload; a successful refund has status 1.

Name
createdAt
Type
string
Description
Timestamp when the refund record was created.
Name
updatedAt
Type
string
Description
Timestamp when the refund was last updated.
Name
refundID
Type
string
Description
Unique identifier for the refund.
Name
transactionID
Type
string
Description
Identifier of the transaction associated with the refund.
Name
paymentRequestID
Type
string
Description
Identifier of the payment request associated with the refund.
Name
accountID
Type
string
Description
Identifier of the account associated with the refund.
Name
merchantID
Type
string
Description
Identifier of the merchant associated with the refund.
Name
referenceNumber
Type
string
Description
Merchant reference or order number of the refunded transaction. May be an empty string.
Name
origin
Type
string
Description
What initiated the refund. One of merchant, fraud, or cancellation.
Name
reason
Type
string
Description
Reason for the refund. May be an empty string.
Name
status
Type
integer
Description
Refund status: -1 failed, 0 pending, 1 success.
Name
stage
Type
string
Description
Current stage of the refund. One of queued, sending, swapping, confirming, or done.
Name
route
Type
string
Description
Refund processing route. One of direct, swap, or custody.
Name
custody
Type
string
Description
Custody provider, when applicable. One of bitgo or maya. Optional.
Name
custodyRef
Type
string
Description
Custody provider reference, when applicable. Optional.
Name
failureReason
Type
string
Description
Details about a failure, when present. May be an empty string.
Name
fiatCurrency
Type
string
Description
Fiat currency of the refund (for example USD).
Name
fiatAmount
Type
number
Description
Fiat amount refunded.
Name
gasFeePayer
Type
string
Description
Who absorbs the network gas fee. One of merchant or customer.
Name
receiverAddress
Type
string
Description
Destination wallet address for the refund. May be an empty string.
Name
cryptoAsset
Type
string
Description
Crypto asset returned (for example USDT).
Name
cryptoNetwork
Type
string
Description
Network the refund is delivered on (for example arbitrum).
Name
fiatFXRate
Type
number
Description
Fiat-to-USD exchange rate for the refund.
Name
usdAmount
Type
number
Description
USD value of the refund.
Name
sourceFXRate
Type
number
Description
Source exchange rate stored for the refund.
Name
sourceAmount
Type
number
Description
Source amount stored for the refund.
Name
sourceUSD
Type
number
Description
Source-side USD value for the refund.
Name
sourceTxHash
Type
string
Description
Source transaction hash. May be an empty string.
Name
swapID
Type
string
Description
Swap identifier, when present. Optional.
Name
swapPayinAddress
Type
string
Description
Swap pay-in address, when present. Optional.
Name
swapQuotedAmount
Type
number
Description
Quoted swap amount.
Name
cryptoAmount
Type
number
Description
Crypto amount returned.
Name
deliveryTxHash
Type
string
Description
Delivery transaction hash. May be an empty string.
Name
initiatedAt
Type
string
Description
Timestamp when the refund was initiated.
Name
executedAt
Type
string
Description
Timestamp when the refund was executed.

refund.success

{
    "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
    "type": "refund.success",
    "timestamp": "2025-08-15T10:22:14.512402-04:00",
    "data": {
        "createdAt": "2025-08-15T10:20:02.769Z",
        "updatedAt": "2025-08-15T10:22:14.512Z",
        "refundID": "acd09ac7-612f-4011-ac74-a5e1f4753648",
        "transactionID": "236118b0-b43e-421e-998d-0d0f84b99e5a",
        "paymentRequestID": "a8f2c1e0-1234-4abc-9def-0123456789ab",
        "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
        "merchantID": "7da1d36d-c995-4e99-bfb4-758fd2c94c99",
        "referenceNumber": "d83fba40-87ea-4a62-bafa-a2601a673f51",
        "origin": "merchant",
        "reason": "Customer requested a refund",
        "status": 1,
        "stage": "done",
        "route": "direct",
        "failureReason": "",
        "fiatCurrency": "USD",
        "fiatAmount": 9.34,
        "gasFeePayer": "customer",
        "receiverAddress": "",
        "cryptoAsset": "USDT",
        "cryptoNetwork": "arbitrum",
        "fiatFXRate": 1,
        "usdAmount": 9.34,
        "sourceFXRate": 0,
        "sourceAmount": 0,
        "sourceUSD": 0,
        "sourceTxHash": "",
        "swapQuotedAmount": 0,
        "cryptoAmount": 9.34,
        "deliveryTxHash": "0x9f2c...c4dd",
        "initiatedAt": "2025-08-15T10:20:03.114Z",
        "executedAt": "2025-08-15T10:22:14.500Z"
    }
}

refund.failed

Sent when a refund fails. The data object has the same structure as refund.success, with status -1 and failureReason set when a reason is available.

Name
data
Type
object
Description
The refund object, with status -1. See refund.success for the complete field list.

refund.failed

{
    "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
    "type": "refund.failed",
    "timestamp": "2025-08-15T10:23:41.882013-04:00",
    "data": {
        "createdAt": "2025-08-15T10:20:02.769Z",
        "updatedAt": "2025-08-15T10:23:41.880Z",
        "refundID": "acd09ac7-612f-4011-ac74-a5e1f4753648",
        "transactionID": "236118b0-b43e-421e-998d-0d0f84b99e5a",
        "paymentRequestID": "a8f2c1e0-1234-4abc-9def-0123456789ab",
        "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
        "merchantID": "7da1d36d-c995-4e99-bfb4-758fd2c94c99",
        "referenceNumber": "d83fba40-87ea-4a62-bafa-a2601a673f51",
        "origin": "merchant",
        "reason": "Customer requested a refund",
        "status": -1,
        "stage": "done",
        "route": "direct",
        "failureReason": "destination wallet rejected the transfer",
        "fiatCurrency": "USD",
        "fiatAmount": 9.34,
        "gasFeePayer": "customer",
        "receiverAddress": "",
        "cryptoAsset": "USDT",
        "cryptoNetwork": "arbitrum",
        "fiatFXRate": 1,
        "usdAmount": 9.34,
        "sourceFXRate": 0,
        "sourceAmount": 0,
        "sourceUSD": 0,
        "sourceTxHash": "",
        "swapQuotedAmount": 0,
        "cryptoAmount": 9.34,
        "deliveryTxHash": "0x9f2c...c4dd",
        "initiatedAt": "2025-08-15T10:20:03.114Z",
        "executedAt": "2025-08-15T10:22:14.500Z"
    }
}

session.canceled

Sent when a session has been canceled. The data object is the session's Create Session response.

Name
sessionID
Type
string
Description
Unique identifier for the session.
Name
qrData
Type
string
Description
The data to generate a QR code that can be scanned using mobile devices.
Name
cancelURL
Type
string
Description
Redirect URL used when the session is cancelled.
Name
successURL
Type
string
Description
Redirect URL used on a successful payment.
Name
failureURL
Type
string
Description
Redirect URL used on a failed payment.
Name
fiatFXRate
Type
number
Description
The fiat FX rate locked in for the session when provided; null otherwise.
Name
recommendedNetwork
Type
string
Description
Network recommended to the customer at checkout, when provided.
Name
quoteID
Type
string
Description
Quote identifier associated with the session, when provided.
Name
merchantName
Type
string
Description
Name of the merchant the session belongs to.
Name
referenceNumber
Type
string
Description
Merchant reference or order number for the session. Optional; omitted when not set.

session.canceled

{
    "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
    "type": "session.canceled",
    "timestamp": "2025-08-15T10:15:44.762134-04:00",
    "data": {
        "sessionID": "009a3809-7328-4b6c-873b-089eff019f98",
        "qrData": "https://pay.lydian.com/session/009a3809-7328-4b6c-873b-089eff019f98",
        "cancelURL": "https://brimspire.com/checkout/cancel",
        "successURL": "https://brimspire.com/checkout/success",
        "failureURL": "https://brimspire.com/checkout/failure",
        "fiatFXRate": 1,
        "recommendedNetwork": "ethereum",
        "quoteID": "",
        "merchantName": "Brimspire"
    }
}

session.promoted

Sent when a session has been promoted. The data object has the same structure as session.canceled.

Name
data
Type
object
Description
The session object. See session.canceled for the complete field list.

session.promoted

{
    "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
    "type": "session.promoted",
    "timestamp": "2025-08-15T10:15:44.762134-04:00",
    "data": {
        "sessionID": "009a3809-7328-4b6c-873b-089eff019f98",
        "qrData": "https://pay.lydian.com/session/009a3809-7328-4b6c-873b-089eff019f98",
        "cancelURL": "https://brimspire.com/checkout/cancel",
        "successURL": "https://brimspire.com/checkout/success",
        "failureURL": "https://brimspire.com/checkout/failure",
        "fiatFXRate": 1,
        "recommendedNetwork": "ethereum",
        "quoteID": "",
        "merchantName": "Brimspire"
    }
}

session.timedout

Sent when a session has timed out. The data object has the same structure as session.canceled.

Name
data
Type
object
Description
The session object. See session.canceled for the complete field list.

session.timedout

{
    "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
    "type": "session.timedout",
    "timestamp": "2025-08-15T10:15:44.762134-04:00",
    "data": {
        "sessionID": "009a3809-7328-4b6c-873b-089eff019f98",
        "qrData": "https://pay.lydian.com/session/009a3809-7328-4b6c-873b-089eff019f98",
        "cancelURL": "https://brimspire.com/checkout/cancel",
        "successURL": "https://brimspire.com/checkout/success",
        "failureURL": "https://brimspire.com/checkout/failure",
        "fiatFXRate": 1,
        "recommendedNetwork": "ethereum",
        "quoteID": "",
        "merchantName": "Brimspire"
    }
}

settlement.closed

Sent when a settlement period ends. The data object is the settlement record: the period it covers, its status (1 = closed), and netUSD, the amount owed to you for that period after fees. merchantID is present when the settlement is for a single merchant rather than the whole account. There is no payout yet.

Name
settlementID
Type
string
Description
Unique identifier for the settlement.
Name
accountID
Type
string
Description
UUID of the account being settled.
Name
merchantID
Type
string
Description
UUID of the merchant being settled. Omitted when the settlement covers the whole account.
Name
status
Type
integer
Description
Settlement status. 1 means closed and 3 means paid.
Name
frequency
Type
string
Description
Settlement schedule: hourly, six_hourly, daily, weekly, biweekly, or monthly.
Name
periodStart
Type
string
Description
RFC 3339 start of the settled period (inclusive).
Name
periodEnd
Type
string
Description
RFC 3339 end of the settled period (exclusive).
Name
netUSD
Type
number
Description
Amount owed to you for the period, in USD, after fees.
Name
payout
Type
object
Description
Present once funds have been sent. See settlement.paid below.

settlement.closed

{
    "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
    "type": "settlement.closed",
    "timestamp": "2026-09-07T00:00:04.118273Z",
    "data": {
        "settlementID": "3f0c9a4e-7d1b-4c2a-9e58-1b6f0d2a7c11",
        "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
        "merchantID": "7da1d36d-c995-4e99-bfb4-758fd2c94c99",
        "status": 1,
        "frequency": "daily",
        "periodStart": "2026-09-06T00:00:00Z",
        "periodEnd": "2026-09-07T00:00:00Z",
        "netUSD": 97.5
    }
}

settlement.paid

Sent when the settlement's funds have been sent to your registered payout destination and, for crypto destinations, confirmed on-chain. The data object has the same structure as settlement.closed with status 3 and a payout object describing the transfer.

Name
payout
Type
object
Description
The transfer that paid this settlement.
Payout Object
Name
type
Type
string
Description
Destination type: crypto_wallet or bank_account.
Name
initiatedAt
Type
string
Description
RFC 3339 timestamp of when the transfer was initiated.
Name
confirmedAt
Type
string
Description
RFC 3339 timestamp of when the transfer was confirmed.
Name
cryptoWallet
Type
object
Description
Present for crypto destinations: network, asset, destinationAddress, and the on-chain txnHash.

settlement.paid

{
    "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
    "type": "settlement.paid",
    "timestamp": "2026-09-07T01:05:12.331901Z",
    "data": {
        "settlementID": "3f0c9a4e-7d1b-4c2a-9e58-1b6f0d2a7c11",
        "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
        "merchantID": "7da1d36d-c995-4e99-bfb4-758fd2c94c99",
        "status": 3,
        "frequency": "daily",
        "periodStart": "2026-09-06T00:00:00Z",
        "periodEnd": "2026-09-07T00:00:00Z",
        "netUSD": 97.5,
        "payout": {
            "type": "crypto_wallet",
            "initiatedAt": "2026-09-07T01:00:03.502Z",
            "confirmedAt": "2026-09-07T01:05:12.117Z",
            "cryptoWallet": {
                "network": "arbitrum",
                "asset": "USDT",
                "destinationAddress": "0x1c9a3b7f2e5d4c6b8a0f9e8d7c6b5a4f3e2d1c0b",
                "txnHash": "0x9f2c...c4dd"
            }
        }
    }
}

reconciliation_report.generated

Sent when Lydian generates a daily reconciliation report for your account. Each report covers one calendar day in your account's local time zone (UTC if none is set) and lists the confirmed payments of transactions settled during that day. Reports are generated about an hour after the day ends, including for days with no payments (rowCount 0). The data object describes the generated report file.

Name
reportID
Type
string
Description
Unique identifier for the report.
Name
type
Type
string
Description
Report type. Currently always daily.
Name
accountID
Type
string
Description
UUID of the account the report covers.
Name
periodStart
Type
string
Description
RFC 3339 start of the reported day (inclusive).
Name
periodEnd
Type
string
Description
RFC 3339 end of the reported day (exclusive).
Name
fileName
Type
string
Description
File name of the generated CSV report.
Name
sizeBytes
Type
integer
Description
Size of the report file, in bytes.
Name
checksum
Type
string
Description
SHA-256 hash of the report file's contents, hex-encoded.
Name
rowCount
Type
integer
Description
Number of payment rows in the report, excluding header lines. Can be 0.
Name
generatedAt
Type
string
Description
RFC 3339 timestamp of when the report was generated.

reconciliation_report.generated

{
    "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
    "type": "reconciliation_report.generated",
    "timestamp": "2026-09-07T01:00:04.902117Z",
    "data": {
        "reportID": "8c4e2f1a-6b3d-4a9e-b7c5-2d1f0e9a8b76",
        "type": "daily",
        "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
        "periodStart": "2026-09-06T00:00:00Z",
        "periodEnd": "2026-09-07T00:00:00Z",
        "fileName": "8c4e2f1a-6b3d-4a9e-b7c5-2d1f0e9a8b76-daily.csv",
        "sizeBytes": 2148,
        "checksum": "ad9c12c8986f4d21226f07a06e406c21ccd93e7b93a2b47053f5ec28e590c7bf",
        "rowCount": 6,
        "generatedAt": "2026-09-07T01:00:03.418Z"
    }
}

For guidance on receiving and processing these events, see Handle Webhook Events.