Skip to content

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

SourceSetup 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" }'

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"

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."
  }'

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