API Documentation

0 AI Agent Integration Prompt

Choose a prompt that matches the model's context and reasoning capacity

The full prompt gives large coding models the complete architecture. The compact prompt gives 5B-8B models one constrained implementation path so security rules remain visible throughout the task.

# PayCow Non-Custodial Crypto Payment Gateway
## Master AI Coding Agent Integration Blueprint

[Role & Directive for the AI Agent]
You are acting as the Principal Web3 & Payment Integration Architect. Integrate PayCow's Non-Custodial crypto payment gateway cleanly and securely.

PayCow is a Non-Custodial payment infrastructure:
- Monitors on-chain deposits and settles directly into merchant wallets
- Never holds private keys or custody of funds
- All API calls over HTTPS (https://paycow.net)
- Supports USDT on Ethereum (ERC-20) and TRON (TRC-20)

Create Payment: POST https://paycow.net/api/payment/create
  Headers: x-api-key, x-api-secret, Idempotency-Key
  Body: { "amount": 50.00, "userId": "...", "network": "TRC20" }

Verify Payment (Pull): GET https://paycow.net/payment/data/:sessionId (public)
Verify Payment (Push): signed server-to-server webhooks

Webhook Setup:
1. Build a public HTTPS POST receiver that preserves the exact raw body.
2. Verify PayCow-Timestamp and PayCow-Signature using HMAC-SHA256.
3. Store event.id with a unique constraint and fulfill payment.paid exactly once.
4. Dashboard → Developer → Webhooks → save URL and copy the one-time whsec_ secret.
5. Send a test webhook and confirm a 2xx result in Delivery History.

Signature input: timestamp + "." + rawBody
Headers: PayCow-Event-Id, PayCow-Timestamp, PayCow-Signature

# PayCow Compact Safe Integration Prompt

For small coding models (5B-8B).

Inspect the repository first. Keep the change small. Do not invent endpoints, fields, statuses, or event types.

Security rules:
- Keep every PayCow credential on the backend.
- Derive amount from trusted database data.
- Send a stable Idempotency-Key.
- Verify HMAC-SHA256 over timestamp + "." + exact rawBody.
- Store event.id under a unique database index.
- Fulfill only signed payment.paid events with PAID status.
- Make fulfillment atomic and exactly once.
- Never fulfill from browser polling or webhook.test.

Build order: database → backend service → checkout route → raw webhook receiver → dashboard test → focused security tests.

1 Overview

Understand how PayCow works at a high level

PayCow provides a non-custodial RESTful API and Webhook event system to generate and monitor cryptocurrency payment sessions. Your backend initiates a payment session and redirects the customer to our hosted checkout, which handles real-time blockchain monitoring automatically.

Supported Settlement Networks

Integration Flow

1. Merchant Server  -->  POST /api/payment/create (amount, userId, network)
2. PayCow Server    -->  Returns { sessionId, paymentUrl, depositAddress, payableAmount }
3. Customer         -->  Redirected to paymentUrl
4. PayCow Engine    -->  Monitors blockchain and confirms transaction
5. State Update     -->  PUSH: Webhook POST to merchant URL
                         PULL: Merchant polls GET /payment/data/:id

2 Authentication

Secure your API requests with merchant credentials

Authenticated API requests require your merchant API Key and API Secret passed as custom HTTP headers. Retrieve these from your merchant profile dashboard at /dashboard.

x-api-key: your_api_key_here
x-api-secret: your_api_secret_here

3 Error Handling

Understand HTTP status codes and error response format

PayCow uses standard HTTP status codes. Error responses return a JSON object with a descriptive msg or error field.

4 Create Payment Session

Generate a non-custodial payment session and hosted checkout URL

curl -X POST https://paycow.net/api/payment/create \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -H "Idempotency-Key: order_tron_847291" \
  -d '{
    "amount": 50.00,
    "userId": "user_123456",
    "network": "TRC20"
  }'

{
  "sessionId": "648f3a8b1c2d3e4f5a6b7c8d",
  "paymentUrl": "https://paycow.net/payment/648f3a8b1c2d3e4f5a6b7c8d",
  "paymentReference": "a1b2c3d4e5f6a7b8",
  "amountRequested": 50.00,
  "payableAmount": 50.0001,
  "amount": 50.0001,
  "depositAddress": "TJY5Pj6xWkP7mNQ7w9u8z1v2y3x4w5e6r7",
  "addressSerialNo": "WAL-1002",
  "expiresAt": "2026-03-12T22:30:00.000Z"
}

5 Payment Lifecycle

Deterministic state transitions during a payment session

