Search the wiki¶

API Documentation¶

Mobile Payment¶

Discuss (0) History

Polling JSON REST API

RSS

You can poll for mobile originated messages (MO) and delivery reports (DR) using our JSON REST API.

Table of Contents [Hide/Show]

Gateway connect information
   Endpoint URL
   SSL Certificates
Polling Services
   Overview
   Authentication
REST methods
   Poll
   Ack
Example requests
   Polling MO with no ack required
   Polling MO with ack required
   Polling DR with no ack required
   Polling DR with ack required
   Other
      Example error response

Gateway connect information¶

Endpoint URL¶

Base URL: https://poll.pswin.com/

SSL Certificates¶

All PSWinCom services are secured using a single *.pswin.com SSL Server certificate. The whole certificate chain can be downloaded from the PSWinCom Wiki: PSWinCom SSL certificates

Polling Services¶

Overview¶

Usage of this API must be handled carefully, as continuously polling towards the system may degrade performance. When the poll-request returns no messages, the client should wait at least 10 seconds before issuing a new poll-request. When the poll-request returns a message, a new request may be issued immediately until the request returns empty.

Authentication¶

Requests are authenticated using Basic authentication and your credentials are the same as for sending messages to the gateway.

REST methods¶

None of the following methods require a request body.

Poll¶

POST /api/output/rest/{payloadtype}/gateway/{userid}?ackrequired=true|false

Parameters

Path parameter	Possible values	Description
payloadtype	mo\|dr	What kind of message you are polling for
userid	Your gateway username	Must be the same as in your basic auth header
ackrequired	true\|false	Wether or not you want the message to stay in the queue until acked

The ackrequired parameter defines wether or not the message/dr is removed from the queue upon retrieval or if it should be removed by a separate ack request. If you set it to true the message/dr will be returned to the queue after 20 seconds with no ack sent.

Possible HTTP responses

Code	Result	Body
200	A message was found and returned	See Example MO response or Example DR response
401	You are not allowed to access this queue, check your credentials	See Example Error Response
404	At the moment there are no more messages in your queue, try again later	See Example Error Response
500	Something unexpected happened	See Example Error Response

Ack¶

PUT /api/output/rest/{payloadtype}/gateway/{userid}/ack/{reference}

Parameters

Path parameter	Possible values	Description
payloadtype	mo\|dr	What kind of message you are acking
userid	Your gateway username	Must be the same as in your basic auth header
reference	GUID	The GUID reference returned by the poll request

Possible HTTP responses

Code	Result	Body
204	The message was successfully acknowledged	No content
401	You are not allowed to access this queue, check your credentials	See Example Error Response
404	The message with the provided reference does not exist or has already been acknowledged	See Example Error Response
500	Something unexpected happened	See Example Error Response

Example requests¶

Polling MO with no ack required¶

Request

POST https://poll.pswin.com/api/output/rest/mo/gateway/myuser?ackrequired=false
Authorization: Basic kja934msf99w3==

Response

200 OK
Content-Type: application/json
 
{
    "sender": "4712345678",
    "receiver": "1234",
    "text": "Some text",
    "operatorTimestamp": "2017-11-08T13:37:00Z",
    "reference": "7e5ac56a-4c79-6e8a-6431-24ac84f49fe2"
}

Polling MO with ack required¶

Request

POST https://poll.pswin.com/api/output/rest/mo/gateway/myuser?ackrequired=true
Authorization: Basic kja934msf99w3==

Response

200 OK
Content-Type: application/json
 
{
    "sender": "4712345678",
    "receiver": "1234",
    "text": "Some text",
    "operatorTimestamp": "2017-11-08T13:37:00Z",
    "reference": "7e5ac56a-4c79-6e8a-6431-24ac84f49fe2"
}

Ack Request

PUT http://poll.pswin.com/api/output/rest/mo/gateway/myuser/ack/7e5ac56a-4c79-6e8a-6431-24ac84f49fe2
Authorization: Basic kja934msf99w3==

Ack Response

204 No Content
Content-Type: text/html

Polling DR with no ack required¶

Request

POST https://poll.pswin.com/api/output/rest/dr/gateway/myuser?ackrequired=false
AUTHORIZATION: BASIC kja934msf99w3==

Example response

200 OK
Content-Type: application/json
 
{
    "receiver": "4712345678",
    "state": "DELIVRD",
    "operatorTimestamp": "2017-11-08T13:37:00Z",
    "reference": "7e5ac56a-4c79-6e8a-6431-24ac84f49fe2"
}

Polling DR with ack required¶

Request

POST https://poll.pswin.com/api/output/rest/dr/gateway/myuser?ackrequired=true
Authorization: Basic kja934msf99w3==

Response

200 OK
Content-Type: application/json
 
{
    "receiver": "4712345678",
    "state": "DELIVRD",
    "operatorTimestamp": "2017-11-08T13:37:00Z",
    "reference": "7e5ac56a-4c79-6e8a-6431-24ac84f49fe2"
}

Ack Request

PUT http://poll.pswin.com/api/output/rest/dr/gateway/myuser/ack/7e5ac56a-4c79-6e8a-6431-24ac84f49fe2
Authorization: Basic kja934msf99w3==

Ack Response

204 No Content
Content-Type: text/html

Other¶

Example error response¶

404 Not Found
Content-Type: application/json

{
    "statusCode": 404,
    "message": "The resource you have requested cannot be found.",
    "details": "Error details are currently disabled."
}

Intouch interfaces: REST | Syncopy