Zelling Socket.IO API – Real-Time Payment Updates

Zelling provides a Socket.IO API to receive real-time payment updates.

You can subscribe to specific payments for crypto (tid) or PayPal (pid) and get instant notifications about status changes, new payments, or confirmations.

💡 We recommend using your own wrapper around the Zelling API for full control. Alternatively, you can redirect users to the hostedUrl for PayPal or crypto payments.

Connection

URL: https://ws.zelling.io

Protocol: Socket.IO

Example (JavaScript)

Subscriptions

Zelling Socket.IO API provides separate subscriptions for crypto payments and PayPal payments.

Type	Event Name	Description
Crypto	`subscribe_crypto`	Subscribe to updates for a specific crypto payment using `tid`. Payload: `{ tid: "TX-123456" }`
Crypto	`unsubscribe_crypto`	Unsubscribe from updates for a specific crypto payment. Payload: `{ tid: "TX-123456" }`
PayPal	`subscribe_paypal`	Subscribe to updates for a specific PayPal payment using `pid`. Payload: `{ pid: "PAYPAL-123456" }`
PayPal	`unsubscribe_paypal`	Unsubscribe from updates for a specific PayPal payment. Payload: `{ pid: "PAYPAL-123456" }`

Example: Subscribing

Example: Unsubscribing

Event Payloads

Crypto Payment Update (`crypto_update`)

{
  "tid": "TX-123456",
  "status": "CONFIRMED",
  "payments": [
    {
      "uuid": "pay-001",
      "txid": "tx123abc",
      "value_coin": 0.005,
      "confirmations": 3,
      "status": "CONFIRMED",
      "seen_at": "2025-09-01T19:00:00.000Z",
      "value_forwarded_coin": null
    }
  ],
  "events": [
    {
      "type": "payment.seen",
      "message": "Received 0.005 LTC (3/4 confirmations)",
      "oldStatus": null,
      "newStatus": null,
      "createdAt": "2025-09-01T19:00:00.000Z"
    },
    {
      "type": "invoice.status_changed",
      "message": "Status changed: PENDING → CONFIRMED",
      "oldStatus": "PENDING",
      "newStatus": "CONFIRMED",
      "createdAt": "2025-09-01T19:05:00.000Z"
    }
  ],
  "meta": {
    "orderId": "ORD-001",
    "customerId": "12345"
  },
  "cryptoCoin": "LTC",
  "cryptoAmountExpected": 0.01234,
  "cryptoAmountReceivedTotal": 0.005
}

PayPal Payment Update (`paypal_update`)

{
  "pid": "PAYPAL-20250902-123456",
  "currency": "USD",
  "amountExpected": 10.00,
  "amountReceivedTotal": 10.00,
  "status": "CONFIRMED",
  "payoutEmail": "seller@example.com",
  "senderEmail": "buyer@example.com"
}

Status Values

Status	Description
NEW	Invoice created, no payments received.
PARTIALLY_PAID	Partial payment received.
PAID_UNCONFIRMED	Full payment received but pending confirmations.
Note: This status applies only to crypto payments. PayPal payments do not use `PAID_UNCONFIRMED`; they go directly from `PARTIALLY_PAID` to `CONFIRMED` once the payment is completed.
CONFIRMED	Full payment confirmed.

Recommendations

✅ Use your own API wrapper around Zelling API for full control of payments, webhooks, and business logic.
This is strongly recommended for production systems to avoid losing payment data and to easily handle retries, logging, and notifications.

🌐 Alternative: Use the provided hostedUrl for a simple integration where Zelling handles the payment page and notifications.
This is faster to implement but offers less flexibility.

🔄 Real-time updates: Subscribe to payments via Socket.IO to get instant updates on tid (crypto) or pid (PayPal).
This allows your frontend or backend to react immediately when payments are made, partially paid, or confirmed.

📌 Important: Always handle failed webhook deliveries by implementing retry logic. For PayPal IPNs, if your wrapper cannot respond with HTTP 200, PayPal will retry sending the IPN. This ensures no updates are lost.

Socket.io API Documentation

Zelling Socket.IO API – Real-Time Payment Updates#

Connection#

Subscriptions#

Example: Subscribing#

Example: Unsubscribing#

Event Payloads#

Crypto Payment Update (crypto_update)#

PayPal Payment Update (paypal_update)#

Status Values#

Recommendations#