Subscribing

The WebSocket stream provides real-time updates of the following data:

• Exchange Rates
• Payment Status Updates
• System Notifications

Steps to use the stream

To use the WebSocket stream follow these steps:

Connection

To establish a connection use the stream URL depending on the environment you'd like to use:

Sandbox URL:

wss://sandbox-ws.quickpay.best/app/pagCMLx6TXrb

Production URL:

wss://ws.quickpay.best/app/pagCMLx6TXrb

📘

Test stream

We provide a test stream that is available all the time on the sandbox URL:

wss://sandbox-ws.quickpay.best/app/pagCMLx6TXrb

Use the channel "test-channel" when trying out this test stream.

Upon successfully connecting, you will receive the welcome message:

{"event":"pusher_internal:subscription_succeeded","channel":"test-channel"}

Authentication

You need to authenticate yourself using your credentials. This can be done using HTTP headers:

Authenticate with HTTP headers

You can set the same headers used for the API endpoints:

• Authorization: Bearer {JWT_TOKEN}
• X-API-KEY: {API_KEY}

Here's an example using wscat:

$ curl -X POST https://sandbox-api.quickpay.best/v1/websocket/auth \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -d '{
    "socket_id": "123.456",
    "channel_name": "test-channel"
  }'

If you provided correct credentials you will receive another success message:

{"auth":"pagCMLx6TXrb:d561d8e1618b72770d31a78a0ab23fe59c2c26f7f51239508c81221a76e1b9f9"}

Subscription

Congratulations, you are ready to receive real-time exchange rate data!

You can send one or more subscription messages. The general format of the subscribe message is this:

{
  "event": "pusher:subscribe",
  "data": {
    "channel": "private-merchant.{merchant_id}"
  }
}

You can subscribe to different channels based on your needs:

• private-merchant.{merchant_id} - Merchant-specific events
• private-payments.{merchant_id} - Payment status updates
• private-notifications.{merchant_id} - System notifications

For example in the sandbox stream, you can send this message:

{"event":"pusher:subscribe","data":{"auth":"pagCMLx6TXrb:d561d8e1618b72770d31a78a0ab23fe59c2c26f7f51239508c81221a76e1b9f9","channel":"private-merchant.merchant_001"}}

After subscribing you will receive a message that confirms your subscription:

{"event":"pusher_internal:subscription_succeeded","channel":"private-merchant.merchant_001"}

Messages

Format

Every message you receive from the server will be in the format:

{"event":"","channel":"","data":"{}"}

Control messages (i.e. where event is pusher_internal:subscription_succeeded, pusher_internal:subscription_error or pusher_internal:connection_established) always arrive as single JSON objects to make their processing easier.

Content type

You can use the Content-Type header to switch between text and binary message data frame:

• Content-Type: application/json

Example

Here's a complete example of the sandbox stream using the wscat cli tool:

# Connect and subscribe using wscat
$ wscat -c wss://sandbox-ws.quickpay.best/app/pagCMLx6TXrb
Connected (press CTRL+C to quit)
< {"event":"pusher:connection_established","data":"{"socket_id":"957523923.7566984777","activity_timeout":30}"}
> {"event":"pusher:subscribe","data":{"auth":"","channel":"test-channel"}}
< {"event":"pusher_internal:subscription_succeeded","channel":"test-channel"}

Troubleshooting

Common Issues

1. Connection Refused: Check if WebSocket server is running
2. Authentication Failed: Verify JWT token and API key
3. Channel Access Denied: Ensure proper channel permissions