Introduction

This page will describe PXP Financial's API framework for Payment Service Directive 2 (PSD2) compliance. Currently the instructions below apply to Visa, MasterCard, Amex and Diners.

The information in this document is supplemented by the following resources:

• PSD 2 Support at PXP Financial
• 3DS 2.0 Information Hub

PXP Financial PSD2 API Overview

With the PXP Financial PSD2 API you can:

• Override default or configured Policy behaviour
• Submit eligible exemptions for application during either Authorisation or Authentication
• Submit information to be used for specific payment use-cases such as follow-up recurring payments

📘

Backend-to-backend vs. Redirect (Checkout) API

The PXP Financial PSD2 API extensions are available for both integration options:

• Backend-to-Backend - using initiatePayment request
• Redirect (Checkout/Hosted Payment Pages) - using getRedirectData request

Note, a typical initiatePayment or getRedirectData request should also include the standard fields for 3DS2 authentication if SCA is going to be performed.

❗️

Define your PSD2 approach

PXP Financial recommends to use the API fields only if you have an extensive knowledge of PSD2 SCA regulations and the 3-D Secure protocol and are familiar with our Policy Framework.

Refer to the Merchant Decisions and Actions section of our PSD2 Support Page for guidance.

👍

PSD2 Implementation Checklist: Overview

• Contact PXP Financial Support if you require specific Policy behaviour to be configured using a Policy other than the default Policy
• Support 3DS2 to take advantage of the enhanced capabilities and benefits which are tailored for 3DS2: 3DS 2.0 Information Hub
• Ensure you have extended your system to take advantage of exemptions and out-of-scope PSD2 cases using the information in this Guide
• Ensure that your are prepared to handle a soft-decline response to a card payment and perform the relevant follow-up steps
• Optionally submit the PSD2 fields in the Payments.SpecificPaymentData section of the initiatePayment request or in the additionalData section of the getRedirectData request in order to control your SCA requirements on a per-transaction level

Default SCA behaviour with new API fields

The initiatePayment and getRedirectData requests have been extended with new fields applicable to PSD2.

Merchants will need to send these fields in addition to those that they usually send in order to meet SCA requirements.

Exemption Flagging

The table below lists instructions for the additional fields that should be sent in initiatePayment or getRedirectData requests to support exemption and out-of-scope handling when using the default policy provided by PXP Financial.

All fields should be provided in initiatePaymentRequest.specificPaymentData or getRedirectDataRequest.additionalData.

Recurring Payments

Recurring Payments have specific requirements for how they should be handled as part of the PSD2 mandate for both the initial payment and subsequent payments. This is covered in detail here.

Out-of-Scope Flagging

Out-of-scope Flagging only applies for backend-to-backend integrations (initiatePayment).

Custom SCA behaviour with new API fields

The initiatePayment and getRedirectData requests have been extended with new fields applicable to PSD2.

Merchants will need to send these fields in order to control their SCA preferences if the default behaviour is not sufficient.

The table below lists the additional fields that can be sent in initiatePayment or getRedirectData request. All fields should be provided in initiatePaymentRequest.specificPaymentData or getRedirectDataRequest.additionalData:

The following table describes various scenarios showing how the parameters can be applied:

Managing specific payment scenarios

Summary of supported payment scenarios per Scheme

Merchant Initiated Transactions (MITs)

📘

MITs - relating payments with the Scheme Transaction reference

MITs are transactions made without the presence of a cardholder using stored card information. Card-On-File (COF) payments and Recurring payments are two of the most common examples, and while MITs are treated as out-of-scope for PSD2, there are specific requirements about their correct usage which must be met.

PXP Financial has made available a new API detail to store the unique transaction references (the Visa/Amex Transaction ID, Diners Network Reference ID and MasterCard Banknet Reference Number respectively) in order to meet the PSD2 requirement for dynamic linking.

This allows for recurring payments and stored credential payments agreements to be related to the initial payment in the agreement sequence.

The name of the detail is SchemeTransactionIdentifier for Visa/MasterCard/Amex and DinersRetrievalReferenceNumber for Diners.

This detail will need to be enabled by PXP Financial Support once you have indicated that you are ready to use it.

📘

Merchants using the PXP Financial Checkout who want to use MITs

Merchants using the PXP Financial Redirect integration (Checkout/Hosted Payment Pages) can also take advantage of MITs by integrating a combination of Checkout and backend-to-backend:

• Merchant should redirect customers that want to pay with a new card to the Checkout
• Merchant should store the created payment credentials (token/payment account) and if a customer wants to pay with stored credentials use the backend-to-backend integration to transmit a COF/MIT transaction

MITs: Handling Recurring Payments

PXP Financial offers both an internal Recurring Payment Service and the ability to pass through recurring payments. See Set up Recurring Payment for more details.

This section provides more details on specific PSD2 mandate requirements for recurring payments and how they can be met.

