Bidirectional API Calls

In addition to the HTTP API, this platform provides an API for bidirectional communication using SockJS. SockJS is a protocol (intended primarily for Javascript) that allows a variety of mechanisms (such as WebSockets) for maintaining a long-lived connection with a server.

This API accepts SockJS connections at the following URL:

https://stream.wingcash.com/bd/sockjs

See the sample bidirectional app and its source code. It connects to the bidirectional API, sends some “ping” messages, receives responses, and lets the connection sit. Because the example does not subscribe to any feeds, the service will close the connection automatically after 1 minute. If software using the bidirectional API successfully subscribes to a feed, the service leaves the connection open.

Once a bidirectional connection is open, the service is ready to receive JSON-encoded request objects. Every request must have a path attribute and most require an access_token. Responses are also encoded in JSON.

Error Handling

When the service sends an error message through a bidirectional channel, it sends an object with error_code and error attributes. The error may be translated by locale. A common error_code is the string 403 (or 401), which indicates a permission was denied or an access token is no longer valid.

Basic Heartbeat

/ping

When you send a ping, the service responds immediately with a “pong” message.

Request Attributes
path
String: /ping
Response Attributes
pong
Integer: 1.
request_message
Object: the request message, echoed back. You can use this to keep track of request identifiers.

Cash Received

/wallet/receive-feed

This request subscribes the connection to the feed of cash received by the authenticated profile. The service provides a list of recent posts, then optionally sends a message every time the authenticated profile receives cash.

This API call requires the receive_cash permission. Unlike most API calls, this API call accepts access tokens that have passed “soft” expiration.

Request Attributes
path
String: /wallet/receive-feed
access_token
Required string: The access token provided by the Authorization Flow.
limit
Optional integer: the number of recent posts the service should provide. The default is 10.
subscribe
Optional boolean value: if true, subscribe to the feed; the service sends another response object for each new transfer. The default is false.
before_timestamp
Optional ISO 8601 timestamp: sets an upper bound on the timestamp of posts provided by the service. Use this to show older posts when the user wants to see more.

Note

It doesn’t make sense to use subscribe and before_timestamp together in a single request.

Response Attributes

The service sends multiple responses. Each response has these attributes:

request_message
The request message, echoed back. You can use this to keep track of request identifiers.
posts
A list of PostDetail objects.
ended
True if the list of posts was requested by the client and the list was not cut short by the limit parameter. If there are more posts the client could retrieve, this attribute is false.
requested
True if the client requested this list of posts. This attribute is false when the message originated from a cash transfer event.

Receive Transfer Notifications

/wallet/receive-transfers

This request subscribes the connection to a feed of all transfers involving the authenticated profile. Use this to provide live updates of the user’s wallet summary and transfer list.

This API call requires the view_history permission.

Request Attributes
path
String: /wallet/receive-transfers
access_token
Required string: The access token provided by the Authorization Flow.
Subscription Response Attributes
subscribed
Boolean: true.
Notification Response Attributes
transfer
A TransferDetail object (with an empty steps_html attribute.)