How to process Customer transactions

Overview

Customer transaction processing starts when Calypso detects an incoming deposit to a customer purse address.

Use this guide to process customer purse webhooks, understand transaction and compliance states, and confirm transaction details through the Customer Purse API.

Processing flow

1. Customer sends funds to a customer purse address.
2. Calypso may send CUSTOMER_PURSE_MEM_POOL_FOUND when the transaction is detected in the mempool. This webhook is not guaranteed.
   • Calypso may send CUSTOMER_PURSE_PENDING_COMPLIANCE when the transaction is under compliance check. This webhook is optional and may be skipped if the transaction automatically passes compliance.
   • If the transaction fails compliance, Calypso sends CUSTOMER_PURSE_COMPLIANCE_DECLINED. This is the terminal webhook for a negative compliance result.
3. If the transaction is confirmed, Calypso sends CUSTOMER_PURSE_FUNDS_RECEIVED_FOR_PURSE.
4. After receiving a terminal webhook, get transaction details by using the method [POST] customer-purse/transaction/get.

Sequence

Names of requests on the scheme indicate webhook events and Customer Purse API methods.

Transaction states

Transaction state	Compliance state	Description	Merchant action
MEM_POOL_FOUND	UNCHECKED	Transaction was detected in the mempool. This state is not guaranteed.	Wait for the next webhook.
PENDING_COMPLIANCE_CHECK	IN_PROGRESS	Transaction is under compliance check. This intermediate state is optional and may be skipped when compliance is passed automatically.	Wait for a terminal webhook.
DECLINED	DECLINE	Transaction failed compliance check.	Do not credit the customer balance. Check transaction details and notify the customer according to your process.
CONFIRMED	CHECKED	Transaction was received successfully.	Confirm transaction details and credit the customer balance if it matches your business rules.

API methods

Get customer purse transaction - [POST] customer-purse/transaction/get

Request fields

Field	Type	Required	Description
account	string	Yes	Merchant account ID. The request will be sent for this account.
timestamp	number	Yes	Current Unix UTC timestamp in milliseconds. The value must not be less than 3 minutes in the past or greater than 3 minutes in the future.
payload	object	Yes	Object with transaction ID.

Payload fields

Field	Type	Required	Description
transactionId	string	Yes	Calypso customer purse transaction ID.

Request example

{
  "account": "0x0000000000000000000000000000000000000000",
  "timestamp": 1761650432438,
  "payload": {
    "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

Response fields

Field	Type	Description
id	string	Customer purse transaction ID.
amount	number	Transaction amount.
addressFrom	string	Sender address.
currency	string	Transaction currency.
transactionHash	string	Blockchain transaction hash, if available.
transactionState	string	Current transaction state.
complianceState	string	Current compliance state.
translationToAccountCompleted	boolean	Shows whether funds were transferred to the merchant account.
createdDate	string	Date and time when the transaction was created.

Response example 200 OK

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "amount": 100,
  "addressFrom": "0x0000000000000000000000000000000000000001",
  "currency": "USDT_TRX",
  "transactionHash": "0xe9dce5e6e602f900f14b209ec8800cf62f7def380f53723905a7724c8c22523a",
  "transactionState": "CONFIRMED",
  "complianceState": "CHECKED",
  "translationToAccountCompleted": true,
  "createdDate": "2026-06-29T09:00:00.000Z"
}

Find customer purse transactions - [POST] customer-purse/transaction/find

Field	Type	Required	Description
customerId	string	Yes	Calypso customer ID.
currencyFilter	object	No	Currency filter.
transactionStateFilter	object	No	Transaction state filter.
pageNumber	number	Yes	Page number. Default value: 1.
pageSize	number	Yes	Page size. Default value: 10.
sort	string	Yes	Sort direction: ASC or DESC.
properties	string	Yes	Attribute used for sorting.

Webhook events

Webhook event	Trigger	Merchant action
CUSTOMER_PURSE_MEM_POOL_FOUND	Transaction was detected in the mempool. This webhook is not guaranteed.	Wait for compliance and confirmation webhooks.
CUSTOMER_PURSE_PENDING_COMPLIANCE	Transaction is under compliance check. This webhook is optional and may be skipped when compliance is passed automatically.	Wait for a terminal webhook.
CUSTOMER_PURSE_COMPLIANCE_DECLINED	Transaction failed compliance check. This is the terminal webhook for a negative compliance result.	Do not credit the customer balance.
CUSTOMER_PURSE_FUNDS_RECEIVED_FOR_PURSE	Transaction was received successfully.	Confirm transaction details and credit the customer balance if expected.
CUSTOMER_PURSE_TRANSLATION_TO_ACCOUNT_COMPLETED	Funds were credited to the merchant account.	Reconcile the customer transaction with the merchant account balance.

Related docs

Document	Link
Customers webhooks	Customers webhooks
Get customer deposit address	How to get a deposit address for a customer
Customer Purse API reference	Customer Purse API