Table of contents
Integration for a payment instrument via redirect
The payment method with redirect to solutions supplied by the individual PSPs or third parties with which they have agreements, that were introduced to facilitate payments on current accounts and similar for citizens and businesses, was created according to the following guidelines:
- principle of neutrality: the pagoPA platform must make the same interfaces and technological integrations available to all PSPs with any personalization; therefore it is requested of all PSPs that have custom solutions to adapt to the new method, which is the only one available for the mandatory single payment model on the pagoPA platform;
- PSD2 compliance: currently the PSP that makes the payment instrument available (directly or via a third party) remains responsible for ensuring compliance with the current regulations on security, authentication (SCA) and banking best practices;
- clear rules described in the SANP: PagoPA S.p.A. has decided to list which payment methods permit transmission in redirect mode according to the principles that must be clear and described in the SANP (implementation specifications of the payment node).
NB: the payment methods, also if for payments made from a current account (e.g. mybank, BancomatPay, ...), that are natively integrated with the pagoPA payment gateway cannot be integrated in redirect mode.
A precondition of the PSP to be able to enable all the available payment instruments, including redirect, is the integration of the payment node according to the specifications of the single mode and definition of the information data catalog via the pagoPA backoffice, which is available in the reserved area.
The PSP must make the following interfaces available to the pagoPA platform:
- API recovery URL: exposed on the public network by the PSP and invoked by the pagoPA platform to recover the URL that the user’s browser will use to land in redirect mode, sending information in advance to the PSP about the payment that will be made;
- redirect: web page optimized for mobile devices where the user will land in redirect mode, which makes the payment authentication and authorization functions available. Following any payment outcome or cancellation by the user, this must trigger the outcome callback and the redirect to the pagoPA platform at the urlback indicated in the Api recupero url with the relative outcome;
- Transaction outcome callback API: API exposed by pagoPA and invoked by the PSP following any payment result of cancellation by the user that permits the correct closure of the transaction in progress that, being a redirect via the user’s browser, by definition is not a secure address;
- Cancellation API: API exposed by the PSP and invoked by pagoPA to request the cancellation of a payment whose outcome never arrived at the platform or in those residual cases where the payment was not finalized due to technical problems.
The connectivity follows the standard rules of the pagoPA platform, which can be consulted on Connectivity.
URL recovery API
Redirect
By means of the GET to the url supplied by the PSP in the response to the call Api recupero url, the user is redirected from the pagoPA platform to the FE of the PSP to authorize the payment.
For correct management, the PSP must use the information related to the payment sent from the pagoPA platform in the call Api recupero url.
Outcome
The payment workflow includes the following steps based on the payment outcome:
- redirect to the pagoPA page: once the payment is complete, the user will be redirected directly to pagoPA, to the address indicated in the urlBack parameter of theApi recupero url;
- server to server notice: a POST notice is sent to Api callback esito transazione to the address communicated during setup by PagoPA S.p.A.; to obtain the confirmation of reception of the notice, the message returned by the call must be an HTTP 200, otherwise it must be reproposed with a retry logic (https://github.com/pagopa/devportal-docs/blob/docs/from-gitbook/docs/DG2lpjf4Y5u7ZRFE7CyZ/appendices/quality-indicators-for-registered-entities/README.md#processi-di-retry).
Transaction outcome callback API
As described in the previous paragraph, it is the server-to-server API that the PSP must invoke in real time to notify the outcome of the payment to pagoPA.
The purpose of the API is to provide a final outcome, even if the redirect from the FE of the PSP to the pagoPA platform fails.
Cancellation API
This API must be exposed by all PSPs to make it possible for the pagoPA platform to cancel a payment in case of a technical error.
The pagoPA platform invoked this API to request the cancellation of a payment in the following cases:
- the outcome (positive or negative) never arrived at the pagoPA platform and, as a result, at the creditor;
- for technical problems, after the pagoPA platform received the positive outcome from the PSP, the telematic dialog between the pagoPA platform and the PSP was not possible or created a discordance with the PSP and as a result of this lack of dialog or discordance, the PSP did not acquire the data necessary for the credit to the creditor concerned with the transaction.
In the case as specified in point 1, the cancellation makes it possible to make the payment of the IUV (univocal payment identifier) subject to the cancellation available again.
In the case as specified in point 2, in addition to the effect specified above, the pagoPA platform cancels the positive outcome received from the PSP.
Each PSP must provide the url to invoke via the pagoPA backoffice for each environment (testing and production).
If there is no response with the outcome HTTP 200 (which has the value of a positive outcome of the response to the call), pagoPA is responsible for presenting the same call again with the retry logic.
The API has the characteristic of idempotency and the PSP must present the same outcome again also if it already previously processed the same request.
.png)
The pagoPA platform performs the cancellation call with the retry logic if it does not receive the outcome (positive or negative) of the payment within the timeout indicated in the response to the Api recupero url from the PSP or the default timeout of 10 minutes from the invocation of the redirect toward the URL of the PSP.
The pagoPA platform performs the cancellation call with the retry logic when the PSP responds KO to the Pspnotifypayment.
Tell us what you think
For clarifications on implementation specifications, such as SACI and SANP, you can open an issue on GitHub