Payment Broker

Overview

Vortex Payment Broker (PB) provides the framework/ the payment bus gateway to process the payment requests. The targeted clients are PPS internal services, such as MXM, RP, Passport or trusted 3rd party partners. A client, or tenant, initiates the connection to Payment Broker and streams the payment requests using Payment Broker. The responses are streamed back using the same channel. The client is then supposed to authorize once during handshake to establish the connection and to keep the connection open.

Vortex Payment Broker API is developed based on the WebSocket protocol. WebSocket leverages HTTP for handshake, but is a full-duplex communication protocol and asynchronous by nature. To support pairing each payment request to its response, Vortex platform follows an internal protocol, or a request envelop, to wrap each request with a universally unique ID, or requestId, and the tenant profile data, through the lifecycle of each request/response. The corresponding response from each service down stream carries the same requestId in order to pair the response back to its request. In that sense, services leveraging WebSocket must be stateful and asynchronous.

Vortex WebSocket API / Protocol

WebSocket Protocol

WebSocket Protocol or simply the WebSocket can be interpreted as a two-step protocol, that makes it possible to open a two-way interactive communication session between the browser and the server.

Handshake: The first step is Handshake; to establish the connection between client and server.
Bidirectional Full Duplex Communication: The second step is the bidirectional full-duplex communication; where the client and the server are just two endpoints of the communication.

Here's a sample of raw HTTP GET message:

GET /chat HTTP/1.1
  Host: server.example.com
  Upgrade: websocket
  Connection: Upgrade
  Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
  Origin: http://example.com
  Sec-WebSocket-Protocol: chat, superchat
  Sec-WebSocket-Version: 13

The response that we get from the server is:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
Sec-WebSocket-Protocol: chat

Vortex API Version of Handshake

A typical Vortex API handshake request is a HTTP GET with headers similar to this

Sec-WebSocket-Version: 13
Sec-WebSocket-Key: WWjOl1rwOwC75MEesFykhQ==
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Extensions: permessage-deflate; client_max_window_bits
Host: sb-payment.vortex.cloud
EOS-Replication-Group: qa
Authorization: Bearer <authorization token>
EOS-Protocol-Version: 1.1.0

The Upgrade header is to tell the server that this is going to be a WebSocket handshake request and URI starts with the protocol identifier 'ws://'. Most of header parameters are generated by the WebSocket client implementation. There is no need to add or update those parameters.

Three of the parameters are added as per Vortex API protocol

EOS-Replication-Group: qa
Authorization: Bearer <authorization token>
EOS-Protocol-Version: 1.1.0

Below is a sample of the response headers:

Server: nginx/1.23.0
Date: Wed, 09 Nov 2022 02:44:23 GMT
Connection: upgrade
Upgrade: websocket
Sec-WebSocket-Accept: vrVYu1XDmqbPG1+8QWU1vHvESQY=
Access-Control-Allow-Credentials: true
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block

In addition to the response header, Vortex API sends a welcome message as part of the handshake.

{"name":"welcome",
  "value":
  	{"name":"EOS Payment Api Broker",
      "build":"1.125.1273-dev",
      "environment":"nonprod-aus",
      "server":
         {"package":"@pps/websocket",
          "version":"4.3.4",
          "protocol":"1.1.0"},
       "client":
         {"id":"3cc573fd-190d-5d8d-959c-dde7db457c72"}
     },
   "class":"event",
   "id":"23a1c201-57a1-5596-af6e-036496556c18"
}