Documentation API SuiTch

This document is a restitution of the different steps to the integration of the SuiTch payment API.

1. Introduction #.

The SuiTch API is a JSON REST API used by partner systems to access the services of the Wallet platform. The API offers services used by e.g. online merchants for the management of payments and other financial services. This document gives an overview of the API structure.

2. Getting started #.

Follow these simple steps to get started :

– Register as a SuiTch dealer,

– After validating your merchant account, log into your merchant area and click on the “API” menu to check and retrieve your subscription keys under your profile. Check and retrieve your subscription keys under your profile,

– Generate a token using your newly created Subscription Key, User API and Key API,

– Access the desired API and use your subscription key and token to connect to the API termination points,

-Try the APIs on the portal.

 

3. API description #

Authentication :

There are three credentials used in the SuiTch API: Subscription Key, User API, and API Key for O auth 2.0 The Subscription Key is used to provide access to the APIs. A user is assigned a Subscription Key when subscribing to the services offered by the API. The User API and API Key are used to grant access to the Wallet system. These credentials are fully managed by SuiTch. However, there is the Sandbox environment, to allow developers to use the API for testing purposes only. The Subscription Key, the User API and the API Key are part of the header of all requests sent to the API Manager. This authentication information can be found under the user profile in the Partners Portal.

 

4. How does the API work? #

Open API uses the O auth 2.0 token for request authentication. The client will request an access token using the client credentials assignment according to RFC 6749. The received token complies with RFC 6750 Carrier Token. The User API and Key API are used in the basic authentication header when requesting the access token. The received token has an expiration time. The same token can be used for transactions until it expires. A new token is requested using the POST /collections/token service in the same way as the original token. The new token can be requested before the previous token expires to prevent authentication failure due to token expiration.

The sequence below describes the flow of requesting a token and using the token in a request.

  1. The SuiTch system requests an access token using the User API and the Key API and Subscription Key as authentication.
  2. The Wallet platform authenticates the credentials and responds with the access token.
  3. The SuiTch system will use the access token for any request sent to the Wallet Platform, e.g. POST / requesttopay (To finalize payment).

Note: The same token should be used if it has not expired.

 

5. API Methods #.

The SuiTch API uses POST, GET methods. This section gives an overview of the interaction sequence used in the API and the use of the methods.

POST

The POST method is used to create a resource in Wallet Platform. The request includes a reference identifier that is used to uniquely identify the specific resource created by the POST request. If a POST uses a reference ID that is already in use, a duplication error response will be sent to the customer. POST is an asynchronous method. The Wallet platform will validate the request to ensure that it is correct according to the API specifications and then respond with HTTP 202 Accepted. The created resource will have the status PENDING. Once the request is processed, the status will be updated successfully or unsuccessfully. The requester can then be informed of the final status by a reminder. Example: Parameters to be sent at POST.

{

  “amount”: “string”,

  “phone”: “string”,  

  “apiuser”: “thong”,  

  “apikey”: “thong”,  

  “subscriptionkey”: “string”

}

 

GET

GET is used to request information on a specific resource. The URL in GET must include the transaction reference for the resource. If a resource has been created with POST, the Transaction Reference ID provided in the request is used for the identity of the resource.

Responses

200 OK

  1. Note that a failed payment request will also be returned with this status. The “status” of RequestToPayResult can be used to determine the outcome of the request. The “reason” field can be used to retrieve a cause in case of failure.

Example: Parameters to be sent during a GET request

{

  “access_token”: “string”,

  “transactionID”: “string”,  

  “apiuser”: “thong”,  

  “apikey”: “thong”,  

  “subscriptionkey”: “string”

}