Fidesmo API

Configuration

In the settings of your application (see all your applications here, use the edit symbol to open the settings page of the application) you need to add two URLs:

  • The Service Description URL, from which Fidesmo will request some service information elements to request confirmation from the user and, if necessary, perform payments.
  • The Service Delivery URL, which launches the service delivery

Service Description requests

When an end user wants to install a service to their Fidesmo Card, they request the service via an application using the method described here. This triggers a service delivery session. The first step of a service delivery session is for Fidesmo to request the service description from the service provider. If you are reading this, the service provider is most likely you!

The format of the request is a very straightforward HTTP GET, taking the Service Description URL and appending the Service ID. For example if the Service ID is "install" and the Service Description URL is "http://example.com" then the Service Description Fidesmo will issue a GET "http://example.com/install". It's as simple as that.

If the requested service exists and can be delivered you should respond with a 200 OK as well as a description of the service. The format of the service description (the response) is described in this page.

If the service does not exist 404 Not Found should be returned. If the service exists but can not (for any reason) be delivered at the moment any 5xx code should be used (such as 500 Internal Server Error).

It is not mandatory to implement this endpoint. You can configure your application so that the service description is sent directly by Fidesmo, using a service recipe.

Service Delivery requests

After the user has confirmed that he/she wants to receive the service, and the payment has been authorized if necessary, Fidesmo will call the Service Delivery URL to start the delivery of the requested service.

The format of the request is a JSON encoded message sent within an HTTP PUT request:

Field Type Examples Explanation
sessionId String formatted UUID 906b1b93-7b4d-442a-aa25-c8a06f599e2d The session id is used throughout the service delivery session to indicate which API calls that are part of it.
serviceId String secure-password-storage The service id is the same string used in the Service Description Request, which uniquely identifies your service.
description Object { "title": "Secure password storage application" } The description is the same JSON object received in the response to the previous Service Description Request

A full JSON example:

{ "sessionId": "906b1b93-7b4d-442a-aa25-c8a06f599e2d", "serviceId": "secure-password-storage",
"description": { "title": "Secure password storage application" } }

This requests that the service "secure-password-storage" should be delivered using the service delivery session id "906b1b93-7b4d-442a-aa25-c8a06f599e2d".

If the requested service exists and can be delivered you should respond with a 200 OK.

If the service does not exist 404 Not Found should be returned. If the service exists but can not (for any reason) be delivered at the moment any 5xx code should be used (such as 500 Internal Server Error).

As soon as you receive the service delivery request, you can start the service delivery process. The service delivery process comprises calling other Fidesmo APIs, such as the transceive API, to communicate with the card to set up the service for the end user.

When a service delivery is completed, i.e. all calls to other Fidesmo APIs necessary to deliver the service have finished, then the service provider should call /service/completed to close the delivery session. This is especially important when payments are involved: the end user will only be charged if the Service Provider sends the service completed message and it is acknowledged with an HTTP 200 OK by the Fidesmo backend server. See the architecture page for more information.

Live documentation

Use our live documentation to learn about the Fidesmo APIs

Please note that all Service Delivery operations (those POST operations including the sessionId parameter, in the first positions on the list below) will only work either