Bidirectional API Calls

In addition to the HTTP API, WingCash 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.

WingCash 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, WingCash will close the connection automatically after 1 minute. If software using the bidirectional API successfully subscribes to a feed, WingCash leaves the connection open.

Once a bidirectional connection is open, WingCash 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 WingCash 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, WingCash 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. WingCash 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 WingCash should provide. The default is 10.
subscribe
Optional boolean value: if true, subscribe to the feed; WingCash 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 WingCash. 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

WingCash 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.)