When a recurring payment is set up, then SCA must take place. Following successful authorisation, the Scheme Transaction reference of the initial payment is returned/can be retrieved:

• In case of a backend-to-backend integration, the SchemeTransactionIdentifier field will be returned in the initiatePayment response
• In case of a Checkout integration, the SchemeTransactionIdentifier field will be sent in the handlePaymentStateChangedNotification and/or can be retrieved via the getPayments request.

For subsequent payments which are not initiated with the cardholder present, SCA will not apply. For such payments use SchemeReferenceTransactionIdentifier to refer to the initial payment used to set up card on file payment.

The table below describes the parameters which need to be submitted in initiatePaymentRequest or getRedirectDataRequest to set up a recurring payment:

The table below describes the parameters which need to be submitted in initiatePaymentRequest for a subsequent recurring payment:

MITs: Handling Card on File (COF) Payments

This section is only applicable for backend-to-backend integrations.

When a COF payment is set up and the user's payment account information is stored, authentication is necessary. When a follow-up payment is made as a MIT, authentication is not necessary.

However if the follow-up payment is initiated by the cardholder, which will be a Cardholder-Initiated Transaction (CIT) with creationTypeID = 11, then it will need to be authenticated.

📘

Scheme rules for setting up cardholder agreements for MITs and CITs

Please note that MasterCard and Visa have different approaches to SCA being required during storage of credentials when a cardholder agreement is set up:

• MasterCard requires SCA in all cases
• For Visa, SCA is required when the agreement is being set up and credentials are stored for future MITs, but not for future CITs. However, Visa does highly recommend SCA in the latter scenario.

Use the creation type MerchantInitiatedWithStoredAccount (creationTypeID = 10) to indicate the subsequent MIT and provide the SchemeReferenceTransactionIdentifier of the initial payment for a subsequent COF payment. This Identifier is returned in SchemeTransactionIdentifier field in the initiatePayment response for the initial set-up payment.

See Creation Types and Card On File Deposits (with Tokenization) for more details on how PXP Financial has implemented the MIT framework.

The table below summarises the expected behaviour:

White-listed transactions/Trusted Beneficiary

During the SCA process, a merchant can be white-listed by a cardholder so that future payments made by that cardholder for that merchant, do not need to go under SCA and can make use of the Trusted Beneficiary exemption.

Not all card issuers will support white-listing so this feature will only be possible to make use of where supported.

Request White-list

In order to request a whitelist set-up during a 3DS2 Challenge, submit the following fields in the initiatePayment or getRedirectData request:

Receive White-list result

The result of the white-listing can be received after a successful challenge.

• In case of a backend-to-backend integration, the fields in the below table will be sent in the executeAction response.
• In case of a Checkout integration, the fields in the below table will be sent in the handlePaymentStateChangedNotification and/or can be retrieved via the getPayments request.

Use White-list Exemption

Once the White-list has been set up, use it by submitting the following values in the initiatePayment request:

Managing soft declines

When a merchant requests an SCA exemption and it is applied directly in the authorisation message without authentication being carried out beforehand, the transaction may be declined by the issuer with the response code 65.

This indicates a soft decline, which means that the issuer has requested that the transaction must be authenticated. In order to avoid another soft decline, the merchant will need a mechanism to retry the payment with the same card details and ensure that SCA take place.

🚧

Default Policy and Soft Declines

Our Default Policy will apply an LVP in authorisation whenever possible. Since a soft decline will be sent by an Issuer when either the cumulative total amount of transactions since the last SCA took place exceeds 100 EUR or the number of transactions exceeds 5, merchants must be aware of how to force SCA on the next transaction to avoid further soft declines. Read on for more information.

Soft declines: Force SCA with 3DS2

The merchant has to initiate a new payment by sending initiatePayment with all necessary data to perform a 3DS2 authentication and either a new MerchantTransactionID, or the same MerchantTransactionID together with the ProviderID supplied in the request.

The merchant should ensure that they set a challenge indicator in the follow-up payment which will mandate SCA. The value of ScaChallengeIndicator should be set to 4 for this purpose. Please refer to the Custom SCA Behaviour section for more information on triggering a challenge.

The merchant must not request a new exemption following a soft decline.

Automatic Soft declines handling in Checkout

📘

Automatic Soft Declines Handling in PXP Financial Checkout

The PXP Financial Checkout is able to handle Soft Declines automatically for the merchant.

To have this feature activated, the merchant has to contact the PXP Support or his PXP Account Manager.
Please note that this feature is not available for Amex payments.

In case the issuer refused the card payment which a customer/player made in the checkout with response code 65 (and the payment was not authenticated with 3DS), checkout will automatically trigger an additional payment and forcing a challenge to be made.
The customer remains in Checkout and will see a spinner while he waits. The 3DS input screens will be displayed and he will be able to perform the authentication.

