# ZyndPay

> ZyndPay is a crypto payment gateway that lets merchants accept USDT (TRC20) payments on TRON. It provides a Stripe-like API with hosted checkout pages, webhooks, sandboxing, multi-team support, and a full dashboard.

## Overview

ZyndPay enables businesses to accept USDT TRC20 cryptocurrency payments via a simple REST API. Key capabilities:

- Accept USDT TRC20 payments (payins) with hosted checkout pages at checkout.zyndpay.io
- Create shareable pay links with promo codes, product catalogs, and subscription support
- Send USDT TRC20 payouts to any TRON wallet (third-party vendor payments)
- Withdraw USDT TRC20 balance to your own whitelisted TRON wallet
- Bulk payments — batch payouts via CSV import or API
- Webhook delivery with HMAC-SHA256 signed payloads for real-time payment events
- Full sandbox environment for development and testing
- KYB onboarding, team management, API key scopes, analytics, and dispute management

## Base URL

```
https://api.zyndpay.io/v1
```

## Response Headers

All API responses include `X-ZyndPay-Api-Version: 2026-03-26`.

## Authentication

All API requests require an API key in the `X-Api-Key` header (or `Authorization: Bearer <key>`).

```
X-Api-Key: zyp_live_sk_...
```

API key prefixes:
- `zyp_live_sk_` — Live secret key (full access)
- `zyp_live_pk_` — Live publishable key (read-only, client-safe)
- `zyp_test_sk_` — Sandbox secret key
- `zyp_test_pk_` — Sandbox publishable key
- `zyp_rk_` — Restricted key (custom scopes)

## Quick Start: Accept a Payment

```bash
curl -X POST https://api.zyndpay.io/v1/payments \
  -H "X-Api-Key: zyp_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "externalRef": "order_123",
    "expiresInSeconds": 3600,
    "successUrl": "https://yoursite.com/payment/success",
    "cancelUrl": "https://yoursite.com/payment/cancel"
  }'

# Response includes paymentUrl — redirect your customer there (checkout.zyndpay.io/{id})
# Response also includes address — the TRON wallet to display in your own UI
```

## API Response Shape

All responses follow this envelope:

```json
{
  "success": true,
  "data": { ... },
  "message": "optional string",
  "meta": { "page": 1, "limit": 20, "total": 100, "totalPages": 5, "hasNext": true, "hasPrev": false, "nextCursor": "abc123" }
}
```

Errors:
```json
{
  "success": false,
  "error": {
    "code": "AMOUNT_TOO_LOW",
    "message": "Minimum payin amount is 1 USDT"
  },
  "statusCode": 400
}
```

## Core Endpoints

> **Listing endpoints** support: `page`, `limit`, `status` (comma-separated), `sort=createdAt:desc`, `from` (ISO date), `to` (ISO date), `externalRef`, `cursor` (for cursor-based pagination).

### Payins (Receive Payments from Customers)
- `POST /payments` — Create a payment request
- `GET /payments/:id` — Get payin status
- `GET /payments` — List payins (paginated)

### Paylinks (Shareable Payment Pages)
- `POST /paylinks` — Create a pay link
- `GET /paylinks` — List pay links
- `GET /paylinks/:id` — Get pay link details
- `PATCH /paylinks/:id` — Update pay link
- `DELETE /paylinks/:id` — Delete pay link
- `GET /paylinks/:id/stats` — Get pay link statistics
- `GET /paylinks/dashboard-stats` — Get aggregate paylink stats
- `POST /paylinks/templates` — Create a reusable template
- `GET /paylinks/templates` — List templates
- `DELETE /paylinks/templates/:templateId` — Delete template
- `POST /paylinks/:id/save-as-template` — Save pay link as template
- `POST /paylinks/:id/products/import-csv` — Import products from CSV
- `POST /paylinks/:id/cover-image` — Upload cover image
- `DELETE /paylinks/:id/cover-image` — Remove cover image
- `POST /paylinks/:id/products/:productId/image` — Upload product image
- `POST /paylinks/:id/promo-codes` — Create promo code
- `GET /paylinks/:id/promo-codes` — List promo codes
- `PATCH /paylinks/:id/promo-codes/:codeId` — Update promo code
- `DELETE /paylinks/:id/promo-codes/:codeId` — Delete promo code
- `GET /paylinks/:id/subscriptions` — List subscriptions
- `POST /paylinks/:id/subscriptions/:subscriptionId/cancel` — Cancel subscription
- `GET /paylinks/:id/orders` — List orders
- `GET /paylinks/:id/orders/export` — Export orders as CSV

