Customers webhooks

Overview

Customer webhooks notify the merchant system about customer purse address lifecycle events and incoming customer deposit processing.

Use webhooks to update transaction state in your system, detect compliance results, reconcile received funds, and react to expired customer addresses.

Webhook events

Event type	Delivery	Trigger	Merchant action
CUSTOMER_PURSE_EXPIRED	Required for address expiration	Customer purse address expired.	Request a new purse address if the customer needs to continue depositing.
CUSTOMER_PURSE_MEM_POOL_FOUND	Optional	Transaction was detected in the mempool. This event is not guaranteed.	Save the transaction ID and wait for the next webhook.
CUSTOMER_PURSE_PENDING_COMPLIANCE	Optional	Transaction is under compliance check. This event may be skipped if the transaction automatically passes compliance.	Keep the transaction pending in your system if this webhook is received.
CUSTOMER_PURSE_COMPLIANCE_DECLINED	Required for negative compliance result	Transaction failed compliance check.	Do not credit the customer balance. Check transaction details if needed.
CUSTOMER_PURSE_FUNDS_RECEIVED_FOR_PURSE	Required for successful customer purse deposit	Transaction was received successfully for the customer purse.	Confirm transaction details and credit the customer balance if expected.
CUSTOMER_PURSE_TRANSLATION_TO_ACCOUNT_COMPLETED	Optional	Funds were credited to the merchant account.	Reconcile customer transaction with the merchant account balance.

Payload fields

Fields can differ by event type. The table below describes fields used in customer purse webhook payloads.

Field	Type	Events	Description
customerId	string	Customer purse events	Calypso customer ID.
customerBlocked	boolean	Customer purse events	Customer blocked status at the moment of the event.
purseId	string	Customer purse events	Customer purse ID.
address	string	Customer purse events	Customer deposit address.
currency	string	Transaction events	Transaction currency.
transactionId	string	Transaction events	Calypso customer purse transaction ID.
amount	number	Transaction events	Transaction amount.
senderAddress	string	MEM_POOL_FOUND, FUNDS_RECEIVED_FOR_PURSE	Sender address.
transactionHash	string	Transaction events	Blockchain transaction hash.
createdDate	string	Transaction events	Date and time when the transaction was created.
serviceFee	number	TRANSLATION_TO_ACCOUNT_COMPLETED	Transaction service fee.
externalId	string	TRANSLATION_TO_ACCOUNT_COMPLETED	Merchant-side external order identifier, if provided.

Event examples

CUSTOMER_PURSE_FUNDS_RECEIVED_FOR_PURSE

{
  "requestId": "a381f753-3079-4214-9720-b416fc35ca10",
  "id": 1331293,
  "createdDate": "2026-06-29T09:00:00.000Z",
  "level": "INFO",
  "service": "CUSTOMER_PURSE",
  "eventType": "CUSTOMER_PURSE_FUNDS_RECEIVED_FOR_PURSE",
  "data": {
    "type": "CUSTOMER_PURSE_FUNDS_RECEIVED_FOR_PURSE",
    "amount": 2,
    "purseId": "0a510bef-6b87-4d85-b803-6af87d5fb996",
    "currency": "USDT_TRX",
    "customerId": "acf0e319-3054-47fa-8117-12691a568359",
    "createdDate": "2026-06-29T09:00:00.000Z",
    "senderAddress": "internal withdrawal address",
    "transactionId": "123dce78-2ca9-4e94-b657-5751c95cabd6",
    "customerBlocked": false,
    "transactionHash": "0xe9dce5e6e602f900f14b209ec8800cf62f7def380f53723905a7724c8c22523a"
  }
}

CUSTOMER_PURSE_EXPIRED

{
  "eventType": "CUSTOMER_PURSE_EXPIRED",
  "data": {
    "customerId": "acf0e319-3054-47fa-8117-12691a568359",
    "customerBlocked": false,
    "purseId": "0a510bef-6b87-4d85-b803-6af87d5fb996",
    "address": "0x8ab54579efb614b9c46fb36db6a753df2cd18d65"
  }
}

Recommended handling

Case	Recommendation
Webhook received	Save the event and update transaction state in your system.
Terminal transaction webhook received	Confirm transaction details by using [POST] customer-purse/transaction/get.
Customer is blocked	Pay attention to customerBlocked: true and process funds according to your internal rules.
Address expired	Request a new customer purse address before showing a deposit address to the customer again.

Related docs

Document	Link
Process customer transactions	How to process Customer transactions
Get customer deposit address	How to get a deposit address for a customer
Customer Purse API reference	Customer Purse API