Table of contents
Best practices
The use of the payment token has the following two objectives:
- defining a payment session temporally;
- having a identifier generated by the pagoPA platform that permits the end to end identification of a payment session.
The default value for the duration of the payment token is a common configuration at the level of the entire pagoPA platform and cannot be higher than 30 minutes. This parameter can be overwritten by the PSP, with a value lower than 30 minutes, in the expireTime field entered in the request of the activatePaymentNotice, and the value must be expressed in milliseconds.
It is essential for each PSP to identify the best expiration value of the token with respect to the type of channel the user uses to pay the notice.
The default value of the duration of the payment token can be redefined based on the monitoring results. The update is communicated by publishing a minor version of this document.
The payment token is provided in response by the pagoPA platform to an activatePaymentNotice, and must be inserted by the PSP in the request to the sendPaymentOutcome and take on the meaning of identificativoUnivocoRiscossione in the reporting flows.
For a correct management of every payment session for every activatePaymentNotice, a sendPaymentOutcome must always follow, both in an OK and in a NOK case, in real time with respect to the user's actions at the touch point of the PSP. This is essential for ensuring a good service quality along the entire chain.
After receiving a response from the Node, the sendPaymentOutcome must not be invoked again, to take care of the cases in which a response is not received, Idempotency key must be used
Only in the case of technical exceptions, the sendPaymentOutcome is not received from the platform simultaneously with the payment, and therefore if the payment token is sent after expiration, it is possible that the cases identified by the following responses supplied by the pagoPA platform apply
| Platform response | Meaning |
|---|---|
| OK | The payment outcome notification took place before the expiration of the token. |
| PPT_TOKEN_SCADUTO | The payment outcome notification took place after the expiration of the token and the platform does not recognize simultaneous payments. |
| PPT_TOKEN_SCADUTO_KO | The notification with the NOK outcome of the payment took place after expiration of the token, in that case the Node does not check the status of the debt position. |
| PPT_PAGAMENTO_DUPLICATO | The payment outcome notification took place after the expiration of the token and the platform detects another payment for the same position. |
As concerns the OK case, no corrective action is necessary.
As concerns the PPT_PAGAMENTO_DUPLICATO case, the correct action to be done on the PSP side is to return the amount to the user.
As regards the PPT_TOKEN_SCADUTO error, the actions to take by the PSP differ depending on the cases:
- in the case of a Payment at the creditor's frontend orpayment-from-pagopa-touchpoint, the error indicates that the payment was not successful and the correct action to take on the PSP side is to return the amount to the user;
- in the case of a Payment of a notice through a PSP, the platform is not able to detect concurrent payments and the correct action to take on the PSP side is to report the payment to the creditor with code 9, if the payment process was managed in Stand In mode, code 8 must be used.
In the case of PPT_TOKEN_SCADUTO_KO, the corrective action to be taken by the PSP is to manage the flow in a temporary manner, in compliance with the duration of the payment token.
sendPaymentOutcome OK
In the case of an OK result of the sendPaymentOutcome the PSP is required to specify the following fields, which therefore are mandatory in case of an affirmative response:
- paymentMethod: specifies the payment method that was used;
- fee: indicates the amount of the commission payed in euros;
- entityUniqueIdentifierType: identifies the type of person making the payment (G or F);
- entityUniqueIdentifierValue: indicates the fiscal code or VAT no. of the person making the payment, if they are not available 'ANONYMOUS' can be used;
- fullName: complete name of the payer;
- applicationDate: application date of the payment;
- transferDate: date of the transfer to the creditor.
Idempotency key
The idempotency key can be generated by the PSP for the calls:
The purpose of the idempotency key is to make it possible to invoke a call multiple times without any side effect regarding the status of the payment. It is mandatory to insert the idempotency key in the requests of the calls that manage it, and the purpose of this instrument is limited to cases in which a response was not received, for any reason, from an idempotency call.
The concept of managing the payment session must not be associated with the idempotency key for any reason which must in fact take place through the correct use of the payment token.
If a PSP, for example, does not receive the response to the activation of the payment, it can repeat the same call, making sure to use the same idempotency key in order to obtain the data that was intended for them during the first call. If the same idempotency key is not used, the response will instead be “payment in progress” and it will not be possible to proceed with the payment.
The rule for generating the idempotency key is <CF_PSP> + "_" + <RANDOM STRING>.
The duration of the idempotency key is set by the pagoPA platform based on a configuration common to all the PSPs. In the case of the activatePaymentNotice the maximum duration may not exceed that of the payment token._
In the case of activatePaymentNotice the idempotency key must be invalidated, not only after the expiration of the key, but also when receiving an outcome for the payment token generated during the activation.
Once the idempotency key has expired, it can be reused.
The platform checks that the idempotency key is used correctly, and in case of an error the fault code PPT_ERRORE_IDEMPOTENZA is returned, and the input parameters are checked according to the following table.
| Idempotency key | Other parameters | Action |
|---|---|---|
| Can be associated with an original request | Equal to an original request | No side effects + original response |
| Can be associated with an original request | Different than an original request | NOK: improper use of the idempotency key |
| Cannot be associated with an original request | Indifferent | It is, for all purposes, a new request |
Tell us what you think
For clarifications on implementation specifications, such as SACI and SANP, you can open an issue on GitHub