### Payouts (Send Payments to Third Parties)
- `POST /payout` — Send USDT to a wallet address
- `GET /payout/:id` — Get payout status
- `GET /payout` — List payouts
- `POST /payout/estimate` — Estimate payout cost with fee breakdown

### Withdrawals (Withdraw Balance to Your Own Wallet)
- `POST /withdrawals` — Request a withdrawal from your balance
- `GET /withdrawals/:id` — Get withdrawal status
- `GET /withdrawals` — List withdrawals
- `DELETE /withdrawals/:id` — Cancel a pending withdrawal

### Bulk Payments (Batch Payouts)
- `POST /bulk-payments` — Create a bulk payment batch
- `POST /bulk-payments/:id/items` — Add items to batch
- `POST /bulk-payments/:id/import` — Import items from CSV
- `POST /bulk-payments/:id/validate` — Validate batch before execution
- `POST /bulk-payments/:id/execute` — Execute the batch
- `POST /bulk-payments/:id/retry` — Retry failed payments in batch
- `POST /bulk-payments/:id/cancel` — Cancel batch
- `GET /bulk-payments/template` — Download CSV template
- `GET /bulk-payments` — List batches
- `GET /bulk-payments/:id` — Get batch details
- `GET /bulk-payments/:id/export` — Export batch results

### Transactions (Unified History)
- `GET /transactions` — List all transactions
- `GET /transactions/:id` — Get transaction details
- `GET /transactions/export` — Export as CSV
- `GET /transactions/export/pdf` — Export as PDF

### Wallets & Balances
- `GET /wallets/balance` — Get available and pending balance
- `GET /wallets/whitelist` — List whitelisted withdrawal addresses
- `POST /wallets/whitelist` — Add an address to whitelist
- `DELETE /wallets/whitelist/:id` — Remove address from whitelist
- `PATCH /wallets/whitelist/:id/set-primary` — Set primary withdrawal address

### Webhooks
- `POST /webhooks/endpoints` — Register a webhook endpoint
- `GET /webhooks/endpoints` — List webhook endpoints
- `GET /webhooks/endpoints/:id` — Get webhook endpoint details
- `PATCH /webhooks/endpoints/:id` — Update endpoint
- `DELETE /webhooks/endpoints/:id` — Remove endpoint
- `GET /webhooks/deliveries` — List webhook delivery history
- `POST /webhooks/endpoints/:id/retry/:deliveryId` — Retry a failed delivery
- `POST /webhooks/test` — Send a test webhook event

### Analytics
- `GET /analytics/volume` — Transaction volume over time
- `GET /analytics/fees` — Fee breakdown
- `GET /analytics/summary` — Summary (total volume, count)
- `GET /analytics/revenue` — Revenue analytics
- `GET /analytics/payins` — Payin-specific analytics
- `GET /analytics/conversion-rate` — Payment conversion rate
- `GET /analytics/average-basket` — Average basket size
- `GET /analytics/top-paylinks` — Top performing pay links

### Disputes
- `POST /disputes` — Create a dispute
- `GET /disputes` — List disputes
- `GET /disputes/:id` — Get dispute details
- `POST /disputes/:id/messages` — Post a message on a dispute

### Notifications
- `GET /notifications` — List notifications
- `GET /notifications/unread-count` — Get unread count
- `PATCH /notifications/read-all` — Mark all as read
- `PATCH /notifications/:id/read` — Mark one as read

### Sandbox
- `POST /sandbox/payments/:id/simulate` — Instantly confirm a sandbox payin
- `POST /sandbox/reset` — Reset all sandbox data
- `POST /sandbox/playground/payment` — Create playground payment
- `POST /sandbox/playground/payment/:id/simulate` — Simulate playground payment
- `GET /sandbox/playground/payments` — List playground payments

### Auth & Account
- `POST /auth/register` — Register merchant account
- `POST /auth/login` — Login, receive JWT + refresh cookie
- `POST /auth/logout` — Revoke session
- `POST /auth/refresh` — Refresh access token
- `POST /auth/verify-email` — Verify email address
- `POST /auth/resend-verification` — Resend verification email
- `POST /auth/change-password` — Change password
- `POST /auth/forgot-password` — Request password reset
- `POST /auth/reset-password` — Reset password with token
- `GET /auth/totp/setup` — Setup TOTP 2FA
- `POST /auth/totp/enable` — Enable TOTP 2FA
- `POST /auth/totp/disable` — Disable TOTP 2FA
- `GET /auth/sessions` — List active sessions
- `DELETE /auth/sessions/:id` — Revoke a session

