Merchant Events WebSocket

Merchant Monitor Stream (event_v1)

curl --request GET \
  --url https://api-beta.pepay.io/ws/merchant/events \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api-beta.pepay.io/ws/merchant/events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-beta.pepay.io/ws/merchant/events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api-beta.pepay.io/ws/merchant/events"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api-beta.pepay.io/ws/merchant/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

GET

merchant

events

Merchant Monitor Stream (event_v1)

curl --request GET \
  --url https://api-beta.pepay.io/ws/merchant/events \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api-beta.pepay.io/ws/merchant/events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-beta.pepay.io/ws/merchant/events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api-beta.pepay.io/ws/merchant/events"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api-beta.pepay.io/ws/merchant/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

Overview

Use this WebSocket endpoint to receive realtime merchant events (for example: invoice updates, payments, and commerce order events where applicable).

Authentication

WebSocket connections use a token minted from the REST API. See: Mint a WebSocket Token.

Request

SDK (recommended)

const stream = pepay.ws.connectMerchantEvents({ format: 'event_v1' });
stream.on('event', (event) => console.log(event));

WebSocket URL (wss)

WS_TOKEN="ws_..."

echo "wss://api-beta.pepay.io/ws/merchant/events?token=$WS_TOKEN"

Response

WebSocket upgrade returns 101 Switching Protocols. After connecting, you receive frames (for example event_v1 events). Example event frame:

{
  "id": "evt_1734780000000-123",
  "object": "event",
  "api_version": "2025-12-16",
  "created": 1734780000,
  "type": "invoice.updated",
  "livemode": false,
  "pending_webhooks": 0,
  "data": {
    "object": {
      "object": "invoice",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "paid",
      "invoice_type": "standard",
      "environment": "devnet"
    }
  }
}

Errors

401 invalid/expired ws_token (connection is rejected/closed)
Treat delivery as at-least-once; dedupe by event.id if you process idempotently.

Examples

Use since=<event_id> to resume from a known cursor when supported.

Next: Merchant Invoices

Authorizations

x-api-key

string

header

required

API key for server-to-server operations (scope=merchant or commerce)

Query Parameters

token

string

Short-lived ws_token (browser/mobile auth).

since

string

Replay cursor (event id), e.g. evt_1700000000000-123.

types

string

Comma-separated allowlisted event type filters (e.g. invoice.*, invoice_payment.updated).

invoice_type

string

Optional invoice type filter (e.g. standard, commerce).

customer_id

string

invoice_id

string

environment

enum<string>

Available options:

devnet,

mainnet

format

enum<string>

Available options:

event_v1

Response

101

Switching Protocols (WebSocket)

Overview

API

Merchant

Tokens

Commerce

Payor

WebSockets

Webhooks

Merchant Events WebSocket

Overview

Authentication

Request

SDK (recommended)

WebSocket URL (wss)

Response

Errors

Examples

Authorizations

Query Parameters

Response

​Overview

​Authentication

​Request

​SDK (recommended)

​WebSocket URL (wss)

​Response

​Errors

​Examples

Authorizations

Query Parameters

Response

Overview

Authentication

Request

SDK (recommended)

WebSocket URL (wss)

Response

Errors

Examples