• PENDING Session active. Awaiting customer deposit on-chain.
• DETECTED Deposit transaction detected in blockchain mempool.
• CONFIRMING Accumulating block confirmations (12 for ERC-20, solidified for TRC-20).
• PAID Confirmed and settled directly into merchant wallet. Fulfill order.
• EXPIRED 30-minute window elapsed without a valid deposit.
• REJECTED Rejected by merchant operator or invalidated on-chain.

6 Polling & Status Queries

Pull architecture -- query payment status on demand

curl https://paycow.net/payment/data/648f3a8b1c2d3e4f5a6b7c8d

{
  "_id": "648f3a8b1c2d3e4f5a6b7c8d",
  "userId": "user_123456",
  "baseAmount": 50.00,
  "payableAmount": 50.0001,
  "amountRequested": 50.00,
  "amountReceived": 50.0001,
  "currencyInfo": "USDT",
  "depositNetwork": "TRC20",
  "status": "PAID",
  "confirmations": 20,
  "txHash": "9e1c7f4a2b3d8e5f...",
  "isAwake": false,
  "awakeExpiresAt": null
}

curl -X GET https://paycow.net/api/payment/status/648f3a8b1c2d3e4f5a6b7c8d \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET"

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 / REJECTED state, it is immediately revived back to PENDING so TRC-20 and ERC-20 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.

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": 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
}

7 Webhooks & Real-Time Notifications

Push architecture -- receive instant HTTP POST notifications on state changes

Setting Up Webhooks

1. Implement and deploy a public HTTPS POST receiver before registering it. The route must preserve the exact raw request body.
2. Log into the PayCow Dashboard and open Developer → Webhooks.
3. Enter the final receiver URL and click Save Changes. Saving a URL enables live event delivery.
4. Copy the newly generated HMAC-SHA256 Signing Secret (whsec_...) immediately to a backend-only PAYCOW_WEBHOOK_SECRET environment variable.
5. Click Send Test Webhook, return HTTP 2xx, and confirm the result in Webhook Delivery History.

8 Event Types & Payload

Webhook events fired on on-chain state transitions

Standard Payload

{
  "id": "evt_01k4xyz123abc987",
  "type": "payment.paid",
  "apiVersion": "2026-09-01",
  "createdAt": "2026-09-09T12:45:31.124Z",
  "data": {
    "sessionId": "648f3a8b1c2d3e4f5a6b7c8d",
    "paymentReference": "a1b2c3d4e5f6a7b8",
    "userId": "order_84920",
    "status": "PAID",
    "amountRequested": 50,
    "payableAmount": 50.0001,
    "amountReceived": 50.0001,
    "currency": "USDT",
    "network": "TRC20",
    "depositAddress": "TJY5TestDepositAddress12345",
    "txHash": "9e1c7f4a5b6c7d8e...",
    "confirmations": 20
  }
}

Dashboard Test Payload

{
  "id": "evt_01k4test123abc987",
  "type": "webhook.test",
  "apiVersion": "2026-09-01",
  "createdAt": "2026-09-23T12:45:31.124Z",
  "data": {
    "message": "PayCow webhook test event"
  }
}

9 Signature Verification

Verify webhook authenticity with HMAC-SHA256

Verification Implementation

import crypto from 'node:crypto';

function verifyPayCowWebhook({ rawBody, timestamp, signature, secret, toleranceSeconds = 300 }) {
  if (!Buffer.isBuffer(rawBody) || !timestamp || !signature || !secret) return false;

  const timestampNumber = Number(timestamp);
  if (!Number.isInteger(timestampNumber)) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - timestampNumber) > toleranceSeconds) return false;
  if (!/^v1=[a-fA-F0-9]{64}$/.test(String(signature))) return false;

  const signedPayload = Buffer.concat([Buffer.from(`${timestamp}.`, 'utf8'), rawBody]);
  const expectedHex = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex');
  const receivedHex = String(signature).slice(3);
  const expected = Buffer.from(expectedHex, 'hex');
  const received = Buffer.from(receivedHex, 'hex');

  return expected.length === received.length && crypto.timingSafeEqual(expected, received);
}

import hmac, hashlib, re, time

def verify_paycow_webhook(raw_body: bytes, timestamp: str, signature: str, secret: str, tolerance=300) -> bool:
    try:
        if not re.fullmatch(r"v1=[a-fA-F0-9]{64}", signature or ""):
            return False
        if abs(int(time.time()) - int(timestamp)) > tolerance:
            return False
        signed = f"{timestamp}.".encode() + raw_body
        expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
        return hmac.compare_digest(expected, signature[3:])
    except Exception:
        return False

