Skip to main content
A payment 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, on the same host as the REST API, in the payment namespace:
It works alongside the payment webhook 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 as the REST API. Send it in the handshake as auth.apiKey, or as an x-api-key header if your client sets headers.
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.
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 returned:
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:
boolean
required
Whether you are now subscribed.
string
The payment you subscribed to, in lowercase.
object
Where the payment stands now, in the same shape as a PAYMENT_UPDATE.
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 response, so the type you use for that response works here too.
string
required
The payment you subscribed to.
string
required
TOKEN or FIAT.
string
required
Where the payment stands. See Statuses.
number
required
What you asked for, in whole units of the currency or token.
number
Paj’s fee, in the same units. Absent when no fee applies.
number
required
What the payer must send: amount plus fee.
number
What actually arrived, in the same units as totalAmount. Absent until a deposit is seen.
string
When the payment window closes, as an ISO 8601 timestamp.
object
The chain, mint and deposit address, for a TOKEN payment.
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.
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

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:
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.