Incoming transactions
Receive messages or detected deposits, review the record, and respond.
Incoming records can come from a Travel Rule message sent by another VASP or from optional blockchain monitoring. Both use direction: "INCOMING" and the same transaction API and webhook mechanism.
Choose the incoming path
| Source | Setup and handling |
|---|---|
| Another VASP sends a Travel Rule message. | Register your custodial wallets, receive the message, review available data, then confirm or decline it. |
| CryptoSwift detects an inbound blockchain transfer. | Enable automatic incoming detection. Records use travelRuleMessageSource: "Automatic" and may initially lack originator information. |
1. Register and confirm your wallets
Maintain the custodial addresses your VASP controls in Production, and use a separate small test inventory in Sandbox. This helps match incoming messages and enables eligible wallets for automatic detection.
If incoming participant PII is hidden, inspect blockchainInfo.isDestinationConfirmed and follow wallet confirmation. Your custodial inventory is separate from a customer's self-hosted wallet.
Receiving transaction data
Configure webhooks. A new incoming message normally arrives as X-Event-Type: transaction, direction: "INCOMING", and status: "DELIVERED". Later notifications can include a hash, changed party data, enrichment, or an originator cancellation.
This example shows a delivered message for a confirmed destination wallet, so participant PII is visible.
ExampleIncoming transaction notificationWebhook POST
{
"id": "233e3fd4-2ef0-677c-a398-8f993d131a19",
"status": "DELIVERED",
"statusReasoning": null,
"direction": "INCOMING",
"createdAt": "2025-12-09T12:55:30.519Z",
"asset": "ETH",
"amount": 0.059625001,
"blockchainInfo": {
"transactionHash": "0x8129df36bf862c55702ab3991c4cc6d00903dc7af4b6f1afc909c216f07e34bd",
"origin": "0x1234567890abcdef1234567890abcdef12345678",
"destination": "0xabcdef1234567890abcdef1234567890abcdef12",
"destinationType": "CUSTODIAL",
"blockchain": "Ethereum",
"isDestinationConfirmed": true,
"destinationWalletId": 7069
},
"vaspInfo": {
"originatorVaspName": "CryptoXYZ",
"originatorVaspEmail": "support@xyz.domain",
"beneficiaryVaspName": "CryptoXchange",
"beneficiaryVaspEmail": "support@cryptox.domain",
"beneficiaryVaspExtraInfo": null
},
"originator": {
"type": "NATURAL",
"name": "Diana DueDiligence",
"accountNumber": "originator-account-123",
"address": "873 Audit Alley",
"country": "AU",
"nationalIdentificatorType": null,
"nationalIdentificator": null,
"customerNumber": null,
"dateOfBirth": null,
"placeOfBirth": null
},
"beneficiary": {
"type": "NATURAL",
"name": "John Smither",
"accountNumber": "AC-123",
"country": null,
"nationalIdentificatorType": null,
"nationalIdentificator": null
},
"travelRuleMessageSource": "CryptoSwift",
"warnings": [],
"riskScore": {
"originatorRiskScore": 72,
"originatorRiskSeverity": "high",
"beneficiaryRiskScore": 8,
"beneficiaryRiskSeverity": "low"
},
"ruleEngine": {
"decision": "REVIEW",
"ruleEngineId": "6292e827-ce05-4cae-a3c8-43e1fb073e1e",
"ruleId": "7f3db7f7-b5b4-4dd7-8de6-e6c15a6eb9e2",
"ruleName": "Review high-risk incoming originator",
"conditions": {
"all": [
{
"field": "riskSeverity",
"value": "high",
"operator": "EQ"
}
],
"any": []
},
"ruleEngineVersion": 3,
"scope": "INCOMING",
"waitForSeconds": null,
"onTimeoutDecision": null
},
"identifiedTenant": {
"name": "CryptoXchange",
"email": "support@cryptox.domain"
}
}
Verify the signature and upsert by transaction id. Retrieve the current record with GET /transactions/{id} before making a decision. Full payload examples and the data model are available separately.
If you cannot receive webhooks, use GET /transactions with _direction=INCOMING and overlapping creation-time windows to discover new IDs. Poll already-known IDs separately for later changes. See the reconciliation pattern.
Use risk score in incoming review workflows
Match the message to the intended deposit and validate the participant data. Use available risk and sanctions results, your own policy, or an optional Rule Engine decision to decide whether to proceed, wait, review, or block.
Incoming records can exist before an on-chain transfer is broadcast. Confirming a message records acceptance of the data; your backend independently controls ledger credit and release of funds. If required information is absent, use the missing Travel Rule data guide.
Respond to incoming Travel Rule messages
Confirming a transaction
When your review accepts the message, update its status:
curl --request PATCH 'https://api-dev.cryptoswift.eu/transactions/{transactionId}' \
--header "X-Api-Key: $API_KEY" \
--header 'Content-Type: application/json' \
--data '{ "status": "CONFIRMED" }'
HTTP/1.1 200 OK
This success response has no body. Do not parse it as JSON.
Read the updated record:
curl --location 'https://api-dev.cryptoswift.eu/transactions/233e3fd4-2ef0-677c-a398-8f993d131a19' \ --header "X-Api-Key: $API_KEY"
{
"id": "233e3fd4-2ef0-677c-a398-8f993d131a19",
"status": "CONFIRMED",
"statusReasoning": null,
"direction": "INCOMING",
"createdAt": "2025-12-09T12:55:30.519Z",
"asset": "ETH",
"amount": 0.059625001,
"blockchainInfo": {
"transactionHash": "0x8129df36bf862c55702ab3991c4cc6d00903dc7af4b6f1afc909c216f07e34bd",
"origin": "0x1234567890abcdef1234567890abcdef12345678",
"destination": "0xabcdef1234567890abcdef1234567890abcdef12",
"destinationType": "CUSTODIAL",
"blockchain": "Ethereum",
"isDestinationConfirmed": true,
"destinationWalletId": 7069
},
"vaspInfo": {
"originatorVaspName": "CryptoXYZ",
"originatorVaspEmail": "support@xyz.domain",
"beneficiaryVaspName": "CryptoXchange",
"beneficiaryVaspEmail": "support@cryptox.domain",
"beneficiaryVaspExtraInfo": null
},
"originator": {
"type": "NATURAL",
"name": "Diana DueDiligence",
"accountNumber": "originator-account-123",
"address": "873 Audit Alley",
"country": "AU",
"nationalIdentificatorType": null,
"nationalIdentificator": null,
"customerNumber": null,
"dateOfBirth": null,
"placeOfBirth": null
},
"beneficiary": {
"type": "NATURAL",
"name": "John Smither",
"accountNumber": "AC-123",
"country": null,
"nationalIdentificatorType": null,
"nationalIdentificator": null
},
"travelRuleMessageSource": "CryptoSwift",
"warnings": [],
"riskScore": {
"originatorRiskScore": 72,
"originatorRiskSeverity": "high",
"beneficiaryRiskScore": 8,
"beneficiaryRiskSeverity": "low"
},
"ruleEngine": {
"decision": "REVIEW",
"ruleEngineId": "6292e827-ce05-4cae-a3c8-43e1fb073e1e",
"ruleId": "7f3db7f7-b5b4-4dd7-8de6-e6c15a6eb9e2",
"ruleName": "Review high-risk incoming originator",
"conditions": {
"all": [
{
"field": "riskSeverity",
"value": "high",
"operator": "EQ"
}
],
"any": []
},
"ruleEngineVersion": 3,
"scope": "INCOMING",
"waitForSeconds": null,
"onTimeoutDecision": null
},
"identifiedTenant": {
"name": "CryptoXchange",
"email": "support@cryptox.domain"
}
}
Declining a transaction
Provide a non-empty reason when declining:
curl --request PATCH 'https://api-dev.cryptoswift.eu/transactions/{transactionId}' \
--header "X-Api-Key: $API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"status": "DECLINED",
"statusReasoning": "Beneficiary name mismatch. Please review."
}'
HTTP/1.1 200 OK
This success response has no body. Do not parse it as JSON.
The response is reflected to the originator through the applicable integration. You cannot set CANCELLED on an incoming message, or change the status of an incoming message already cancelled by its originator. See transaction update constraints.
Improving delivery rates
Keep your wallet inventory current and provide accurate VASP identity information. CryptoSwift can match incoming messages using VASP names, contact information, registered destination wallets, and available analytics. Follow the wallet inventory guide for bulk setup and ongoing maintenance.
Test your integration
Use Sandbox webhook scenarios to check new messages, later hash updates, hidden PII, confirmation, decline, cancellation, and recovery.
Next steps
- Register your custodial wallets
- Set up webhooks
- Enable automatic incoming detection
- Handle missing Travel Rule data