<?php
function verifyPayCowWebhook($rawBody, $timestamp, $signature, $secret, $tolerance = 300) {
    if (!preg_match('/^v1=[a-fA-F0-9]{64}$/', $signature ?? '')) return false;
    if (abs(time() - intval($timestamp)) > $tolerance) return false;
    $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
    return hash_equals($expected, substr($signature, 3));
}

Express Receiver Placement

Register the raw webhook route before the application's global JSON parser. Replace acceptWebhookEventIdempotently with a database transaction that uniquely stores event.id and applies payment.paid fulfillment once.

app.post('/webhooks/paycow', express.raw({ type: 'application/json', limit: '256kb' }), async (req, res) => {
  const timestamp = req.get('PayCow-Timestamp');
  const signature = req.get('PayCow-Signature');

  if (!verifyPayCowWebhook({
    rawBody: req.body,
    timestamp,
    signature,
    secret: process.env.PAYCOW_WEBHOOK_SECRET
  })) return res.sendStatus(401);

  let event;
  try {
    event = JSON.parse(req.body.toString('utf8'));
  } catch {
    return res.sendStatus(400);
  }

  if (event.id !== req.get('PayCow-Event-Id')) return res.sendStatus(400);
  await acceptWebhookEventIdempotently(event);
  return res.sendStatus(200);
});

app.use(express.json());

10 Retries & Security

At-least-once delivery, exponential backoff, and SSRF protection

Retry Schedule

SSRF Protection

• HTTPS Only -- HTTP rejected in production
• Private IP Blocked -- 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8
• DNS Validation -- Destination hostnames are resolved and checked against prohibited address ranges
• No Redirects -- Delivery does not follow 301/302 redirect responses

11 Best Practices

Architecture recommendations for production integrations

• Webhooks as Primary, Polling as Backup: Process orders via webhooks; run a cron job with GET /api/payment/status/:id as fallback.
• Store Credentials Securely: Keep x-api-secret and webhook secrets in server-side environment variables only.
• Always Pass Idempotency-Key: Use a unique order UUID in every POST /api/payment/create request.

12 Code Examples

Create payment sessions in your preferred language

const response = await fetch('https://paycow.net/api/payment/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.PAYCOW_API_KEY,
    'x-api-secret': process.env.PAYCOW_API_SECRET,
    'Idempotency-Key': `order_${order.id}`,
  },
  body: JSON.stringify({
    amount: 50.00,
    userId: 'user_123456',
    network: 'TRC20',
  }),
});

const data = await response.json();
res.redirect(data.paymentUrl);

import requests, os

response = requests.post("https://paycow.net/api/payment/create",
    json={"amount": 50.00, "userId": "user_123456", "network": "TRC20"},
    headers={
        "Content-Type": "application/json",
        "x-api-key": os.getenv("PAYCOW_API_KEY"),
        "x-api-secret": os.getenv("PAYCOW_API_SECRET"),
        "Idempotency-Key": "order_847291"
    })
payment_url = response.json().get("paymentUrl")

data := map[string]interface{}{
    "amount": 50.00, "userId": "user_123456", "network": "TRC20",
}
jsonData, _ := json.Marshal(data)

req, _ := http.NewRequest("POST", "https://paycow.net/api/payment/create",
    bytes.NewBuffer(jsonData))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("x-api-key", os.Getenv("PAYCOW_API_KEY"))
req.Header.Set("x-api-secret", os.Getenv("PAYCOW_API_SECRET"))

resp, _ := (&http.Client{}).Do(req)

$ch = curl_init('https://paycow.net/api/payment/create');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'amount' => 50.00, 'userId' => $user_id, 'network' => 'TRC20'
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'x-api-key: ' . getenv('PAYCOW_API_KEY'),
    'x-api-secret: ' . getenv('PAYCOW_API_SECRET'),
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = json_decode(curl_exec($ch), true);
header('Location: ' . $result['paymentUrl']);

var client = new HttpClient();
var data = new { amount = 50.00, userId = "user_123456", network = "TRC20" };
var content = new StringContent(JsonSerializer.Serialize(data), Encoding.UTF8, "application/json");

client.DefaultRequestHeaders.Add("x-api-key", Environment.GetEnvironmentVariable("PAYCOW_API_KEY"));
client.DefaultRequestHeaders.Add("x-api-secret", Environment.GetEnvironmentVariable("PAYCOW_API_SECRET"));

var response = await client.PostAsync("https://paycow.net/api/payment/create", content);

let client = reqwest::Client::new();
let mut headers = HeaderMap::new();
headers.insert("x-api-key", HeaderValue::from_str(&std::env::var("PAYCOW_API_KEY")?)?);
headers.insert("x-api-secret", HeaderValue::from_str(&std::env::var("PAYCOW_API_SECRET")?)?);

