Webhook Sequence for AML Enabled Payments: Deposit Detection and Transaction Status

1. Webhook Sequence (with AML Enabled)

If the merchant has AML enabled and the received amount is ≥ the AML threshold, the payment flow includes an additional AML verification step.

You may receive up to three payment webhooks for a single deposit.

1.1. Webhook 1 — Deposit detected (funds arrived on the wallet)

This webhook is sent when funds first arrive on your deposit address and the system automatically creates a payment.

status = "OPEN"
displayStatus = "OPEN"

Example: Webhook 1 (mock data)

{
  "id": "d1111111-aaaa-4bbb-cccc-eeeeeeee0001",
  "transactions": [
    {
      "paymentId": "d1111111-aaaa-4bbb-cccc-eeeeeeee0001",
      "txnId": "0xf0f0f0f0f0f0aabbccddeeff11223344556677889900aabbccddeeff00112233",
      "receivedAmount": "2.50",
      "asset": {
        "short": "USDT",
        "name": "Tether",
        "logoUrl": "https://cdn.example.com/usdt.png",
        "network": "tron"
      },
      "destTag": null,
      "addressFrom": "TTtt1111aaaabbbb2222cccc3333dddd4444",
      "addressTo": "TTtt9999aaaa5555bbbb6666cccc7777dddd",
      "createdAt": "2025-12-04T07:43:45Z",
      "riskScore": 0,
      "isDanger": false,
      "riskCheckedAt": null,
      "amlPriceUsd": "0"
    }
  ],
  "amount": "2.50",
  "totalReceivedAmount": "2.50",
  "asset": {
    "short": "USDT",
    "name": "Tether",
    "logoUrl": "",
    "network": "tron"
  },
  "addressTo": "TTtt9999aaaa5555bbbb6666cccc7777dddd",
  "destTag": "",
  "confirmsNeeded": 0,
  "timeout": 0,
  "checkoutUrl": "",
  "status": "OPEN",
  "displayStatus": "OPEN",
  "merchant": {
    "id": 10,
    "name": "Mock Merchant",
    "email": "[email protected]",
    "siteUrl": "https://merchant-site.com",
    "logoUrl": "https://cdn.example.com/merchant-logo.png"
  },
  "invoice": "",
  "paymentRedirectURL": "https://alppay.io/payment-invoice?id=d1111111-aaaa-4bbb-cccc-eeeeeeee0001",
  "createdAt": "2025-12-04T07:43:45Z",
  "updatedAt": "2025-12-04T07:43:45Z"
}

1.2. Webhook 2 — Transaction received, AML already completed

Difference from 1.1: This webhook is sent when the AML check for the transaction has already been completed. The main difference is that AML fields are now filled:

riskScore = 50
isDanger = false
riskCheckedAt = "2025-12-04T07:44:34.813096Z"
amlPriceUsd = "0.18"

Everything else (transaction structure, fields, payment state) remains the same as in webhook 1.1.

Example: Webhook 2 (mock data)

{
  "id": "d1111111-aaaa-4bbb-cccc-eeeeeeee0001",
  "transactions": [
    {
      "paymentId": "d1111111-aaaa-4bbb-cccc-eeeeeeee0001",
      "txnId": "0xf0f0f0f0f0f0aabbccddeeff11223344556677889900aabbccddeeff00112233",
      "receivedAmount": "2.50",
      "asset": {
        "short": "USDT",
        "name": "Tether",
        "logoUrl": "https://cdn.example.com/usdt.png",
        "network": "tron"
      },
      "destTag": null,
      "addressFrom": "TTtt1111aaaabbbb2222cccc3333dddd4444",
      "addressTo": "TTtt9999aaaa5555bbbb6666cccc7777dddd",
      "createdAt": "2025-12-04T07:43:45Z",
      "riskScore": 50,
      "isDanger": false,
      "riskCheckedAt": "2025-12-04T07:44:34.813096Z",
      "amlPriceUsd": "0.18"
    }
  ],
  "amount": "2.50",
  "totalReceivedAmount": "2.50",
  "asset": {
    "short": "USDT",
    "name": "Tether",
    "logoUrl": "",
    "network": "tron"
  },
  "addressTo": "TTtt9999aaaa5555bbbb6666cccc7777dddd",
  "destTag": "",
  "status": "OPEN",
  "displayStatus": "OPEN",
  "merchant": {
    "id": 10,
    "name": "Mock Merchant",
    "email": "[email protected]",
    "siteUrl": "https://merchant-site.com",
    "logoUrl": "https://cdn.example.com/merchant-logo.png"
  },
  "invoice": "",
  "paymentRedirectURL": "https://alppay.io/payment-invoice?id=d1111111-aaaa-4bbb-cccc-eeeeeeee0001",
  "createdAt": "2025-12-04T07:43:45Z",
  "updatedAt": "2025-12-04T07:44:35Z"
}

1.3. Webhook 3 — Final AML decision (AML passed)

This webhook is sent after AML is fully completed and the transaction is approved.

The only differences from webhook 1.2:

"status": "EXPIRED" — payment is closed
"displayStatus": "COMPLETED" — payment successfully completed

All transaction AML fields remain unchanged.

Example: Webhook 3 (AML passed) (mock data)

