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