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",
    "deviationUsd": "-0.27"
  }
}

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 assetSymbol units. Decimal string. Paid outcomes only.	51.42
assetSymbol	string	Yes	The asset both crypto amounts are denominated in (e.g. USDT). Paid outcomes only.	USDT
deviationUsd	string (decimal)	Yes	Signed USD value of received − expected. Negative = underpaid, positive = overpaid, "0" = exact. Decimal string. Paid outcomes only. For open-amount payments it appears only on MISMATCH, computed against the gateway minimum (amountUsd).	-0.27

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