Specifications of REST data exchange

Web Services use the common principles of the REST API. The used exchange format is JSON.

Authentication

The REST API uses basic authentication. For more information, go to: Authentication phase. To learn where to find your keys, see the following article: Prerequisites.

Request parameters

The application awaits valid JSON as request entry. For example, Charge/SDKTest will interpret the Type/String object as entry value.

The call must be made as follows:

{
    "value": "my testing value"
}
/** 
 * Initialize the SDK 
 * Please update your keys in keys.php
 */
$client = new Lyra\Client();  

/**
 * I send test data
 */
$store = array("value" => "my testing value");
$response = $client->post("V4/Charge/SDKTest", $store);

Response parameters

When the Web Service responds, it returns:

{
    "webService":"Charge/SDKTest",
    "version":"V4",
    "applicationVersion":"4.1.2",
    "status":"SUCCESS",
    "answer": {
        "value":"my testing value",
        "_type":"V4/Type/String"
    },
    "ticket":null,
    "serverDate":"2018-10-02T16:13:57+00:00",
    "applicationProvider":"NPS",
    "metadata":null,
    "_type":"V4/WebService/Response"
}

The requested object is returned in a generic response object where:

PARAMETERS TYPE DESCRIPTION
webService string The called web service, format: [namespace]/[web_service_name].
version string Version of the API.
status string Status of the response: SUCCESS or ERROR.
answer the Business response (if the status is SUCCESS).
ticket string Ticket number to be transmitted to the support service (not implemented).
applicationProvider string Gateway that provides the service.
applicationVersion string Version of the application.
metadata the Reserved for future use.
serverDateTime string Date of the server that responded, in UTC format.
_type string Type of the object. Always starts with the version number.

Error handling

In case of Web Service error:

{
    "amount": -1
}

The response is:

{
  "webService": "Charge/CreatePayment",
  "version": "V4",
  "applicationVersion": "4.5.1",
  "status": "ERROR",
  "answer": {
    "errorCode": "INT_902",
    "errorMessage": "web-service input data validation error",
    "detailedErrorCode": null,
    "detailedErrorMessage": "can't decode JSON data : {\n    \"amount\":   -1,\n}",
    "ticket": "null",
    "_type": "V4/WebService/WebServiceError"
  },
  "ticket": null,
  "serverDate": "2018-12-10T19:27:32+00:00",
  "applicationProvider": "NPS",
  "metadata": null,
  "_type": "V4/WebService/Response"
}

The Web Service has failed and returns a V3.1/WebService/WebServiceError object:

PARAMETER TYPE DESCRIPTION
errorCode string Error code (in [PREFIX]_[CODE] format)
errorMessage string Error message
detailedErrorCode string Detailed error code (or null)
detailedErrorMessage string Detailed message (or null)

For more information on errors, go to: Error codes.

Why is the API not 100% RESTful?

We have decided to develop a simple API to avoid common errors:

We only use the POST method.

This way, we avoid the usual questions about which method should be used, the answer is ALWAYS POST.

All the request parameters are sent as a JSON object:

  • There is only one way of sending parameters (nothing is added in the URI).
  • The reports are simplified.
  • The API always responds HTTP 200.

Therefore, there is no need to manage several HTTP status codes, the answer is always 200. The Web Service status can be viewed in the JSON object.

Date and time

The datetime object is in ISO 8601 format.

The Web Service accepts all the time zones such as:

  • 2015-11-19T16:56:57+00:00
  • 2015-11-19T16:56:57+01:00
  • 2015-11-19T16:56:57+Z

The server always returns the datetime object in UTC format (GMT+00):

  • 2015-11-19T16:56:57+00:00

The server never returns 2015-11-19T16:56:57+Z

Null values

Non-mandatory null values are automatically excluded from the response. In other words, a null property is included in the response only if the key is made mandatory, null being an acceptable value.