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:

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

ParameterTypeDescription
sessionId required*stringPayment session MongoDB ID (or provide paymentReference)
paymentReference required*stringPayCow unique payment reference (or provide sessionId)
txHash requiredstringBroadcasted blockchain transaction hash (TxID). Verified directly on-chain against the invoice deposit address
senderAddress requiredstringSender wallet or exchange account address from which the USDT transfer originated
amountPaid requirednumberTransferred amount in USDT (cross-verified against on-chain transaction logs)
reason requiredstringDetailed customer explanation of the shortfall (minimum 10 characters)
issueType optionalstringCategory: exchange_fee_deduction, network_fee_shortfall, fractional_underpayment, wrong_amount_sent, or other (default: exchange_fee_deduction)
contactInfo optionalstringCustomer email address or Telegram handle for merchant resolution
screenshot optionalfileReceipt 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.