In case the authentication was successful and the issuer authorizes the payment, the customer is redirected back to the merchants success-URL. In addition a backend notification is sent.
In case of another refusal, the customer is redirected to the merchants error-URL (Note: Checkout only does one retry, if the second payment also fails, Checkout will not try again but redirect to Error-URL).

❗️

Handle State Change Notifications for Soft declines handling in Checkout

Usually a merchant receives state change notifications from PXP System only for successful payments.
In case a merchant is also configured to receive notifications for refused payments, merchants have to ensure that they are able to handle the following:

In the case that Checkout has applied the automatic soft-declines handling, two state change notifications will be received by the merchant.
The first notification (RefusedByProvider) is usually already received while the customer is still in the Checkout and doing the authentication for the second payment.
Merchant system needs to wait until the customer is redirected to the Success-URL and a state change notification is received for the second payment.
In case also the second payment is refused, customer is redirected to Error-URL and the merchant system will receive a notification also for the second refusal.

Details about the two state change notifications:

• The notification for the first payment will have state “RefusedByProvider” and response code 65
• The notification for the second payment will have the state “AuthorisedByProvider”
• Both payments will have the same merchant-transaction-id (PaymentID)
• But the payments will have different UniqueIDs and ProviderExternalIDs

The below diagram shows the system interaction when Checkout handles the soft decline - successful case.
Please note that the asynchronous state change notifications could also be received by the merchant system in a different order.

Existing 3D Secure Flags in the initiatePayment Request

Merchants with a backend-to-backend integration and/ or Redirect (Checkout) need not send the IsThreeDSecureRequired = true flag in the initiatePayment/ redirectData request. The decision for triggering Strong Customer Authentication (SCA) is now controlled by the SCA Policies.

Only merchants that do not have PSD2 enabled must send the IsThreeDSecureRequired = true flag in the initiatePayment request in order to correctly trigger the 3DS2 flows. Alternatively, to trigger 3DS Authentication for out-of-scope PSD2 transactions, the merchant can determine the conditions under which this occurs using our Smart 3DS functionality. Use the IsThreeDSecureConditionalRequired flag to trigger Smart 3DS.

❗️

Existing flags for 3DS when PSD2 goes live

Originally, the IsThreeDSecureRequired flag was planned to be deprecated in the PXP Financial API following the full transition to PSD2. This is no longer the case.

It is important to note that the flag is still required in the initiatePayment request when:

• PSD2 is activated for the merchant and there are Card Verifications* used for initial storage of card details or for standard verification (without storage)
• PSD2 is not activated for the merchant, and the merchant operates outside EEA but the merchant wants to authenticate payments (including non-Card Verifications)
  *Payment methods: 202 - VisaCardVerification, 203 - ECMCCardVerification, 215 - MaestroCardVerification

Note: The IsThreeDSecureConditionalRequired was going to be deprecated but this is no longer the case as it will be used to apply Smart 3DS rules. please note, the IsThreeDSecureConditionalRequired flag cannot be used in conjunction with IsThreeDSecureRequired flag because they are mutually exclusive.

🚧

Using Smart 3D Secure when SCA is required

When Strong Customer Authentication is required for a payment, then Smart 3D Secure is not applicable.

Pass-through Payments

Pass-through Payments only apply to backend-to-backend integrations.

3DS 2.0 Pass-through payments are payments which have made use of a third-party 3DS Server or 3DS MPI to complete the SCA process, but will be authorised through PXP Financial.

Such payment transactions proceed directly to authorisation but contain the relevant fields to ensure that the valid Authentication outcome is submitted to the Card Schemes, such as the CAVV.

For 3DS2 payments which have undergone SCA, if an exemption has been granted during authentication, it must be flagged in the initiatePayment request.

For more information about how to flag granted exemptions for pass through payments refer to the Integration Steps section.

❗️

Granted Exemptions Flagging

Please note that sending an exemption in a pass-through payment means that the exemption was already granted during the SCA process with the third-party 3DS provider.

Sending an exemption that hasn't been granted during authentication may lead to potential decline of the transaction by issuer.

In addition, sending either the Anonymous Card or Secure Corporate Card indicator in initiatePayment for a pass-through payment will result in a validation error.

Using different acquirers in authentication and authorization

By default, merchants should use the same acquirer for both authentication and authorization. In a multi-acquirer scenario, especially in a retry scenario, it might be necessary to use the same authentication result for multiple authorization attempts.

PXP can support such use cases with

• Stand-alone authentication for use with other acquirers.
• Authentication is done with another partner, authorization is done with PXP, passing the authentication result (“pass-through”)
• Authorisation can be done with multiple acquirers integrated into the PXP host. In this case you would need to pass the desired acquirer ID (‘ProviderID’ in PXP terms)

If you are interested in that option, you can contact PXP Financial Support for more information.