### Merchant Profile
- `GET /merchant/profile` — Get merchant profile
- `PATCH /merchant/profile` — Update profile
- `POST /merchant/request-live-activation` — Request live activation
- `GET /merchant/balances` — Get all currency balances
- `GET /merchant/balances/:currency` — Get balance for a specific currency
- `GET /merchant/onboarding` — Get onboarding progress
- `GET /merchant/compliance-status` — Get compliance verification status
- `GET /merchant/freemium-status` — Get freemium tier status
- `GET /merchant/features` — Get available features
- `GET /merchant/notifications` — Get notification preferences
- `PATCH /merchant/notifications` — Update notification preferences
- `GET /merchant/export-settings` — Get PDF export settings
- `PATCH /merchant/export-settings` — Update PDF export settings
- `GET /merchant/onboarding-checklist` — Get onboarding checklist

### API Key Management
- `POST /api-keys` — Create API key
- `GET /api-keys` — List API keys
- `GET /api-keys/:id` — Get API key details
- `PATCH /api-keys/:id` — Update API key
- `POST /api-keys/:id/rotate` — Rotate key (24h grace period)
- `DELETE /api-keys/:id` — Revoke key

### Team Management
- `GET /team/members` — List team members
- `POST /team/invites` — Invite a team member
- `PATCH /team/members/:id` — Update member role
- `DELETE /team/members/:id` — Remove member
- `POST /team/invites/:id/resend` — Resend invitation
- `GET /team/invite-info` — Get invitation info (public)
- `POST /team/accept-invite` — Accept invitation

### KYB (Know Your Business)
- `GET /kyb/status` — Get KYB verification status
- `POST /kyb/upload` — Upload KYB document (max 10MB)
- `GET /kyb/documents/:id` — Download KYB document
- `POST /kyb/submit` — Submit KYB application

### Support
- `POST /support/chat` — Send support message (authenticated)
- `GET /support/history` — Get conversation history
- `DELETE /support/history` — Clear conversation history
- `POST /support/public-chat` — Public FAQ chat (no auth)
- `GET /support/status` — Get support availability

### Real-Time Events
- `GET /events/stream` — SSE event stream for real-time updates

## Webhooks

ZyndPay sends signed POST requests to your endpoint on payment events.

### Verify Signature

```javascript
const crypto = require('crypto');

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-zyndpay-signature'];
  const [tPart, v1Part] = sig.split(',');
  const timestamp = tPart.split('=')[1];
  const received  = v1Part.split('=')[1];

  // Reject events older than 5 minutes
  const age = Math.abs(Date.now() / 1000 - parseInt(timestamp));
  if (age > 300) return res.status(400).send('Webhook too old');

  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(`${timestamp}.${req.body}`)
    .digest('hex');

  // Use timing-safe comparison to prevent timing attacks
  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
    return res.status(400).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  // Handle event...
  res.json({ received: true });
});
```

### Webhook Events

**Payin events**: payin.created, payin.confirming, payin.confirmed, payin.expired, payin.underpaid, payin.overpaid, payin.failed
**Deposit events**: deposit.confirmed, deposit.overpaid, deposit.underpaid
**Payout events**: payout.broadcast, payout.confirmed, payout.failed
**Withdrawal events**: withdrawal.requested, withdrawal.approved, withdrawal.broadcast, withdrawal.confirmed, withdrawal.failed
**AML events**: aml.flagged
**KYB events**: kyb.approved, kyb.rejected

## Sandbox Testing

```bash
# Create sandbox payin
curl -X POST "https://api.zyndpay.io/v1/payments?sandbox=true" \
  -H "X-Api-Key: zyp_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":"50.00","externalRef":"test_1"}'

# Instantly simulate confirmation
curl -X POST \
  https://api.zyndpay.io/v1/sandbox/payments/{id}/simulate \
  -H "X-Api-Key: zyp_test_sk_..."
```

## Fee Structure

| Operation | Formula |
|-----------|---------|
| Payin | `amount x 1%` (merchant pays commission only) |
| Network fee | $1.00 added to `amountExpected` (paid by customer, covers TRON sweep) |
| Payout | `clamp(amount x 1%, $1.50 min, $5 max)` |
| Withdrawal | `max(amount x 1%, $1.50 min)` |

## SDKs

- **Node.js**: `npm install @zyndpay/sdk`
- **Python**: `pip install zyndpay`
- **PHP**: `composer require zyndpay/zyndpay-php`
- **WooCommerce**: Plugin available for WordPress stores

## Further Documentation

- Full API reference: https://zyndpay.io/docs
- Full LLM reference: https://zyndpay.io/llms-full.txt
- Dashboard: https://dashboard.zyndpay.io
- Support: support@zyndpay.io