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":"PAYZEN",
    "metadata":null,
    "_type":"V4/WebService/Response"
}

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

PARAMETERS TYPE DESCRIPTION
webService string web-service called, format: [namespace]/[web_service_name]
version string version of the API
status string status of the response SUCCESS or ERROR
answer object business response (if status is SUCCESS)
ticket string ticket number to be transmitted to the support service (unimplemented)
applicationProvider string gateway that provides the service
applicationVersion string version of the application
metadata object 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": "PAYZEN",
  "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 logs are some simple.
  • 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.