Crypto limits and authenticated callbacks
Crypto checkout limits: read GET /api/v1/methods before creating a charge. For each live custom-amount method, use its current USD min and max, exact cents, and the exact method/network; the maximum is $25,000. NOWPayments minimums are calculated for the actual pay currency converted into USDT TRC-20, buffered by 10% and rounded up to cents. They are dynamic and shared by app, API and gateway validation, cached for at most five minutes; never hardcode a historical minimum. A method with live=false or temporarily_unavailable=true must not be offered; min=null means no verified quote, not a zero minimum. A lookup outage blocks new checkout creation rather than using an unsafe fallback. The browser refreshes the catalogue each minute; the server revalidates at creation. The requested USD amount and exact payment asset/network stay unchanged; custody conversion is not a change to what the payer must send. NOWPayments callbacks require the matching IPN HMAC-SHA512 signature; an unavailable signing configuration returns retryable HTTP 503, while missing/invalid signatures return 401 without credit. Authenticated provider polling remains a recovery path. Merchant callbacks still use mPay signatures, not the provider IPN secret. Credit verified pending_settlement/available receipts using settled_amount once per charge id; redirects, Waiting invoices and webhook HTTP 200 alone do not prove payment or external wallet credit.
Partial payments and exact amounts
Exact paid amounts: requested_amount is the original invoice. paid_amount is the provider-verified gross receipt, before merchant/provider fees. settled_amount is the captured gross principal eligible for customer-wallet credit, not net merchant proceeds. Uncollected states return settled_amount=0, even if a partial receipt is observed. is_partial=true means less than requested was paid; shortfall_amount is the remaining difference. A $10 invoice with $9 captured returns requested_amount=10, amount=9, paid_amount=9, settled_amount=9, is_partial=true, shortfall_amount=1. There is no new partial status: use pending_settlement/available with these amount fields. Speed underpayments are captured after checkout expiry; a still-open underpayment remains awaiting_customer and must not be credited yet. Match the ORIGINAL requested_amount, charge id, reference and currency to your order, then credit only settled_amount once per charge id in a database transaction. Never require settled_amount to equal the requested invoice, credit amount from the redirect, or credit net. Later payment.succeeded/available does not create another wallet credit. Verify webhook signature over the raw body, deduplicate event_id, and use authenticated GET /api/v1/charges/{id} for reconciliation; a failed delivery or HTTP 200 is not proof that the customer wallet was credited. Existing collected charges receive the new fields on GET; previously emitted events are not silently rewritten.