AML & Wallet Screening

​

When screening happens

​

Screening a wallet on demand

curl -X POST https://api.sohopay.xyz/v1/aml-check \
  -H "Authorization: Bearer $SOHOPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: aml-check-2026-08-22-001" \
  -d '{
    "wallet_address": "0x8ba1f109551bd432803012645ac136ddd64dba72"
  }'

import { SohoPay } from "@sohopay/sdk";

const sohopay = new SohoPay({ apiKey: process.env.SOHOPAY_API_KEY });

const check = await sohopay.amlChecks.create({
  walletAddress: "0x8ba1f109551bd432803012645ac136ddd64dba72",
});

console.log(check.result); // "clear" | "review" | "declined"

from sohopay import SohoPay

sohopay = SohoPay(api_key=os.environ["SOHOPAY_API_KEY"])

check = sohopay.aml_checks.create(
    wallet_address="0x8ba1f109551bd432803012645ac136ddd64dba72",
)

print(check.result)  # "clear" | "review" | "declined"

{
  "check_id": "req_2f9c1e8a",
  "wallet_address": "0x8ba1f109551bd432803012645ac136ddd64dba72",
  "result": "clear",
  "flags": [],
  "screened_at": "2026-08-22T09:41:07Z"
}

​

The AML decline workflow

1. The payment is rejected with HTTP 402 and error code AML_DECLINED in the standard error envelope. Your agent code should treat this as terminal — do not retry.

{
  "error": {
    "code": "AML_DECLINED",
    "message": "Agent wallet failed AML screening. Payment blocked. Contact support to appeal.",
    "request_id": "req_b7e4a1d2"
  }
}

2. An agent.aml_declined webhook fires so your systems learn about the block even if the failing call happened deep inside agent logic. (An agent.aml_review event fires for the softer review state.) See Webhook events.
3. The operator is notified by email with the flag details and the appeal instructions below. The agent stays blocked until the flag is resolved.

​

Appealing a decline

1. Email support@sohopay.xyz with subject “AML appeal”, the agent or merchant ID, the flagged wallet address, and the request_id from the error.
2. Attach documentation: proof of wallet ownership and control, source-of-funds explanation, and any context on the flagged exposure (e.g. an inbound transfer you didn’t solicit).
3. Appeals are reviewed within 24–48 hours. Cleared wallets are unblocked immediately and you’re notified by email; upheld declines include the reason and any remaining options.

​

Processor compliance and additional screening

• OFAC / sanctions screening is part of every check: wallets and (during KYB) entities, signers, and beneficial owners are screened against OFAC SDN and equivalent international sanctions lists. Sanctions matches are hard declines and are also subject to regulatory reporting obligations — these cannot be waived by appeal unless the match is a false positive.

​

Next steps