Quick Start#

Get started with PayWatcher in under 15 minutes. This guide walks you through creating your first payment intent, receiving USDC, and handling the confirmation webhook.

1. Get Your API Key#

To use the PayWatcher API, you need an API key. Request access through our Request Access form — it's free.

Your API key follows the format mms_paywatcher_... and is displayed in the Dashboard under Settings → API Keys. Include it in every request as the x-api-key header.

Non-Custodial: PayWatcher never holds your funds. When you onboard, you provide your own wallet address. Payments from your customers are sent directly to that address — PayWatcher only monitors the blockchain and notifies you via webhook.

2. Create a Payment Intent#

Create a payment intent by sending a POST request to /v1/payments. This tells PayWatcher how much USDC you expect to receive.

bash

curl -X POST https://api.masem.at/v1/payments \
  -H "x-api-key: mms_paywatcher_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "49.00",
    "currency": "USDC",
    "chain": "base",
    "metadata": {
      "order_id": "ORD-123",
      "customer": "john@example.com"
    },
    "expires_in": 3600
  }'

The API returns a payment object with a depositAddress and a unique exactAmount:

json

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "amount": "49.00",
    "exactAmount": "49.000042",
    "status": "pending",
    "depositAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
    "currency": "USDC",
    "chain": "base",
    "confirmations": 0,
    "confirmationsRequired": 6,
    "txHash": null,
    "metadata": {
      "order_id": "ORD-123",
      "customer": "john@example.com"
    },
    "expiresAt": "2026-01-15T11:00:00Z",
    "createdAt": "2026-01-15T10:00:00Z",
    "updatedAt": "2026-01-15T10:00:00Z"
  }
}

3. Customer Sends USDC#

Display the depositAddress and exactAmount to your customer. They send exactly that amount of USDC on the Base network.

PayWatcher uses a Shared Address + Unique Amount pattern. Each payment gets a unique exactAmount (e.g. 49.000042 instead of 49.00). The last digits identify the payment — your customer must send the exact amount shown.

PayWatcher monitors the blockchain and updates the payment status automatically:

bash

pending ──→ matched ──→ confirming ──→ confirmed
  ├──→ expired (after expiresAt)
  └──→ failed (transaction error)

pending — Waiting for the customer to send USDC
matched — Transaction detected on-chain
confirming — Waiting for block confirmations (default: 6)
confirmed — Payment confirmed, webhook sent

4. Receive Webhook#

Once the payment reaches the required confirmations, PayWatcher sends a payment.confirmed event to your configured webhook URL:

json

{
  "event": "payment.confirmed",
  "timestamp": "2026-01-15T10:05:00Z",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "amount": "49.00",
    "exactAmount": "49.000042",
    "status": "confirmed",
    "txHash": "0x7a3f9c2e1d4b5a6f8e0c3d2b1a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1",
    "depositAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
    "confirmations": 6,
    "confirmationsRequired": 6,
    "currency": "USDC",
    "chain": "base",
    "metadata": {
      "order_id": "ORD-123",
      "customer": "john@example.com"
    },
    "expiresAt": "2026-01-15T11:00:00Z",
    "createdAt": "2026-01-15T10:00:00Z",
    "updatedAt": "2026-01-15T10:05:00Z"
  }
}

Configure your webhook URL in the Dashboard under Settings → Webhook URL, or set it per-payment using the webhook_url field in the create payment request.

PayWatcher signs every webhook with an HMAC signature in the x-paywatcher-signature header. Verify this signature before processing events to ensure authenticity. See Webhooks for verification details.

Next Steps#

Endpoints — Full API reference with all endpoints, parameters, and response schemas
Webhooks — Webhook events, retry logic, and signature verification
Examples — Code examples in multiple languages

Ready to integrate? Request Access — Free