Access Methods

Examples

When doing a plannings request with a TO, the TO will let the MP know the "accessMethod" for trip execution. The various access methods supported are Deeplink, QR/Aztec code, AXA EKEY for AXA bluetooth locks, OV-Chipkaart, EMV, None. Please note that only the access method will be provided in the result of the plannings request. This parameter provides the possibility to have more than one access method, for example, Deeplink and AXA-EKEY-OTP. So, if an MP only wants to do a deeplink connection, they can ignore the AXA-EKEY-OTP method.

Example (partial) JSON of the result of a planning request, where the asset can be opened using deeplink:

{
  "validUntil": "2021-04-15T06:28:58.967Z",
  "options": [
    {
      "id": "id1",
	  "state": "NEW",
	  "legs": [
	    "id": "id1",
		"asset": { "overriddenProperties": { "accessMethods" : [ "DEEPLINK" ] } }
	  ]
	}
  ]
}

Providing this information is often accompanied by the processIdentifiers ASSET_BASED, ACCESS_CODE_DEEPLINK. To get the deeplink in the trip execution, the method /legs/{id}/events - PREPARE should be called, unless the deeplink is already provided in the result of the /bookings/{id}/events - COMMIT.

Whenever a MP wants to get the deeplink, it has to call the /legs/{id}/events - PREPARE. In the response, the access methods will be delivered; in the case of the example, it could contain something like this:

 { ...
   "overriddenProperties": { 
     "assetAccessData" : {
        "tokenType": "DEEPLINK"
     },
     "tokenData": {
         "url": "anyTOApp://deeplink?access-info=349AB934-3482BA",
         "knownParameters": ["return-url","error-url"]
     }
   } 
   ...
 }

The MP can extend the URL with the parameters and their values. The parameters are not yet standardized in the API, bilateral agreements should cover these in the current situation. But these are already foreseen:

parameter	description	usage
return-url	the deeplink into the MP app. Is being called whenever the TO wants to give control back to the MP app	anyMPApp://trip-ended/
error-url	the deeplink into the MP app. Is being called whenever the TO app ends in an error state	anyMPApp://error/
error-code	the TO can extend the error-url with this parameter, the codes itself are nowadays not standardized
error-description	the TO can extend the error-url with this parameter, the message should preferably be in the Accept-Language of the header fields
message	the TO can extend the return-url with this parameter to give some information when ending the trip