{
  "id": "d1111111-aaaa-4bbb-cccc-eeeeeeee0001",
  "transactions": [
    {
      "paymentId": "d1111111-aaaa-4bbb-cccc-eeeeeeee0001",
      "txnId": "0xf0f0f0f0f0f0aabbccddeeff11223344556677889900aabbccddeeff00112233",
      "receivedAmount": "2.50",
      "asset": {
        "short": "USDT",
        "name": "Tether",
        "logoUrl": "https://cdn.example.com/usdt.png",
        "network": "tron"
      },
      "destTag": null,
      "addressFrom": "TTtt1111aaaabbbb2222cccc3333dddd4444",
      "addressTo": "TTtt9999aaaa5555bbbb6666cccc7777dddd",
      "createdAt": "2025-12-04T07:43:45Z",
      "riskScore": 50,
      "isDanger": false,
      "riskCheckedAt": "2025-12-04T07:44:34.813096Z",
      "amlPriceUsd": "0.18"
    }
  ],
  "amount": "2.50",
  "totalReceivedAmount": "2.50",
  "asset": {
    "short": "USDT",
    "name": "Tether",
    "logoUrl": "",
    "network": "tron"
  },
  "addressTo": "TTtt9999aaaa5555bbbb6666cccc7777dddd",
  "destTag": "",
  "status": "EXPIRED",
  "displayStatus": "COMPLETED",
  "merchant": {
    "id": 10,
    "name": "Mock Merchant",
    "email": "[email protected]",
    "siteUrl": "https://merchant-site.com",
    "logoUrl": "https://cdn.example.com/merchant-logo.png"
  },
  "invoice": "",
  "paymentRedirectURL": "https://alppay.io/payment-invoice?id=d1111111-aaaa-4bbb-cccc-eeeeeeee0001",
  "createdAt": "2025-12-04T07:43:45Z",
  "updatedAt": "2025-12-04T07:45:00Z"
}

If AML is successfully passed:

status = "EXPIRED"
displayStatus = "COMPLETED" / "OVERPAID" / "UNDERPAID"

If AML fails (high risk):

status = "EXPIRED"
transactions[0].isDanger
displayStatus = "AML_CHECK_DANGER"
AML fields show high risk
Deposit wallet blocking
Wallet type webhook sending with blocking wallet info

Example (mock data)

{
  "id": "d1111111-aaaa-4bbb-cccc-eeeeeeee0001",
  "transactions": [
    {
      "paymentId": "d1111111-aaaa-4bbb-cccc-eeeeeeee0001",
      "txnId": "0xf0f0f0f0f0f0aabbccddeeff11223344556677889900aabbccddeeff00112233",
      "receivedAmount": "2.50",
      "asset": {
        "short": "USDT",
        "name": "Tether",
        "logoUrl": "https://cdn.example.com/usdt.png",
        "network": "tron"
      },
      "destTag": null,
      "addressFrom": "TTtt1111aaaabbbb2222cccc3333dddd4444",
      "addressTo": "TTtt9999aaaa5555bbbb6666cccc7777dddd",
      "createdAt": "2025-12-04T07:43:45Z",
      "riskScore": 50,
      "isDanger": true,
      "riskCheckedAt": "2025-12-04T07:44:34.813096Z",
      "amlPriceUsd": "0.18"
    }
  ],
  "amount": "2.50",
  "totalReceivedAmount": "2.50",
  "asset": {
    "short": "USDT",
    "name": "Tether",
    "logoUrl": "",
    "network": "tron"
  },
  "addressTo": "TTtt9999aaaa5555bbbb6666cccc7777dddd",
  "destTag": "",
  "confirmsNeeded": 0,
  "timeout": 0,
  "checkoutUrl": "",
  "status": "EXPIRED",
  "displayStatus": "AML_CHECK_DANGER",
  "merchant": {
    "id": 10,
    "name": "Mock Merchant",
    "email": "[email protected]",
    "siteUrl": "https://merchant-site.com",
    "logoUrl": "https://cdn.example.com/merchant-logo.png"
  },
  "invoice": "",
  "paymentRedirectURL": "https://alppay.io/payment-invoice?id=d1111111-aaaa-4bbb-cccc-eeeeeeee0001",
  "createdAt": "2025-12-04T07:43:45Z",
  "updatedAt": "2025-12-04T07:45:00Z"
}

Example: Wallet Type (mock data)

{
  "wallet": {
    "address": "TTtt9999aaaa5555bbbb6666cccc7777dddd",
    "assetShort": "USDT",
    "assetNetwork": "tron",
    "merchantId": 10,
    "merchantName": "Mock Merchant",
    "clientId": ""
  },
  "aml": {
    "riskScore": 50,
    "isDanger": true,
    "riskLevel": "medium",
    "riskCheckedAt": "2025-12-04T11:44:44.202175Z",
    "amlPriceUsd": "0.18"
  }
}

Green scenario (AML passed):

OPEN / OPEN
OPEN / OPEN (with AML fields)
EXPIRED / COMPLETED

Red scenario (high AML risk):

OPEN / OPEN
OPEN / OPEN (with AML fields)
EXPIRED / AML_CHECK_DANGER → no COMPLETED