> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paj.cash/llms.txt
> Use this file to discover all available pages before exploring further.

# Track a payment

> Follow a payment from the moment it opens until it settles or expires, over a WebSocket.

A [payment](https://docs.paj.cash/api-reference/create-payment.md) moves through a few statuses
between the moment you open it and the moment your balance is credited. Instead
of polling for them, subscribe to the payment's `id` on the payment socket. You
get its current state straight away, then a message each time its status
changes, until it settles or expires.

The socket runs on [Socket.IO](https://socket.io), on the same host as the REST
API, in the `payment` namespace:

```
wss://api.paj.cash/payment
```

It works alongside the [payment webhook](https://docs.paj.cash/api-reference/create-payment.md#following-the-payment)
rather than replacing it. The webhook tells your server once a payment has
settled, even if nothing is connected at that moment. The socket shows every
step while you are watching, which suits a checkout screen waiting for the
payer.

## Connecting

The socket takes the same [API key](https://docs.paj.cash/authentication.md) as the REST API. Send it in
the handshake as `auth.apiKey`, or as an `x-api-key` header if your client sets
headers.

```javascript theme={null}
import { io } from 'socket.io-client';

const socket = io('https://api.paj.cash/payment', {
  auth: { apiKey: process.env.PAJ_API_KEY },
});

socket.on('connect_error', (error) => {
  // "No API key provided", "Invalid API key", or
  // "Could not verify the API key, try again"
  console.error(error.message);
});
```

A connection without a valid key is refused during the handshake and never
opens. The first two messages are permanent: fix the key rather than retrying.
The third means the key could not be checked at that moment, and Socket.IO's
own reconnection will try again.

> [!WARNING]
>
> This is your API key, and the same rules apply as anywhere else: connect from
> your backend, never from a browser bundle or a mobile app a user can read.
> Relay what your payer needs to see through your own servers.

## Subscribing to a payment

Subscribe with the `id` that
[`POST /pub/v2/payment`](https://docs.paj.cash/api-reference/create-payment) returned:

```javascript theme={null}
const payment = await createPayment({ amount: 25, chain: 'SOLANA', mint });

socket.emit('subscribe', { paymentId: payment.id }, (ack) => {
  if (!ack.ok) return console.error(ack.error);
  console.log('Current status:', ack.payment.status);
});

socket.on('PAYMENT_UPDATE', (update) => {
  console.log(update.id, update.status);

  if (['SUCCESSFUL', 'EXPIRED', 'ERROR'].includes(update.status)) {
    socket.emit('unsubscribe', { paymentId: update.id });
  }
});
```

Subscribe as soon as the payment is created, before you show the payer where to
pay. Subscribing late is fine too: the acknowledgement carries the payment's
current state, including a final one.

You can only follow payments that belong to the business your API key belongs
to. A payment opened under another business is refused as `Payment not found`,
exactly as if it did not exist.

### The acknowledgement

The callback you pass to `subscribe` receives:

**ok** `boolean` *required*

Whether you are now subscribed.

**paymentId** `string`

The payment you subscribed to, in lowercase.

**payment** `object`

Where the payment stands now, in the same shape as a
[`PAYMENT_UPDATE`](#updates).

**error** `string`

Why the subscription was refused, when `ok` is `false`. The same message is
also sent as an `ERROR` event.

A subscription is refused when:

* `paymentId` is missing or is not a 24-character hex id: `A valid paymentId is required`.
* No payment of your business has that id: `Payment not found`.
* The connection already watches 50 payments. Unsubscribe from payments that
  have finished to stay under the limit, or open a second connection.
* The payment could not be looked up at that moment: `Could not look up the
  payment, try again`. You are not subscribed; send `subscribe` again.

## Updates

Every `PAYMENT_UPDATE` carries the whole current state of one payment, not just
what changed, so you can handle each one on its own. It has the same shape as
the [create payment](https://docs.paj.cash/api-reference/create-payment.md) response, so the type you
use for that response works here too.

```json theme={null}
{
  "id": "507f1f77bcf86cd799439011",
  "method": "TOKEN",
  "status": "SUCCESSFUL",
  "amount": 25,
  "fee": 0.25,
  "totalAmount": 25.25,
  "receivedAmount": 25.25,
  "expiresAt": "2026-11-13T10:30:00.000Z",
  "token": {
    "chain": "SOLANA",
    "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "address": "8xKq…"
  }
}
```

**id** `string` *required*

The payment you subscribed to.

**method** `string` *required*

`TOKEN` or `FIAT`.

**status** `string` *required*

Where the payment stands. See [Statuses](#statuses).

**amount** `number` *required*

What you asked for, in whole units of the currency or token.

**fee** `number`

Paj's fee, in the same units. Absent when no fee applies.

**totalAmount** `number` *required*

What the payer must send: `amount` plus `fee`.

**receivedAmount** `number`

What actually arrived, in the same units as `totalAmount`. Absent until a
deposit is seen.

**expiresAt** `string`

When the payment window closes, as an ISO 8601 timestamp.

**token** `object`

The `chain`, `mint` and deposit `address`, for a `TOKEN` payment.

**fiat** `object`

The `currency`, `accountNumber` and `accountName`, for a `FIAT` payment. The
`bank` is not included on the socket; use the one from the create response.

> [!NOTE]
>
> A deposit may fall up to 0.1% short of `totalAmount` and still settle as
> `SUCCESSFUL`, credited for what actually landed; so may one that overpays.
> Compare `receivedAmount` with `totalAmount` to see what arrived. A deposit any
> shorter is not settled: the payment moves to `ERROR` and stays there.

### Statuses

| Status | Meaning |
| - | - |
| `AWAITING` | Open and waiting for the payer. This is the status in the acknowledgement of a new payment. |
| `PROCESSING` | The payment arrived and is being moved into Paj's pool, swapped to USDC first if it was another token. |
| `SUCCESSFUL` | Settled, with no more than 0.1% short of `totalAmount` arrived, and your balance has been credited. Final. |
| `EXPIRED` | The window closed before anything arrived. Final: open a new payment rather than reusing the address. |
| `ERROR` | Moving the funds failed. **This is not final.** Paj retries, and a retry moves the payment back to `PROCESSING`. The exception is an underpayment — `receivedAmount` more than 0.1% below `totalAmount` — which is not retried: nothing is swept or credited, and the funds stay on the deposit address until Paj resolves it with you. |

Treat `SUCCESSFUL` and `EXPIRED` as the end of a payment. If a payment stays in
`ERROR`, contact Paj with its `id`.

## Staying connected

Subscriptions belong to the connection. When a connection drops, its
subscriptions go with it, and Socket.IO reconnects with a fresh connection and
none of them. Subscribe again on every `connect`, not just the first:

```javascript theme={null}
const watching = new Set();

function watch(paymentId) {
  watching.add(paymentId);
  if (socket.connected) socket.emit('subscribe', { paymentId }, onAck);
}

socket.on('connect', () => {
  for (const paymentId of watching) {
    socket.emit('subscribe', { paymentId }, onAck);
  }
});

socket.on('PAYMENT_UPDATE', (update) => {
  if (['SUCCESSFUL', 'EXPIRED'].includes(update.status)) {
    watching.delete(update.id);
    socket.emit('unsubscribe', { paymentId: update.id });
  }
});
```

Updates sent while you were disconnected are not replayed. The acknowledgement
of each new subscription carries the current state, so after reconnecting you
are back in step without anything else.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.