let res = client.post("https://paycow.net/api/payment/create")
    .headers(headers)
    .json(&json!({"amount": 50.0, "userId": "user_1", "network": "TRC20"}))
    .send().await?.json::<serde_json::Value>().await?;

println!("URL: {}", res["paymentUrl"]);

WooCommerce Payment Gateway

Official Non-Custodial USDT Gateway Plugin for WordPress & WooCommerce

Accept direct, non-custodial USDT (TRC-20 & ERC-20) payments on your WooCommerce store with 0% gateway commission. Customer transfers settle directly to your self-custody wallet addresses with real-time on-chain confirmation.

Installation & Setup Guide

1. Download & Upload: Download paycow-crypto-payment-gateway.zip and upload it in your WordPress admin via Plugins → Add New → Upload Plugin, then click Activate.
2. Configure Credentials: Navigate to WooCommerce → Settings → Payments → PayCow Non-Custodial Crypto Gateway. Enter your PayCow Merchant API Key and API Secret from your dashboard (Developer → API Keys).
3. Setup Webhooks: Copy your store's unique Webhook Delivery URL shown at the bottom of the PayCow settings screen (e.g. https://example.com/?wc-api=paycow_webhook), paste it into your PayCow Dashboard under Developer → Webhooks, and save your generated HMAC-SHA256 Signing Secret (whsec_...) back into WooCommerce.

WHMCS Payment Gateway

Official Non-Custodial USDT Gateway Module for WHMCS Web Hosts & SaaS Providers

Accept direct, non-custodial USDT (TRC20 & ERC20) payments in WHMCS. Payments settle directly on-chain into your merchant vault address with automatic invoice reconciliation powered by the official PayCow PHP SDK.

Quick Setup

1. Extract Files: Unpack paycow-whmcs-payment-gateway.zip directly into your root WHMCS directory. Module files will automatically populate modules/gateways/paycow.php, modules/gateways/callback/paycow.php, and modules/gateways/paycow/sdk/.
2. Activate in WHMCS: Navigate to Configuration → System Settings → Payment Gateways → All Payment Gateways, locate PayCow Non-Custodial Crypto, and click Activate.
3. Configure API Keys: Enter your API Key, API Secret, and Webhook Secret from your PayCow dashboard.
4. Set Webhook URL: Copy the callback URL displayed in the gateway instructions (https://example.com/modules/gateways/callback/paycow.php) and save it in your PayCow Dashboard under Webhook Settings.

Official PHP SDK

Official Zero-Dependency PHP Client for PayCow Non-Custodial Infrastructure

Integrate PayCow directly into custom PHP applications, web frameworks (Laravel, Symfony), and billing systems with paycow/paycow-php-sdk. Features zero external dependencies, pure decimal string arithmetic to eliminate rounding drift, and timing-safe HMAC-SHA256 signature verification.

Installation Options

Standalone PSR-4 Autoloader

<?php
require_once __DIR__ . '/paycow-php-sdk/autoload.php';

use PayCow\PayCowClient;

$client = new PayCowClient([
    'api_key' => getenv('PAYCOW_API_KEY'),
    'api_secret' => getenv('PAYCOW_API_SECRET'),
]);

JavaScript SDK

Server-side Node.js client with TypeScript declarations

The JavaScript SDK creates payment sessions, retrieves authenticated payment status, and verifies PayCow webhook signatures. It requires Node.js 18 or newer and has no runtime dependencies.

npm install ./paycow-javascript-sdk

const { PayCowClient } = require('@paycow/sdk');

const paycow = new PayCowClient({
  apiKey: process.env.PAYCOW_API_KEY,
  apiSecret: process.env.PAYCOW_API_SECRET
});

const payment = await paycow.createPayment({
  userId: 'customer-2048',
  amount: '50.00',
  network: 'TRC20',
  idempotencyKey: 'order-2048-001'
});

Java SDK

Typed Java 17 client with BigDecimal payment values

The Java SDK uses Java HttpClient for API requests and Jackson for response mapping. It exposes typed payment session and status records together with HMAC-SHA256 webhook verification.

cd paycow-java-sdk
mvn clean install

PayCowClient paycow = new PayCowClient(
    System.getenv("PAYCOW_API_KEY"),
    System.getenv("PAYCOW_API_SECRET")
);

CreatePaymentRequest request = CreatePaymentRequest.builder()
    .userId("customer-2048")
    .amount(new BigDecimal("50.00"))
    .network("TRC20")
    .idempotencyKey("order-2048-001")
    .build();

PaymentSession payment = paycow.createPayment(request);