PAYCOW / DOCUMENTATION
Awake & disputes
Create, track and reconcile payments safely.
Underpayment & Dispute Resolution ("Awake Mode")
Automated 72-hour session extension and merchant alerting for fractional shortfalls
A frequent pain point in non-custodial crypto payments is customer underpayment caused by centralized exchange (CEX) withdrawal fee deductions (e.g. Binance, OKX, Bybit deducting 0.30 - 0.40 USDT or 1 USDT directly from the principal withdrawal) or minor fractional discrepancies (e.g. 0.0003 USDT short). In standard gateways, the session expires in 15-30 minutes, risking lost customer funds and merchant overhead.
PayCow solves this natively through the 72-Hour "Awake Mode" Engine. When a customer or checkout widget reports a shortfall:
- 72-Hour Lifespan Extension: The payment session expiration (
expiresAt) is extended by 3 full days (72 hours). - On-Chain Worker Reactivation: If the session had previously timed out or entered
EXPIRED/REJECTEDstate, it is immediately revived back toPENDING(when its reserved amount is still free) so the TRC-20 and EVM listener daemons keep polling for incoming blockchain deposits. - Immunity to Auto-Expiry Cron: The background auto-expiry worker ignores the session throughout its 72-hour window.
- Automated Merchant SMTP Alert: A comprehensive notification email is dispatched in English directly to the merchant's registered inbox with shortfall breakdown, blockchain explorer links, and customer proof.
POST
/api/dispute/submit
Public & Anti-Spam Protected: Can be called directly from checkout widgets, client interfaces, or support bots using either
multipart/form-data (with file upload) or standard JSON. To protect merchants from fraudulent claims, PayCow performs strict on-chain validation of the transaction hash and sender address across Ethereum (ERC-20) and TRON (TRC-20) networks before accepting the dispute.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| sessionId required* | string | Payment session MongoDB ID (or provide paymentReference) |
| paymentReference required* | string | PayCow unique payment reference (or provide sessionId) |
| txHash required | string | Broadcasted blockchain transaction hash (TxID). Verified directly on-chain against the invoice deposit address |
| senderAddress required | string | Sender wallet or exchange account address from which the USDT transfer originated |
| amountPaid required | number | Transferred amount in USDT (cross-verified against on-chain transaction logs) |
| reason required | string | Detailed customer explanation of the shortfall (minimum 10 characters) |
| issueType optional | string | Category: exchange_fee_deduction, network_fee_shortfall, fractional_underpayment, wrong_amount_sent, or other (default: exchange_fee_deduction) |
| contactInfo optional | string | Customer email address or Telegram handle for merchant resolution |
| screenshot optional | file | Receipt screenshot or transfer proof (JPEG, PNG, WEBP, or PDF; max 10MB) |
cURL Example (Form Data with Screenshot)
curl -X POST https://paycow.net/api/dispute/submit \ -F "sessionId=648f3a8b1c2d3e4f5a6b7c8d" \ -F "txHash=0xf6f1e72ae1c1a05b140ea54923eebc28e3bca0438b7f289b34478782ef1468b2" \ -F "senderAddress=0xBdb3ba9ffe392549E1f8658DD2630c141fDF47B6" \ -F "amountPaid=49.65" \ -F "issueType=exchange_fee_deduction" \ -F "[email protected]" \ -F "reason=Exchange deducted withdrawal fee from transfer. Please verify on-chain TxID." \ -F "screenshot=@/path/to/withdrawal_proof.png"
Success Response 201 Created
{
"success": true,
"msg": "Dispute verified on-chain! 72-Hour Awake Mode is now active, and the merchant has been notified via email.",
"isAwake": true,
"awakeExpiresAt": "2026-03-15T22:30:00.000Z",
"verifiedOnChain": true,
"txHash": "0xf6f1e72ae1c1a05b140ea54923eebc28e3bca0438b7f289b34478782ef1468b2",
"network": "ERC20",
"onChainAmount": 49.65,
"onChainSender": "0xBdb3ba9ffe392549E1f8658DD2630c141fDF47B6",
"shortfallAmount": 0.35,
"emailDispatched": true
}
Non-Custodial Merchant Fulfillment: Because PayCow never holds merchant funds, the on-chain transfer lands directly in your destination wallet. When Awake Mode alerts you of a shortfall, you can review the on-chain explorer link, confirm receipt of the partial payment, and choose to manually credit the invoice in your billing system or request the remaining delta.