POST /payments/{id}/verify

Returns the authoritative outcome of a payment and marks it as verified by your server. This is the only response that carries the money figures — the callback and webhook are thin triggers. Concepts and the recommended flow: Verify Payments.

curl -X POST https://api-staging.finomesh.com/api/v1/payments/0d9f3a64-4f0c-4b6e-9f6e-2f4f4c1b8a21/verify \
  -H "X-Api-Key: $FINOMESH_API_KEY"

Headers

Header	Type	Required	Description	Example
X-Api-Key	string	Yes	Gateway API key. Keep it server-side only.	<your-api-key>

Path parameters

Parameter	Type	Required	Description	Example
id	string (UUID)	Yes	The payment UUID from create payment. Must belong to your gateway.	0d9f3a64-4f0c-4b6e-9f6e-2f4f4c1b8a21

Request body: None.

Response — 200 OK

{
  "success": true,
  "data": {
    "paymentId": "0d9f3a64-4f0c-4b6e-9f6e-2f4f4c1b8a21",
    "status": "ACCEPTABLE",
    "checkoutMode": "HOSTED",
    "isVerified": true,
    "verifiedAt": "2026-06-12T10:21:43Z",
    "amount": "49.99",
    "currencyCode": "USD",
    "amountUsd": "49.99",
    "txHash": "0xabc…",
    "expectedAmount": "51.69",
    "receivedAmount": "51.42",
    "assetSymbol": "USDT",
    "receivedAssetId": "293a335d-99e9-44dc-89d1-17d27ce7fe35",
    "receivedAssetSymbol": "USDT",
    "receivedAmountUsd": "51.42",
    "deviationUsd": "-0.27",
    "depositPath": "scanner"
  }
}

Field	Type	Nullable	Description	Example
paymentId	string (UUID)	No	The payment UUID.	0d9f3a64-…
status	string (enum)	No	The verdict — one of PENDING, SUCCESS, ACCEPTABLE, MISMATCH, EXPIRED. Fulfil on SUCCESS / ACCEPTABLE.	ACCEPTABLE
checkoutMode	string (enum)	No	How the payment was integrated — HOSTED or API (see Embedded Checkout / API Mode).	HOSTED
isVerified	boolean	No	true once a determined payment has been verified. Stays false for PENDING.	true
verifiedAt	string (RFC 3339)	Yes	Timestamp of the first verification. Present once verified; omitted while PENDING.	2026-06-12T10:21:43Z
amount	string (decimal)	No	Your invoice amount in currencyCode units. Decimal string — never a number, to preserve precision.	49.99
currencyCode	string	Yes	The invoice currency ISO code (e.g. USD). Omitted if unresolved.	USD
amountUsd	string (decimal)	No	Your invoice amount converted to USD. Decimal string — never a number.	49.99
openAmount	boolean	No	true for an open-amount payment — one created with no fixed amount, where the payer chooses what to send. For these, amount / amountUsd are 0 until the deposit confirms, then back-filled: what actually arrived on SUCCESS, or the gateway minimum (the expected amount) on MISMATCH. expectedAmount is always absent (nothing was quoted per-offer); deviationUsd appears only on MISMATCH — the signed shortfall against the minimum, e.g. "-2" for $8 received of a $10 minimum. Open-amount is only available to specifically-provisioned gateways; if you have not arranged it, this is always false.	false
txHash	string	Yes	The resolving on-chain transaction hash. Paid outcomes only.	0xabc…
expectedAmount	string (decimal)	Yes	The crypto amount the customer was quoted (the paid offer's totalValue), in assetSymbol units. Decimal string. Paid outcomes only, and absent for open-amount payments — they were never quoted.	51.69
receivedAmount	string (decimal)	Yes	What actually arrived on-chain, in receivedAssetSymbol units (normally the same as assetSymbol — see below). Decimal string. Paid outcomes only.	51.42
assetSymbol	string	Yes	The asset the customer was quoted in — expectedAmount is denominated in it (e.g. USDT). Paid outcomes only.	USDT
receivedAssetId	string (UUID)	Yes	The asset the deposit actually arrived in. Normally the quoted asset; it differs when the customer paid in a different asset than they selected (e.g. sent native TRX to a USDT address) — the deposit is then valued at the received asset's own market price and judged in USD, and receivedAmount is denominated in this asset, not assetSymbol. Paid outcomes only.	293a335d-…
receivedAssetSymbol	string	Yes	Symbol of receivedAssetId (e.g. TRX). Compare it with assetSymbol: when they differ, do not compare receivedAmount to expectedAmount unit-for-unit — use receivedAmountUsd / deviationUsd, which are always computed in USD from the actual valuation. Paid outcomes only.	USDT
receivedAmountUsd	string (decimal)	Yes	receivedAmount valued in USD at the received asset's market price, quantised to cents. The direct USD equivalent of what arrived — e.g. a 30 TRX deposit against a 15 USDT quote reports "10", not "30". Compare it to amountUsd for a unit-safe check in any asset situation. Present alongside deviationUsd (same availability).	51.42
deviationUsd	string (decimal)	Yes	Signed USD value of received − expected. Negative = underpaid, positive = overpaid, "0" = exact. Decimal string. Paid outcomes only. Always safe to branch on — including when the received asset differs from the quoted one. For open-amount payments it appears only on MISMATCH, computed against the gateway minimum (amountUsd).	-0.27
depositPath	string (enum)	Yes	How the deposit reached us: scanner (paid inside the payment window — the ordinary case), late_confirmation (paid inside the window, confirmed after it closed), late_capture (paid after the window and credited anyway — see Payment Statuses), or manual_inquiry (matched from a transaction hash submitted after the fact). Present once a deposit has been recorded. You do not need to branch on it to fulfil — status remains the decision; it explains a payment that resolved after expiring.	scanner
amlState	string (enum)	Yes	AML disposition, AML-screened gateways only — omitted on every payment screening never flagged. HELD: funds are in your held balance (totalQuarantined* on balances), excluded from totalAvailable until you cash them out. RELEASED: paid to you (drained or released by an operator). REFUNDED: returned to the customer. WITHHELD: seized.	HELD
isQuarantined	boolean	Yes	true while the funds sit in the held pool (amlState: "HELD"). Omitted when false.	true

"Paid outcomes" = SUCCESS, ACCEPTABLE, MISMATCH — those fields appear together once a resolving transaction exists, and are omitted for PENDING / EXPIRED.

Behavior

• Idempotent — safe to call repeatedly; you always get the current authoritative state.
• PENDING is a no-op — the response reports PENDING with isVerified: false; nothing is marked.
• Quiets the webhook — verifying a payment causes any still-undelivered webhook for it to be skipped.
• Ownership-scoped — 404 not_found for unknown IDs and for payments of other gateways.

Errors

HTTP status	Error code	Meaning	How to fix
401	auth_api_key_invalid	Bad or missing API key.	Send a valid X-Api-Key from a verified gateway.
404	not_found	Unknown ID, or the payment belongs to another gateway.	Check the payment ID — it must belong to your gateway.