nick/nick-doc
3
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: sync from backend a4d72df - cap confirmation floors

Browse Source
This commit is contained in:
Siavash Sameni
2026-05-31 15:21:28 +04:00
parent 798fa2f48e
commit 9f8cc104c7
9 changed files with 48 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
04 - Flows/Payment Flow - Scanner.md
View File

@@ -6,7 +6,7 @@ created: 2026-05-30
# Payment Flow — AMN Pay Scanner (In-House)
> **Last updated:** 2026-05-31 — documented backend `2.6.81` confirmation persistence for scanner `confirmed` webhooks.
> **Last updated:** 2026-05-31 — documented backend `2.6.82` / scanner `0.1.7` capped accepted confirmation floors.
End-to-end payment flow using the in-house AMN Pay Scanner, replacing the Request Network integration. The scanner is a separate microservice; the backend talks to it over an internal HTTP API.
@@ -61,7 +61,7 @@ Authorization: Bearer <SCANNER_API_KEY>
"amount": "10000000000000000000",
"callbackUrl": "https://api.amn.gg/api/payment/amn-scanner/webhook",
"callbackSecret": "<per-intent HMAC secret stored in payment doc>",
"confirmations": 12
"confirmations": 200
}
```
@@ -93,7 +93,7 @@ The buyer signs and broadcasts the transaction using their wallet. The scanner i
1. `eth_getLogs` returns a `TransferWithReferenceAndFee` log matching `topicRef`
2. `validateLogMatchesIntent` verifies token address, destination, and amount
3. Intent moves to `confirming`; scanner waits for N blocks
4. Once `confirmationsRequired` blocks have been built on top, intent moves to `confirmed`
4. Once `confirmationsRequired` blocks have been built on top, intent moves to `confirmed`. The scanner stores and reports the accepted threshold count, not an ever-growing live count.
**Tron path:**
1. TronGrid `Transfer` event matches `destination` (EVM-hex normalized)
@@ -118,14 +118,14 @@ The scanner POSTs to `callbackUrl` with:
"amount": "10000000000000000000",
"token": "0x55d...",
"chainId": 56,
"confirmations": 12,
"confirmations": 200,
"status": "confirmed"
}
```
Header `X-AMN-Signature` = `HMAC-SHA256(body, callbackSecret)`.
The backend verifies the signature, matches the `intentId` to a Payment record, and marks it paid. Backend `2.6.81+` treats scanner `status: "confirmed"` as final enough to run Transaction Safety Provider checks and persist `blockchain.confirmations`. The stored confirmation count comes from verifier evidence first, then the webhook payload, then the configured per-chain threshold fallback when the scanner has already waited for enough blocks but did not send a raw count.
The backend verifies the signature, matches the `intentId` to a Payment record, and marks it paid. Backend `2.6.82+` treats scanner `status: "confirmed"` as final enough to run Transaction Safety Provider checks and persist `blockchain.confirmations`. The stored confirmation count comes from verifier evidence first, then the webhook payload, then the configured per-chain threshold fallback, but settled counts are capped at the accepted threshold so the UI can show values like `200+` instead of chasing the live chain height forever.
### Step 6 — Backend acknowledges