This section provides information related to the authorization to access and perform operations via APIs.
Once you have subscribed any of the Platform's services as a third party, you will be enabled to access the API endpoints as follows:
- The Platform API endpoints through the
S2S
authentication schema. - All the service-specific API endpoints through the
S2S-Auth
authentication schema.
The following sections provide detailed information related to the authorization step that your users must complete in order to grant the access to producers' services through your application, and the management of the required confirmation to complete command instructions.
Confirming Commands
We define as commands those instructions that imply the transfer of a given amount of money outside of the account on which the operation is executed. The commands that can be requested via API are:
- POST Create SCT Order to request the execution of a SEPA Credit Transfer
- POST Create SCT-Inst Order to request the execution of an Instant SEPA Credit Transfer
- POST Create CBILL Order to request a CBILL payment instruction
- POST Create PagoPA Order to request a PagoPA payment instruction
- POST Create Postal Form Order to request the payment of a postal form
- POST Create F24-Simple Order to request the payment of a F24-Simple module
Whenever you issue a command request on behalf of your user, such request may be blocked for security reasons. In this case, the user is notified with a challenge response that must be answered to continue the execution of the requested operation.
If the command execution is blocked, the status code of the API response is PENDING
, indicating that further actions are required to complete the operation. Please refer to the Status codes section for further information about API response status codes.
After having invoked one of the previously listed endpoints, the response structure in case of PENDING
status code differs from the standard one as documented in the technical reference, and is structured as follows (this example is related to the POST Create SCT Order):
Request: POST https://api.platfr.io/api/gbs/banking/v2.1/accounts/{accountId}/payments/sct/orders Body: { ... POST Create SCT Order body parameters ... } Response: HTTP/1.1 200 OK { "status": "PENDING", "errors": [], "payload": { "challengeId": "1d5181ec-97a7-4b97-86ab-b92b746e6896", "channel": "SMS" } }
The payload
element contains the information related to a challenge that must be answered in order to proceed with the command required. The challengeId
field provides a reference ID that must be used when answering the challenge, while the channel
field provides information about that channel through which the challenge response has been sent to the user. The possible values of the channel
field are:
SMS
, indicating that the challenge response has been sent to the user via SMS;RSA
, indicating that the challenge response is the code provided by the RSA token of the user.
The challenge response must be provided by invoking the corresponding PUT Challenge Response of the originally requested service, providing in the payload both the channel
and the response
. The answer to this last API call is the answer that was expected to the original command. The challenge response answer for the previous example in case of correct challenge response is the following:
Request: PUT https://api.platfr.io/api/gbs/banking/v2.1/accounts/{accountId}/payments/sct/challenges/1d5181ec-97a7-4b97-86ab-b92b746e6896 Body: { "channel" : "SMS", "response" : "123456" } Response: HTTP/1.1 200 OK { "status": "OK", "errors": [], "payload": { "orderId": "180060099", "cro": "58643941200", "uri": "NOTPROVIDED", "amount": { "senderAmount": "1000.00", "senderCurrency": "EUR" }, "feeType": "SHA", "fees": [ { "amount": "3.50", "currency": "EUR", "code": "MK003", "description": "Commissione valutaria" } ], "date": "26/08/2017", "taxRelief": null } }
If the challenge response provided is incorrect, then you should expect an HTTP/403 Unauthorized response, as if the original call was unsuccessful.