Getting Started

This guide walks you through setting up PayzCore and creating your first blockchain monitoring request. You'll be up and running in under 5 minutes.

1. Create an Account

Sign up at app.payzcore.com/register.

• Fill in your name, email, and password
• Complete the Turnstile verification
• Accept the Terms of Service
• Check your email and click the verification link
• You'll receive a welcome email once verified

Your account starts on the Free plan (2 projects, 2 wallets, 100 webhooks/day, 500 API calls/day).

2. Create a Project

Navigate to Projects and click Create Project.

• Name: Display name (e.g., "My Store"). A URL-safe slug is auto-generated.
• Webhook URL: Your server endpoint that will receive payment notifications (must be HTTPS in production).
• Address Mode: How addresses are assigned. See Address Modes for details. Default: per_payment.

On success, your credentials are displayed once:

Save these immediately. You cannot retrieve them later. If lost, you can regenerate them from the project settings (admin only).

3. Add a Wallet

Go to Wallets and add your xPub key. PayzCore derives watch-only addresses from it. Your private keys never leave your wallet.

Where to find your xPub:

• Trust Wallet: Settings > Wallets > Info icon > Extended Public Key
• Ledger Live: Account > Advanced Logs > xPub
• Electrum: Wallet > Information > Master Public Key

Each wallet is linked to an address family:

• EVM xPub: Used for BEP20, ERC20, Polygon, Arbitrum (derivation path: m/44'/60'/0'/0/index)
• Tron xPub: Used for TRC20 (derivation path: m/44'/195'/0'/0/index)

HD derivation index 0 is reserved as a gas/fee address. Payment addresses start at index 1. See Sweeping Funds for details.

Verify Your Wallet Setup

This step is critical. Before accepting real payments, always verify your wallet configuration:

1. Check address #0: When adding your xPub in the dashboard, click "Verify Key" to preview derived addresses. Compare address #0 with your wallet app's first receiving address — they must match exactly.
2. Send a test payment: Create a monitoring request for a small amount ($1–5) and send the funds to the assigned address.
3. Verify receipt: Confirm the test funds appear in your wallet app.
4. Test sweeping: Send the test funds back out to confirm you have full control of the derived addresses with your private keys.

4. Create a Monitoring Request

Use the API to create a payment monitoring request:

curl -X POST https://api.payzcore.com/api/v1/payments \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50,
    "chain": "TRC20",
    "token": "USDT",
    "external_ref": "customer-123",
    "metadata": { "order": "ORD-456" }
  }'

Request Parameters

Response

{
  "success": true,
  "payment": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "address": "TXyz...abc",
    "amount": "50.00",
    "chain": "TRC20",
    "token": "USDT",
    "status": "pending",
    "expires_at": "2026-02-20T13:00:00.000Z",
    "qr_code": "data:image/png;base64,iVBOR..."
  }
}

• amount: May differ from request if pool+micro_amount mode adds a micro-offset
• qr_code: Base64 PNG of the wallet address (not amount-encoded). Show this to your customer for easy scanning.
• expires_at: After this time, the payment status changes to expired if unpaid.

Idempotency

If you provide external_order_id, creating a payment with the same (external_order_id, external_ref, chain, token) returns the existing payment instead of creating a duplicate. The response includes "existing": true.

Error Responses

{
  "error": "Description of the error"
}

5. Check Payment Status

Poll the payment status (or wait for a webhook):

curl https://api.payzcore.com/api/v1/payments/PAYMENT_ID \
  -H "x-api-key: pk_live_YOUR_KEY"

{
  "success": true,
  "payment": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "paid",
    "expected_amount": "50.00",
    "paid_amount": "50.00",
    "address": "TXyz...abc",
    "chain": "TRC20",
    "token": "USDT",
    "tx_hash": "abc123def...",
    "expires_at": "2026-02-20T13:00:00.000Z",
    "transactions": [
      {
        "tx_hash": "abc123def...",
        "amount": "50.00",
        "from": "TSender...xyz",
        "confirmed": true,
        "confirmations": 21
      }
    ]
  }
}

Payment Statuses

Overpaid threshold: A payment is marked overpaid when the received amount exceeds expectedAmount * 1.01. For example, $50 expected + $50.60 received = overpaid. This is to distinguish intentional overpayments from rounding.

6. Handle Webhooks

When a transfer is detected and confirmed, PayzCore sends a POST request to your webhook URL. See the Webhooks Guide for full details on events, headers, signature verification, and retry logic.

Quick verification example:

import { createHmac, timingSafeEqual } from 'crypto';

function verify(body: string, signature: string, secret: string): boolean {
  const expected = createHmac('sha256', secret).update(body).digest('hex');
  return timingSafeEqual(
    Buffer.from(signature.toLowerCase()),
    Buffer.from(expected)
  );
}

// signature = request.headers['x-payzcore-signature']

Next Steps

• Authentication & API Keys - API key setup, headers, credential management
• Supported Chains & Tokens - Available chains, tokens, and confirmation thresholds
• Address Modes - Choose the right address strategy for your use case
• Webhooks Guide - Full webhook documentation with retry logic
• Rate Limits & Plans - Free/Pro limits, daily quotas, upgrading
• Error Reference - HTTP status codes and error handling
• Sweeping Funds - How to collect received funds
• FAQ & Troubleshooting - Common questions and solutions
• Node.js SDK - Use the official SDK instead of raw HTTP calls
• API Reference - Complete interactive API documentation