Security Best Practices
Validation of the Security Token
The securityToken parameter must be verified for every notification received from XPay. During payment initialization, XPay returns a value called securityToken that uniquely identifies the transaction. The same value is subsequently included in the server-to-server notifications sent to the notificationUrl endpoint configured by the merchant. Upon receiving a notification, the merchant's system must compare the received securityToken with the value previously stored during transaction initialization. Only if there is a match can the notification be considered valid and used to update the order status or trigger further application processing. Notifications containing a securityToken that differs from the one associated with the transaction, that is not present in the merchant's systems, or that cannot be verified must be considered untrustworthy and must not be processed. Validation of the securityToken constitutes a fundamental check to verify that the notification received actually relates to a transaction previously initialized through the XPay platform, and must be implemented for all integrations that use the server-to-server notification mechanism.
IP Address Whitelisting
As an additional protective measure, it is recommended to restrict access to notification endpoints to requests coming solely from XPay infrastructure. Implementing whitelisting rules at the firewall or application infrastructure level helps reduce the risk of receiving requests from unauthorized sources and constitutes an additional layer of defense against spoofing attempts or misuse of publicly exposed endpoints. The IP addresses from which notifications are sent were listed in the following section: Specifications for outcome notification
Merchants are encouraged to periodically check the official documentation for any updates regarding the service delivery infrastructure. The use of IP whitelisting should not replace other security mechanisms, but should be adopted in combination with securityToken validation and the other checks described in this section.
Verification of Payment Outcome
The browser redirect to the resultUrl must not be used as the primary source for determining the outcome of a transaction.
Completion of the redirect depends on the user's browser, the availability of the network connection, and the successful completion of the client-side interaction. In some scenarios the customer might interrupt the payment flow, close the browser, or fail to properly reach the return page even though the transaction was authorized or settled correctly.
Server-to-server notifications sent to the notificationUrl endpoint are asynchronous with respect to the completion of the payment process and are delivered using a fire-and-forget mechanism. This means that XPay does not automatically retry notification delivery if it fails due to network issues or temporary unavailability of the merchant's endpoint.
For this reason, once the customer is redirected back to the merchant's website, merchants are recommended to verify the transaction status by calling the GET /orders/{orderId} API. If the authorization operation is not yet available, it is advisable to wait a few seconds before issuing a new request to determine the final payment outcome.
Server-to-server notifications should therefore be considered an additional asynchronous mechanism for updating the transaction status, complementing the verification performed through the XPay APIs.
Operational decisions regarding order status updates, the delivery of goods or services, or the execution of automated processes must not be based solely on the browser redirect.
The resultUrl should therefore be regarded primarily as a navigation and informational tool for the end user, while the actual payment status should be determined through backend API calls to the XPay platform.
Security of Notification Endpoints
The endpoints designated to receive payment notifications constitute a particularly sensitive element of the integration and should therefore be designed and maintained according to appropriate security criteria. It is recommended that these endpoints be exposed exclusively via HTTPS protocol and configured to accept only HTTP POST requests coming from authorized systems. Before processing a received notification, the application should verify the correctness and presence of the main transaction identification parameters, including securityToken, eventId, operationId, orderId, and eventTime. Similarly, malformed, incomplete, or non-compliant requests should be rejected without initiating any application processing. In order to reduce exposure to possible abuse or automated attacks, it is also recommended to implement appropriate traffic monitoring mechanisms, rate limiting, and timeout management.
Idempotency and Handling of Duplicate Notifications
In a distributed context it is possible for the same notification to be transmitted more than once due to automatic retransmissions, temporary network issues, or momentary unavailability of the systems involved in the communication. For this reason, applications that receive notifications from XPay should be designed according to idempotency principles. Repeated processing of the same notification should not produce side effects nor generate multiple changes to the order status. To this end, it is recommended to keep track of the identifiers received, such as eventId and operationId, so as to be able to recognize and, where appropriate, ignore notifications already processed previously.
Credential Management
Protecting the credentials used to access XPay services is the merchant's responsibility.
API keys, transaction Security Tokens, any certificates or cryptographic keys used for the integration, and any other application secrets should be stored exclusively within dedicated secure credential management systems and should not be included in source code or exposed within frontend applications.
Access to production credentials should be restricted to authorized personnel according to the principle of least privilege.
API keys should be rotated periodically, preferably at least once a year or immediately in the event of a suspected compromise, following the procedure described in the XPay Back Office documentation. This procedure consists of generating a new API key, updating it across all merchant systems, verifying that the new key is working correctly, and only then disabling the previous key.
It is also advisable to monitor credential usage in order to promptly identify any anomalies or unauthorized use.
Secure Logging
To facilitate monitoring, troubleshooting, and security analysis activities, it is recommended to log at least the following information, consistent with the entities exposed by the XPay APIs (orders, operations, notifications): • eventId • operationId (identifier returned by the Back Office APIs, for example when querying operations, refunds, captures, or cancellations) • orderId (order identifier, also used in the order query APIs) • eventTime • transaction status • processing timestamp • outcome of the checks performed • source IP address These elements are particularly important for the server-to-server notifications sent by XPay to the merchant's endpoint, as they make it possible to reconstruct the chain of events in the event of anomalies, disputes, or the need for subsequent verification.
Evidence Retention
Logs and audit information should: • be protected from unauthorized modification; • be retained in accordance with applicable company policies; • allow for potential forensic analysis activities. Sensitive information should not be logged unless strictly necessary, particularly card data, which — especially in Hosted Payment Page and XPay Build integrations — should never pass through or be stored on the merchant side, remaining confined to XPay systems.
Merchant Responsibility
The security of the merchant's infrastructure and applications remains the exclusive responsibility of the merchant. This responsibility includes, by way of example: • protecting the notification endpoints, in particular those that receive server-to-server notification calls from XPay regarding transaction outcomes; • validating received notifications, to ensure they actually originate from Nexi systems and have not been altered or falsified; • implementing idempotency controls, to correctly handle any duplicate notifications; • secure management of credentials (API keys and other secrets); • secure configuration of network infrastructure, including any firewall rules that could otherwise block notifications sent from Nexi servers; • system monitoring; • applying security updates and patches. Failure to implement adequate security measures could expose the merchant's systems to operational and security risks, even in the presence of Nexi infrastructure that is compliant and continuously verified.
Security Standards and Industry Best Practices
XPay continuously evaluates the evolution of security standards, cyber threats, and industry best practices in order to maintain a secure and reliable payment ecosystem. All transmissions of sensitive data involving the merchant, Nexi systems, and the end customer are encrypted according to the HTTPS protocol, in line with the standards imposed by the International Card Schemes and the PCI-DSS standard; Nexi systems are also subject to periodic security assessments and constant updates for protection against known vulnerabilities in standard protocols. Security recommendations and guidance may be updated over time to reflect the evolution of technologies, regulatory requirements, and market standards. Merchants are advised to periodically consult the updated technical documentation available on the Nexi Developer Portal (developer.nexi.it).
PCI DSS Compliance and Security Standards
XPay operates within an environment compliant with PCI DSS requirements and implements the security controls and operational procedures required by applicable industry standards, as well as additional regulatory frameworks where applicable (such as DORA).
Depending on the selected integration model, merchants may be subject to different PCI compliance responsibilities.
The PCI Security Standards Council recommends that merchants identify the appropriate level of PCI compliance required for their integration and complete the relevant Self-Assessment Questionnaire (SAQ) or certification process.
In particular:
- PCI SAQ A for Hosted Payment Page (HPP) integrations.
- PCI SAQ A-EP for XPay Build integrations.
- PCI SAQ D for Server-to-Server integrations where payment card data is handled by the merchant's systems.
Merchants are encouraged to implement the security measures described in these guidelines and to choose the integration model that best suits their business needs while considering the level of PCI responsibility associated with each integration.