PSD2 and 3DSv2

What is PSD2?

PSD2 is the second European directive on online payment services in the European Union and United Kingdom. It entered into force on 14 November 2020. Its goals are:

  • To make online payments more secure in Europe. 
  • To promote innovation.
  • To encourage banking services to adapt to new technologies.

With this new regulation, non-secure operations are not allowed for cards issued within the European Economic Area (EEA). Therefore, operations by non-secure merchants (without authentication) with European cards will be declined. 

Advantages of PSD2 regulation

The two main advantages of this directive are:

  • More secure transactions with a lower risk of fraud. This is possible thanks to the double authentication or strong authentication system.
  • Increased customer confidence in online payments. This allows the e-commerce sector to grow and generate a more varied and higher quality offer for its consumers.

Strong customer authentication (SCA) under PSD2

Strong customer authentication (SCA) seeks to strike a balance between comfort and security. So, at least two (2) of these elements must be used: 

  1. Something only the customer knows, like a PIN or password.
  2. Something only the customer possesses, such as a smartphone where they can receive a single-use code.
  3. Something that is an inherent part of the customer, such as a part of their body that can be used as a biometric security measure (fingerprint, iris, facial recognition, etc.).

Operations that require strong customer authentication (SCA)

Strong customer authentication seeks to verify the customer’s identity and prevent fraud. It is required when:

  • Buying from an ecommerce site in the European Union.
  • You enter your bank card details on an ecommerce site for future online payments (even if you don’t use it at that time).

EMVCo and 3DSecure v.2

For the roll-out of the PSD2 directive and SCA, EMVCo developed an updated version of its card transaction authentication standards (3DSecure). It is called 3DSecure v.2 (3DSv2 hereinafter). It has the following advantages:

  • No more static passwords: Customers no longer have to remember a password, which makes the payment process more comfortable.
  • Two-factor authentication: 3DSv2 uses two-factor authentication. To make the experience more comfortable for customers, this authentication can include a fingerprint or biometric reading on their phone, for example.
  • Fewer false declines: The new protocol gives issuers ten times more information, which helps drastically reduce the number of false declines.
  • Fewer false declines: Customers are no longer redirected to authorization pages that may not be prepared for mobile devices.
  • Fewer abandoned carts: A faster payment process and easier purchasing experience reduce the number of abandoned carts by 70%.
  • Merchant opt-out flexibility: Merchants can choose which transactions are processed through 3DSv2 and which aren’t. However, remember that issuers may decline transactions not authenticated if they require SCA.
  • This protects the merchant from liability in cases of fraud. This is the same with 3DSv1.

Frictionless and challenge authentication – 3DSv2

With 3DSecure v.2 there are two customer-authentication methods:

  1. Frictionless authentication. The issuer decides that the transaction is a low fraud risk and authorizes it itself without customer SCA.
  2. Challenge authentication. The issuer decides that the transaction is a medium/high fraud risk and requires the customer be redirected to an SCA URL for SCA as a condition of authorization.

Frictionless authentication and authorization

  1. Enter card data.
  2. Redirect to issuing bank for authentication.
  3. Redirect customer to your ecommerce platform with the result of the authentication/authorization.

Challenge authentication and authorization

  1. Enter card data.
  2. Redirect to issuing bank challenge for authentication.
  3. Redirect customer to your ecommerce platform with the result of the authentication/authorization.

Authentication status 3DS2

Using 3DS2, authentication is used to reduce fraud in card transactions. The status of this authentication is indicated in the “eci” field of the notification. Depending on this status, the financial liability for a transaction may be on the side of the card issuer or the merchant.

There are some differences depending on the card brand, see the table below for details. To learn more about notifications visit the Notification Management documentation.

Card3DSv2 statusDescriptionECICAVVResponsibilityRecommended action
Visa, Amex, JCBYAuthenticated05YesIssuerRequest authorization
Visa, Amex, JCBAAuthentication attempt06
Visa, Amex, JCBNNot authenticated07NoMerchantDo not request authorization
Visa, Amex, JCBUAuthentication not available
Visa, Amex, JCBRAuthentication declined
MasterCardYAuthenticated02SíIssuerRequest authorization
MasterCardAAuthentication attempt01
MasterCardNNot authenticated00NoMerchantDo not request authorization
MasterCardUAuthentication not available
MasterCardRAuthentication declined

Parameters introduced in 3DSecure v.2

EMVCo has introduced new parameters with 3DSecure v.2 to more efficiently assess the risk of fraud in card transactions. This attempts to collect as much information as possible on the customer’s profile and activity on the merchant’s platform.

Information from customer’s web browser

Required only for integrations that don’t delegate this step to AP. To get some data from the browsers below, you can use the following JavaScript code:

				
					function datos_navegador() {function datos_navegador() {
document.getElementById("agente_navegador").value = navigator.userAgent;
document.getElementById("idioma_navegador").value = navigator.language;
document.getElementById("altura_pantalla").value = screen.height;
document.getElementById("anchura_pantalla").value = screen.width;
document.getElementById("profundidad_color").value = screen.colorDepth;
var d = new Date();
document.getElementById("diferencia_horaria").value = d.getTimezoneOffset();
}
ParameterDescriptionFormat and values accepted
acceptHeaderHTTP “Accept” order header for the customer’s browser. Highly recommended to avoid being rejected by issuer’s SCA server.
Alphanumeric, max 2048 characters.
browserIpIP address for the customer’s browser.Alphanumeric, max 45 characters.
Format: IPv4 or IPv6.
browserLanguageLanguage on the customer’s browser, in IETF-BCP47 code. Can be obtained from the property “navigator.language”.Alphanumeric, max 8 characters.
challengeWindowSizeSize of the window the customer sees for the authentication (challenge).
The SCA has to adapt the content to the window size.
The sizes shown are width x height in pixels.		01: 250×400
02: 390×400
03: 500×600
04: 600×400
05: Full screen (default).
javaEnabledShows whether Java is enabled on the customer’s browser. It is required if “jsEnabled” is true.
Can be obtained with the function “navigator.javaEnabled()”.		Boolean
jsEnabledShows whether Java is enabled on the customer’s browser.Boolean
screenColorDepthDepth of colour on the customer’s screen. It is required if jsEnabled is true.
Can be obtained from the property “screen.colorDepth”. 		Whole number
1, 4, 8, 15, 16, 24, 30, 32 y 48.
screenHeightTotal height of customer’s screen in pixels. It is required if “jsEnabled” is true.
Can be obtained from the property “screen.height”.
Whole number.
screenWidthTotal width of customer’s screen in pixels. It is required if “jsEnabled” is true.
Can be obtained from the property		Whole number.
tzOffsetTime difference in minutes between UTC and the local time on the customer’s browser. Positive if local time is behind UTC. Negative if ahead.
It is required if “jsEnabled” is true.
Can be obtained with the function “”getTimezoneOffset()””.		Whole number.
userAgentUser agent for the customer’s browser. Provides information on the browser being used.
Highly recommended to avoid being rejected by issuer’s SCA server.
Can be obtained from the property “navigator.userAgent”.
Alphanumeric, max 256 characters.

Parameters to get other information

Below are the parameters to get the rest of the customer information:

ParameterDescriptionFormat and values accepted
accountAgeAge of the customer’s account on your ecommerce platform.Numerical, the values accepted are:
01: Doesn’t have an account (guest).
02: Created today.
03: Created less than 30 days ago.
04: Created between 30 and 60 days ago.
05: Created more than 60 days ago.
accountChangeDateDate the customer last made changes to their account, such as changing the shipping or billing address, card, email address, etc.
Don’t send this field if the customer uses a guest account.
Alphanumeric. Format YYYY-MM-DD.
accountChangeIndTime passed since the customer last made changes to their account. Don’t send this field if the customer uses a guest account.Numerical.
The values accepted are:
01: Today.
02: less than 30 days.
03: between 30 and 60 days.
04: more than 60 days.
accountCreationDateDate the customer created their account on your ecommerce platform.
Don’t send this field if the customer uses a guest account.
Alphanumeric. Format YYYY-MM-DD.
passwordChangeDateDate of the last change to the password on the customer’s account.
Don’t send this field if the customer uses a guest account.
Alphanumeric. Format YYYY-MM-DD.
passwordChangeIndTime since the user last changed the password on their account.Numerical.
The values accepted are:
01: Doesn’t have an account (guest).
02: Created today.
03: Created less than 30 days ago.
04: Created between 30 and 60 days ago.
05: Created more than 60 days ago.
paymentAccountAgeDate the customer registered the payment account (card) on their account on your platform.
Don’t send this field if the customer uses a guest account.
Numerical. Format YYYY-MM-DD.
paymentAccountIndTime since the customer registered the payment account (card) on their account on your platform.The values accepted are:
01: Doesn’t have an account (guest).
02: During this transaction.
03: Less than 30 days ago.
04: Between 30 and 60 days ago.
05: More than 60 days ago.
provisioningAttemptsDayNumber of cards the customer has attempted to add to their account on your platform for payments in the past 24 hours.
Don’t send this field if the customer uses a guest account.		Numerical. Max 999.
purchasesLast6MonthsNumber of authorized payments the customer has made on your platform in the past six (6) months.
Don’t send this field if the customer uses a guest account.
Numerical. Max 999.
shippingAddressUsageDate the customer entered their current shipping address on your platform.
Don’t send this field if the customer uses a guest account.
Alphanumeric. Format YYYY-MM-DD.
shippingAddressUsageIndTime since the customer entered their shipping address on your platform.
The values accepted are:
01: Today.
02: Less than 30 days ago.
03: Between 30 and 60 days ago.
04: More than 60 days ago.
shippingNameIndShows whether the cardholder’s name matches the name on the shipping address.Boolean.
The values accepted are:
true: The cardholder name is the same as the shipping address.
false: The cardholder name isn’t the same as the shipping address.
suspiciousAccountActivityIndMust show whether your platform has detected suspicious activity by the customer.Boolean.
The values accepted are:
true: Suspicious activity has been detected.
false: No suspicious activity has been detected.
txnActivityDayNumber of transactions (authorized, declined or cancelled) that the customer has made in the past 24 hours on your platform.
Don’t send this field if the customer uses a guest account.
Transactions indicated by your platform not counted automatically.		Numerical. Max 999.
txnActivityYearNumber of transactions (successful, failed or cancelled) the customer has made in the past year on your platform.
Don’t send this field if the customer uses a guest account.
Transactions indicated by your platform not counted automatically.		Numerical. Max 999.
ParameterDescriptionFormat and values accepted
deliveryEmailFor virtual products, give the email address the goods will be sent to.Alphanumeric, max 254 characters.
deliveryTimeframeWhen the order purchased by the customer will be delivered.Whole number.
The values accepted are:
01: Electronic delivery.
02: Same-day delivery.
03: Next-day delivery.
04: Delivery in two (2) days or more.
shippingAddress1First line of shipping address. You should send it even if it is the same as the billing address.
Required (whenever available) except when restrictions, regional or sector laws prohibit sending this information.		Alphanumeric, max 50 characters.
shippingAddress2Second line of the shipping address. You should send it even if it is the same as the billing address.
Required (whenever available) except when restrictions, regional or sector laws prohibit sending this information.		Alphanumeric, max 50 characters.
shippingAddressMatchShows whether the shipping address and billing address match.Boolean.
The values accepted are:
true: The shipping and billing addresses match.
false: The shipping and billing addresses don’t match.
shippingCityShipping address city. You should send it even if it is the same as the billing address.
Required (whenever available) except when restrictions, regional or sector laws prohibit sending this information.		Alphanumeric, max 50 characters.
shippingCountryShipping address country. You should send it even if it is the same as the billing address.
Required (whenever available) except when restrictions, regional or sector laws prohibit sending this information.		ISO 3166-1 alpha-2 code (ES, US, UK, etc.).
shippingMethodIndShipping method chosen by the customer.
Should describe the shipping method chosen for the transaction in as much detail as possible, not the merchant’s activity in general.
If it includes physical and digital products, give the shipping code for the physical products.
If all the products are digital, give the shipping code for the most expensive item.		The values accepted are:
01: Main shipping address on the customer’s account.
02: Shipping to another address stored on the customer’s account.
03: Shipping to an address not stored on the customer’s account
04: Collect at merchant / ship to pick-up point.\n05: Digital goods (includes electronic services, gift vouchers/codes, etc.).
06: Tickets to events or electronic travel tickets.
07: Other (for example, videogames, electronic subscriptions, etc.)
shippingPhoneCustomer’s phone number for shipping.Alphanumeric.
shippingStateProvince or state on the customer’s shipping address.
Only the state or province, not the country.
You should send it even if it is the same as the billing address.
Required (whenever available) except when restrictions, regional or sector laws prohibit sending this information.
Not required if the country doesn’t use provinces or states.		ISO 3166-2 code. Max two (2) characters
shippingZipCodePostcode on the shipping address.
You should send it even if it is the same as the billing address.
Required (whenever available) except when restrictions, regional or sector laws prohibit sending this information.		Alphanumeric. Max 16 characters.
ParameterDescriptionFormat and values accepted
challengeIndIndicates the preference set by the merchant for an authentication process. The issuer can modify the preference specified in this field.Numerical.
The values accepted are:
01: No preference. (default value if this parameter is not sent)
02: Avoid challenge.
03: Require challenge (merchant preference).
04: Require challenge (required).
05: Avoid challenge (Transaction risk analysis conducted).
06: Avoid challenge (only on share data).
07: Avoid challenge (SCA already completed).
08: Avoid challenge (use whitelist exemption).
09: Avoid challenge (request whitelist).
ParameterDescriptionFormat and values accepted
giftShows whether the product purchased is a gift voucher or prepaid card.Boolean.
The values accepted are:
true: The order includes gift vouchers or prepaid cards.
false: The order doesn’t include gift vouchers or prepaid cards.
giftCardAmountTotal amount of gift vouchers or prepaid cards in the order.Number, decimals.
giftCardCountNumber of gift vouchers or prepaid cards.Numerical. Max 99.
giftCardCurrencyCurrency of the gift vouchers or prepaid cards.
If more than one currency, give the one of the larger amount.		ISO-4217.3 code (EUR, USD, GBP, etc.).
preOrderDateEstimated shipping date for products pre-ordered.Numerical. Max eight (8) digits.
Format YYYY-MM-DD.
preOrderPurchaseIndShows whether the product is available or will be in the future.Alphanumeric.
The values accepted are:
true: Product available.
false: Product not available yet.
reorderItemsShows whether the customer had previously purchased the item.Alphanumeric.
The values accepted are:
01: Item purchased by the customer for the first time.
02: Item purchased previously by the customer.
traActionIndShows the merchant’s preference for the type of authentication to request from issuer for the transaction.
The value sent to the issuer will depend on whether your merchant has ASC enabled and the characteristics of the transaction.
The issuer has the final say on the type of authentication they apply.		Securities:
forceChallenge: Force strong customer authentication
frictionless: Frictionless authentication \ntraExemption: Exemption from TRA authentication
lowValueExemption: Low value exemption
ParameterDescriptionFormat and values accepted
authMethodMethod used by customer for authentication on your platform.
Numerical.
The values accepted are:
01: Customer not authenticated (guest).
02: Credentials for your ecommerce platform.
03: Federated ID.
04: Issuer credentials.
05: Third-party authentication.
06: FIDO Authenticator.
07: Signed FIDO Authenticator security data.
08: CSR guarantee data.
authTimestampTime and date of customer authentication on your ecommerce platform.Numerical. Format YYYYMMDDHHmm.
ParameterDescriptionFormat and values accepted
merchantExemptionsScaSCA exemptions requested by your ecommerce platform.
Can be more than one, separated by commas.
The order in which they are given indicates priority.
The values accepted are:
LWV: Low value exemption.
TRA: Exemption because risk analysis completed.
COR: Exemption because corporate payment.
MIT: Exemption because transaction initiated by the merchant.
ParameterDescriptionFormat and values accepted
priorACSTransIDRefSCA ID for initial authentication.Alphanumeric. Max 36 characters.
priorAuthDataInitial authentication data received from SCA.Alphanumeric. Max 2048 characters.
priorAuthMethodAuthentication method used by SCA for initial authentication.Numerical.
The values accepted are:
01: Frictionless.
02: Challenge.\n03: AVS check.
04: Other issuer method.
PriorAuthTimestampTime and date of initial authentication.Whole number. Format YYYYMMDDHHmm.
threeDS3RIShows the type of 3RI request.
Provides additional information to SCA to manage 3RI request.		Numerical.
The values accepted are:
01: Recurring transaction.
02: Payment in instalments.
03: Add card.
04: Update card information.
05: Account verification.
06: Postponed or split shipping.
07: Top up.
08: Post order.
09: Phone order.
10: Check whitelist status.
11: Other payments.
threeDSDecoupleConfirmationIndAsks SCA to use decoupled authentication and accepts it will be used if SCA confirms.Alphabetical. Max one (1) character.
The values accepted are:
Y: Request decoupled authentication be used.
N: Request decoupled authentication not be used.
threeDSDecoupleMaxTimeoutMaximum time in minutes your ecommerce platform will wait for SCA to return result of decoupled authentication.
Required if “threeDSDecoupleConfirmationInd = Y”
Numerical. Max 10080 minutes.
threeDSDeviceChannelTransaction authentication channel.Numerical.
The values accepted are:
1: App.
2: Web browser.
3: 2DS initiated by merchant (3RI).
threeDSServerTransIdUUID for the transaction on the 3DS server.
Required if “threeDSDeviceChannel = 2”.
Alphanumeric. Format is UUID.

Exemptions and Addon Sales Conversion (ASC) service

Exemptions

The PSD2 directive establishes certain cases when transactions are exempt from these rules. These exemptions from 3DSecure authentication apply as long as certain criteria are met, such as: amounts under designated limit or after risk analysis. The issuing bank must accept that the exemption is applied to the transaction.

If you want to apply the exemption, the transaction authorization request must included the parameter “merchantExemptionsSca“. The values accepted are:

  • MIT (Merchant Initiated Transaction): Transaction initiated by the merchant.
  • LWV (Low Value): Transaction for a small amount.
  • TRA (Transaction Risk Analysis): Transaction deemed low risk by risk analysis service.
  • COR: Corporate payments between companies

For example:

[merchantExemptionsSca] => MIT

Addon Sales Conversion

Addon Sales Conversion (hereinafter ASC) is a Comercia Global Payments (CGP) service that allows you to offer a better user experience during payment processes on your ecommerce site, reducing the number of times authentication is requested without sacrificing security.

The service is based on SCA exemptions allowed under the PSD2 directive. Transactions eligible for exemption are analysed to determine the risk the transaction poses. If it is low risk, the issuer is asked not to authenticate the transaction. The issuer has the final say in applying exemptions or not, so it may request authentication as a requirement for authorizing the transaction.

Types of transactions that are SCA exempt

The PSD2 directive allows merchants to request the following types of transactions not be authenticated:

  • LWV (Low Value): Transaction for a small amount (under €30 per transaction, with no more than 5 consecutive transactions or €100 in total without authentication).
    • Transactions exempt through ASC.
  • TRA (Transaction Risk Analysis): Transactions analysed by the entity and deemed low risk up to an amount set by the entity.
    • Transactions exempt through ASC.
  • COR: Corporate transactions between companies with payment methods not accessible outside the business environment or to end consumers.
  • DAU (Delegated Authentication): Delegated authentication is a specific programme that will be part of future versions of the protocol.

The following operations are not subject to PSD2 compliance:

  • MIT (Merchant Initiated Transaction): Transaction sent by the merchant without cardholder involvement, sending card data or tokens generated previously.
    • MIT operation must be activated by your Caixabank account manager.
  • Cards issued outside the EEA: Cards from issuers outside the European Economic Area (EEA) are not affected by the new PSD2 directive, so they can continue operating with non-secure methods.
  • MO/TO (Mail Order/Telephone Order): Transactions sent by a terminal with MO/TO by manually entering the cardholder’s card data, provided over the phone or by email.

How to use ASC

ASC can be activated with your Caixabank account manager. Once it is activated, your platform can use this service as follows:

  • Default: All transactions requesting authorization will be analysed. The system will add the TRA exemption request to the request sent to the issuing bank. This will be done for transactions Comercia Global Payments (CGP) deems a low fraud risk.
  • Manual mode (must be activated by CGP): Your ecommerce platform is in charge of telling the system which transactions should be analysed, including the TRA exemption request in the parameter “merchantExemptionsSca”.
    • When the system set up in manual mode receives an authorization request with TRA exemption in the “merchantExemptionsSca” field, the system will analyse the transaction risk:
      • If the risk is low, it will allow the exemption request to be sent to the issuing bank.
      • If the risk is high, it will request authentication from the issuing bank.

MIT exemption

From the point of view of the cardholder’s action during the transaction, PSD2 classifies transactions in two categories:

  • CIT (Customer Initiated Transaction): Transactions initiated by the consumer, who is present at the time. So, SCA is possible.
  • MIT (Merchant Initiated Transaction): Transactions initiated by the merchant, when the customer is not present. So, SCA is not possible.

Transactions initiated by the merchant (automatic or manual payment) are outside the scope of the PSD2 directive. They must include the parameter “merchantExemptionsSca” with the value “MIT” in the transactions. This must be activated by your Caixabank account manager.

To comply with the PSD2 directive, if you save the reference or token for the customer’s card for future payments, the first transaction using the token must be authorized with strong customer authentication (SCA). 

Below is an example of a request for recurring payment with a token, including MIT exemption:  

[merchantId] => 12345
[merchantTransactionId] => 84891340
[amount] => 1.00
[currency] => EUR
[country] => ES
[customerId] => 3
[paymentSolution] => creditcards
[merchantExemptionsSca] => MIT
[cardNumberToken] => 1217106174412227
[paymentRecurringType] => subscription
[subscriptionPlan] => 941789570176899

Integration of 3RI

Merchant Initiated Authentication (3RI) is a form of authentication supported in 3D Secure version 2.2.

3RI authentication allows merchants to perform authentications and authorizations without the customer being present during transactions. These authentications are possible by referencing the authentication of the original transaction, where the customer was present during the transaction.

This operation can be useful for your business in the following cases:

  • Partial product shipment: When you cannot ship all the items purchased by the customer at the same time. With the 3RI operation you can ship them at different times and charge them when you ship them.
  • Final amount unknown before purchase: When the final amount is unknown and may incur extra costs. For example, possible damages after renting a vacation home.
  • Coverage of a returned item: When the merchant offers free returns to the customer. If not all items are returned, the merchant may charge the customer again.
  • Multiple merchants: Allows for one authentication with the customer present and then multiple authorizations for the merchants involved. For example, a Marketplace that sells different products from different stores from its website. The customer buys 2 products from the Marketplace and authenticates the total amount. Then, the Marketplace processes different authorizations to send the amount to the stores that sell the products.

In the following examples, you will see how 3RI works with a practical use case: The partial shipment of products. In addition, we will give you complementary indications to carry out the other use cases, if necessary.

In this example, a customer has purchased 2 products. The merchant has one of them in stock, so:

  • It will authenticate the amount of the 2 products.
  • It will authorize and send the one in stock (these 2 operations have the customer present).
  • Later, it will authenticate and authorize the second one thanks to 3RI.

If you want to authenticate and authorize with the customer present in the same operation, check this section.

Authentication for the full amount

This operation is performed with the customer present (CIT, Customer Initiated Transaction). We will authenticate the amount of the 2 products, which is 100€, 50€ each product.

You can perform this operation in Hosted, Host2Host or JavaScript integrations. However, please note that the following 3RI operations must be via Host2Host. See the specific documentation for more details.

In this example, we will do all examples with a Host2Host integration. Refer to the specific documentation for the request sending endpoints. Remember that if you send customer card data from your platform you must be aware of the PCI DSS certification requirements.

Request

In this first operation we will authenticate the full amount of the operation. This is an example of authentication request for the full amount, the first as a string and the second as a cURL.

				
					merchantId=102106&amount=0&productId=105960001&merchantTransactionId=3RICITPAtestsoporte1
&country=ES&errorURL=https://ejemplo.com/error&customerId=supportest&currency=EUR
&chName=soporte&paymentSolution=creditcards&operationType=debit&successURL=http://ejemplo.com/success
&statusURL=http://ejemplo.com/status&cardNumber=4907270002222227&expDate=1240
&cvnNumber=123&authenticationInd=02&paymentRecurringExpiry=20231231
&paymentRecurringFrecuency=0&authentication3RIAmount=100
				
			
				
					curl --location --request POST 'https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/pay' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: 0Pn6pDEm73YvekNKUJcvwg==' \
--form 'merchantId="102106"' \
--form 'encrypted="YhkE2nrG1vmWRxNnMxWtbqDHsi/+FQs2AfPJBBHwIYOG3JCagem6DSb+D5hF1TUlut+p3/9WUaInomL4o17lyYZds2eQ48hNGO8O8EmnDzTfveqZUASpII=”' \
--form 'integrityCheck="06c928531469eb314c609e9a565567afecae69e644ba0e8cc49c612b6bf35e83"'

Authentication request parameters

Below are the specific parameters you must send for the authentication request. Important: To these parameters you must add those required for a Host2Host request via cards.

The type column shows whether the element is Required (R) or Optional (O):

FieldFormatTypeDescriptionExample
authenticationInd01: Payment transaction
02: Recurring transaction
03: Installment payment
RIndicates the initial cardholder authentication type.02
paymentRecurringExpiryAlphanumeric
YYYY-MM-DD		R (when authenticationInd is 02 or 03)Last day on which the merchant can make authorizations.2024-12-31
paymentRecurringFrecuencyNumerical
Bigger or same as 0		R (when authenticationInd is 02 or 03)Indicates the minimum number of days that must elapse between authorizations.0
authentication3RIAmountNumerical with decimals
0~1000000.00
The amount must be bigger than the one in the field “amount”		R (when authenticationInd is 02 or 03)Indicates the amount of the authentication. If not sent, it will be done with the amount in the “amount” field.
The decimal separator is the period (.). There is no thousands separator.		100
purchaseInstalDataNumerical
Bigger than 1		R (when authenticationInd is 03)Indicates the number of authorizations allowed for an installment payment. Must be agreed between the cardholder and the merchant.3

Response

In the notification, some parameters will be returned whenever the authentication is successful. The merchant should save this data for future transactions.

Below, you have a table with some of the data required for subsequent 3RI transactions that will be returned in the response after a successful full amount authentication. You will find them inside < mpi >:

FieldFormatDescriptionExample
acsTransIDCanonic, as defined in IETF RDC 4122
Inside “mpi” object		Authentication identification value in 3DS ACSa9be31b1-6d52-44c1-8699-1d37ca4eb1cf
authMethod01: Frictionless authentication by ACS
02: Cardholder challenge by ACS
03: AVS verificated
04: Other issuer methods
05-79: Reserved for future EMVCo uses
80-99: Reserved for DS
Inside “mpi” object		Method used by card owner to perform authentication01
authTimestampYYYYMMDDHHMM
Inside “mpi” object		Year, month, day, hour and minute (UTC) in which the first authentication was made202301071540
threeDSv2TokenAlphanumeric3DS token. It links authentication with authorization.cf5bf8c8-03e8-4ead-899b-d00b82fa5093
authDataAlphanumeric
Inside “mpi” object		Information related to authentication, with extra data related to this operation.
It is optional.		N/A

Below is an example of a response to an authentication request:

				
					<!--?xml version="1.0"?-->
<payfrex-response operation-size="1">
  <message>WorkFlow has finished successfully, for transaction Id: 7762122</message>
  <operations>
    <operation sorted-order="1">
      <amount>0</amount>
      <currency>EUR</currency>
      <merchanttransactionid>3RI-CIT-PA-testsoporte0001</merchanttransactionid>
      <message>3dsv2 - processed</message>
      <operationtype>DEBIT</operationtype>
      <payfrextransactionid>7762122</payfrextransactionid>
      <paymentdetails>
        <cardnumbertoken>2420835988782227</cardnumbertoken>
        <extradetails>
      </extradetails></paymentdetails>
      <service>3DSv2</service>
      <status>SUCCESS3DS</status>
      <respcode>
        <code>8000</code>
        <message>Successful authentication</message>
        <uuid>6a69447e_51fe_4689_b6f8_c4943bcd2ac2</uuid>
      </respcode>
      <mpi>
        <acstransid>62eecff1-471d-4d0a-902f-c1a535b9cf68</acstransid>
        <authmethod>01</authmethod>
        <authtimestamp>202312140942</authtimestamp>
        <authenticationstatus>Y</authenticationstatus>
        <cavv>AJkBB4OBmVFmgYFYFIGZAAAAAAA=</cavv>
        <eci>05</eci>
        <messageversion>2.2.0</messageversion>
        <threedssessiondata>NGJhNDgyZmEtZjJiZS00ODVkLTkzYTgtZjE2OGRiYzdhNGQ3</threedssessiondata>
        <threedsv2token>4ba482fa-f2be-485d-93a8-f168dbc7a4d7</threedsv2token>
      </mpi>
      <paymentcode>nsY1</paymentcode>
      <paymentmessage>Authenticated successfully</paymentmessage>
    </operation>
  </operations>
  <optionaltransactionparams>
    <entry>
      <key>3riauthentication</key>
      <value>true</value>
    </entry>
  </optionaltransactionparams>
  <status>SUCCESS</status>
  <workflowresponse>
    <id>51498</id>
    <name>3RI H2H autenticacion</name>
    <version>0</version>
  </workflowresponse>
</payfrex-response>

Authorization of an amount less than the total amount

In this operation, which is performed with the customer present (CIT), we are going to authorize the amount of one of the products that the customer has purchased, since it is the one we have in stock. The value is 50€. Remember that the value must be less than the total amount authenticated.

In this example we are working with a Host2Host integration, but remember that you can perform this operation in Hosted or JavaScript integrations. The following 3RI operations must be via Host2Host.

Request

In this second operation we will authorize the amount of the item in stock. This is an example of an authorization for an amount less than the total, the first as a string and the second as a cURL.

				
					merchantId=102106&amount=50&productId=105960001&merchantTransactionId=3RICITPAtestsoporte1
&country=ES&errorURL=https://ejemplo.com/error&customerId=supportest&currency=EUR
&chName=soporte&paymentSolution=creditcards&operationType=debit&successURL=http://ejemplo.com/success
&statusURL=http://ejemplo.com/status&cardNumber=4907270002222227&expDate=1240
&cvnNumber=123&paymentRecurringType=newCof
&threedParams={"threeDSv2Token":"4ba482fa-f2be-485d-93a8-f168dbc7a4d7"}
				
			
				
					curl --location --request POST 'https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/pay' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: 12dsdpDEm73YvekNKdfdfg==' \
--form 'merchantId="102106"' \
--form 'encrypted="TuHAIJhyagYU237JIGMxWtbqDHsi/+FQs2AfPJBBHwIYOG3JCagem6DSb+D5hF1TUlut+p3/9WUaInomL4o17lyYZds2e932AGyu6SA6S6=”' \
--form 'integrityCheck="sfsdfwf9eb314c609e9a565567afecae69e644ba0e8cc49c612b6basda3"'

Authorization request parameters

Below are the specific parameters you must send for the authorization request of an amount less than the total. Important: To these parameters you must add those required for a Host2Host request via cards.

The type column shows whether the element is Required (R) or Optional (O):

FieldFormatTypeDescriptionExample
paymentRecurringType– newCof: One-off payments, without a fixed amount or periodicity.
– newSubscription: Recurring payments with fixed amount and periodicity.
– newInstallment: Postponed payment limited to individual purchase with fixed amount and periodicity.		RRecurring or successive payment type. Note if the COF transaction is initial or successive, and the reason or purpose for payment.newCof
threedParamsJSON
Alphanumeric		RLink the decoupled authentication with the authorizations. In the JSON, you must include the field “threeDSv2Token” along with its value, as you see in the example{“threeDSv2Token “:”cf5bf8c8-03e8-4ead-899b-d00b82fa5093”}

Response

In the notification you will receive some parameters when the authorization is successful. You will need to use this data, together with the data from the previous notification, for subsequent 3RI operations.

Below is a table with some of the necessary parameters that you will receive in the notification for an authorization of less than the total amount.

FieldFormatDescriptionExample
cardNumberTokenAlphanumeric
16~20 characters		Addon Payments token of the card number. The last 4 digits match the original card number.4535954006730084
subscriptionPlanAlphanumeric
Max 45 characters.		Subscription plan identifier, linking the authorization with the customer and the merchant.
This parameter is required for successive authorizations.		708120533554282

Below is an example of a response to an authorization request:

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payfrex-response operation-size="1">
	<message>WorkFlow has finished successfully, for transaction Id: 7762182</message>
	<operations>
		<operation sorted-order="1">
			<amount>50</amount>
			<currency>EUR</currency>
			<details>{"resultCode":"00000","resultDescription":"OK","values":{"rfTransactionCurrency":"EUR","rfRTS":"999008881 790190 900879 231214110620","rfContactlessLogo":"false","rfOperationType":"Settle","rfAuthMode":"On","rfDataEntryMode":"Manual","rfCardHolderVerificationMode":"No","rfFuc":"999008881","rfTerminalID":"00000713","rfProcessor":"Redsys","rfMerchantName":"Easy Payment Gateway","rfMerchantCity":"Mijas","rfMerchantPostalCode":"29651","rfMerchantAddress":"Av. Carmen Saenz de Tejada, S208, 001B, Edificio Miramar","rfMaskedPan":"************2227","rfOperationDateTime":"14/12/23 11:06:20","rfTerminalOperationNumber":"0051","rfAuthNumber":"597386","rfTransactionAmountCurrency":"250,00 EUR","rfProcessorMessage":"","OperationResult":"000","cofAdditionalInformation":"CS098715813517364"}}</details>
			<merchantTransactionId>3RI-CIT-AO-testsoporte0002</merchantTransactionId>
			<message>Success 'Settle' operation</message>
			<operationType>DEBIT</operationType>
			<optionalTransactionParams>
				<entry>
					<key>3riauthorization</key>
					<value>true</value>
				</entry>
			</optionalTransactionParams>
			<payFrexTransactionId>7762182</payFrexTransactionId>
			<paySolTransactionId>999008881 790190 900879 231214110620</paySolTransactionId>
			<paymentDetails>
				<cardHolderName>test soporte</cardHolderName>
				<cardNumber>490727****2227</cardNumber>
				<cardNumberToken>2420835988782227</cardNumberToken>
				<cardType>VISA/CREDIT</cardType>
				<expDate>1240</expDate>
				<extraDetails>
					<entry>
						<key>cardCategory</key>
						<value>Not Available</value>
					</entry>
					<entry>
						<key>rememberMe</key>
						<value>true</value>
					</entry>
				</extraDetails>
				<issuerBank>SERVIRED MASTERCARD INTERNACIONAL</issuerBank>
				<issuerCountry>ES</issuerCountry>
			</paymentDetails>
			<paymentSolution>caixapucpuce</paymentSolution>
			<status>SUCCESS</status>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>f2c9b387_0d5d_4c8a_a203_0b797af1148d</uuid>
			</respCode>
			<authCode>597386</authCode>
			<mpi>
				<eci>05</eci>
			</mpi>
			<paymentCode>000</paymentCode>
			<paymentMessage>Operación finalizada con éxito</paymentMessage>
			<subscriptionPlan>098715813517364</subscriptionPlan>
		</operation>
	</operations>
	<status>SUCCESS</status>
	<workFlowResponse>
		<id>51501</id>
		<name>3RI H2H autorizacion</name>
		<version>0</version>
	</workFlowResponse>
</payfrex-response>

Authentication and authorization 3RI for the remaining amount

In this operation, where the customer is no longer present (MIT, Merchant Initiated Transaction), we will authenticate and authorize the remaining amount, which corresponds to the object that the merchant already has in stock. At this point, we have:

  • The total amount authenticated.
  • Information required for the 3RI operation.
  • The first authorization, where we have obtained details of the subscription plan and the card.

With this information we can perform the 3RI operation for the remaining amount. Please note the following:

  • You do not have to process the entire remaining amount, you can perform multiple 3RI operations (as long as they do not exceed the authenticated remaining amount).
  • You can use a different “productId”, as long as it belongs to the same “merchantId”.
  • You can perform separate authentication and authorization, check this section for more information. For this example, we will perform the operations in one step.

Request

In this operation, we will authenticate and authorize the remaining amount of the original authentication, which would correspond to the second item that the customer purchased and that the merchant already has in stock. The first example is the request as a string and the second in cURL.

				
					merchantId=102106&amount=50&productId=105960001&merchantTransactionId=3RIMITPAtestsoporte1
&country=ES&errorURL=https://ejemplo.com/error&customerId=supportest&currency=EUR
&chName=soporte&paymentSolution=creditcards&operationType=debit&successURL=http://ejemplo.com/success
&statusURL=http://ejemplo.com/status&cardNumberToken=2420835988782227&expDate=1240
&subscriptionPlan=098715813517364&paymentRecurringType=cof
&threedParams={"threeDSv2Token":"4ba482fa-f2be-485d-93a8-f168dbc7a4d7"}
&threeDSDeviceChannel=03&threeDS3RI=01&priorACSTransIDRef=62eecff1-471d-4d0a-902f-c1a535b9cf68
&priorAuthMethod=01&priorAuthTimestamp=202312140942
&paymentRecurringExpiry=20231231&paymentRecurringFrecuency=0
				
			
				
					curl --location --request POST 'https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/pay' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: 12dsdpDEm73YvekNKdfdfg==' \
--form 'merchantId="102106"' \
--form 'encrypted="TuHAIJhyagYU237JIGMxWtbqDHsi/+FQs2AfPJBBHwIYOG3JCagem6DSb+D5hF1TUlut+p3/9WUaInomL4o17lyYZds2e932AGyu6SA6S6=”' \
--form 'integrityCheck="sfsdfwf9eb314c609e9a565567afecae69e644ba0e8cc49c612b6basda3"'

Request parameters 3RI

Below are the specific parameters you must send for the 3RI request. Important: To these parameters you must add those required for a Host2Host request via cards, except for those related to the card (cardNumber, expDate and cvnNumber), since we are using the card token.

The type column shows whether the element is Required (R) or Optional (O):

FieldFormatTypeDescriptionExample
threeDSDeviceChannel03: 3DS Requestor InitiatedRIndicates the authentication channel for this request. In this case 3RI (03).03
threeDS3RI01: Recurring transactionRIndicates the type of 3RI. It is extra information to process the operation in the best possible way.01
threeDSMessageCategory01: Authentication with payment (PA)
02: Authentication without payment (NPA)		OSpecifies the authentication category. The default is 01 (authentication with payment).01
priorACSTransIDRefAlphanumeric
This is the “acsTransID” value of the previous transaction notification(CIT).		RReference to the authentication in the 3DS ACS previously performed.
This value is the same for all successive payments, in case more than once is required.		a9be31b1-6d52-44c1-8699-1d37ca4eb1cf
priorAuthMethodThis is the value of the “authMethod” of the previous notification transaction (CIT).RMethod used by the card owner to perform authentication.01
priorAuthTimestampThis is the value of the “authTimestamp” of the previous transaction notification(CIT).RYear, month, day, hour and minute (UTC) in which the first authentication was made.202301071540
priorAuthDataThis is the value of the “authData” of the previous transaction notification(CIT).OInformation related to authentication, with extra data related to this operation.N/A
paymentRecurringExpiryAlphanumeric
YYYY-MM-DD		RLast day on which the merchant can make authorizations.2024-12-31
paymentRecurringFrecuencyNumerical
Same or bigger than 0		RIndicates the minimum number of days that must elapse between authorizations.0
subscriptionPlanAlphanumeric
Max 45 characters.		RSubscription plan identifier, linking the authorization with the customer and the merchant.
This parameter is required for successive authorizations.		708120533554282
cardNumberTokenAlphanumeric
16~20 characters		RAddon Payments token of the card number. The last 4 digits match the original card number. 4535954006730084
paymentRecurringTypecofRType of recurring or successive payment. Indicates whether the C.O.F. transaction is initial or successive, as well as the reason or purpose of the payment.cof
merchantExemptionsScaMIT = Merchant Initiated TransactionRPSD2 exemption to be applied. Normally it should be sent only in successive payments and with the value “MIT”.MIT

Response

This is an example of notification received after 3RI operation. If you are going to perform more 3RI operations, you must use the authentication and payment details received in the first authentication and authorization.

Note: If the authentication and authorization is for another merchant (in case of multiple merchants, you must send the “amount” and the corresponding “productId”).

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payfrex-response operation-size="2">
    <message>WorkFlow has finished successfully, for transaction Id: 520480949</message>
    <operations>
        <operation sorted-order="1">
            <amount>50</amount>
            <currency>EUR</currency>
            <merchantTransactionId>HdR612TsFZ3ri</merchantTransactionId>
            <message>3dsv2 - processed</message>
            <operationType>DEBIT</operationType>
            <payFrexTransactionId>520480949</payFrexTransactionId>
            <paymentDetails>
                <cardNumberToken>2420835988782227</cardNumberToken>
                <extraDetails/>
            </paymentDetails>
            <service>3DSv2</service>
            <status>SUCCESS3DS</status>
            <respCode>
                <code>8000</code>
                <message>Successful authentication</message>
                <uuid>22631ee0_445d_4e8f_895f_4981540ec07c</uuid>
            </respCode>
            <mpi>
                <acsTransID>e4061b62-0894-41c3-1336-e2c1c1287e14</acsTransID>
                <authMethod>01</authMethod>
                <authTimestamp>202301071548</authTimestamp>
                <authenticationStatus>Y</authenticationStatus>
                <cavv>AJkCB2VhBQAAAAABl4FYAQAAAAA=</cavv>
                <eci>05</eci>
                <messageVersion>2.2.0</messageVersion>
                <threeDSSessionData>ZDI1MDljNzgtMTU0Yy00MGIwLWJhMWEtMDYyYTZkZDYyOGQ1</threeDSSessionData>
                <threeDSv2Token>12509c78-354c-40b0-ba1a-062a6dd628d5</threeDSv2Token>
            </mpi>
            <paymentCode>nsY1</paymentCode>
            <paymentMessage>Authenticated successfully</paymentMessage>
        </operation>
        <operation sorted-order="2">
            <amount>0.01</amount>
            <currency>EUR</currency>
            <details>{"resultCode":"00000",...,"merchantExemptionSca":"MIT"}</details>
            <merchantTransactionId>HdR612TsFZ3ri</merchantTransactionId>
            <message>Success 'Auth' operation with status 'PENDING'</message>
            <operationType>DEBIT</operationType>
            <optionalTransactionParams>
                <entry>
                    <key>3ds</key>
                    <value>2</value>
                </entry>
            </optionalTransactionParams>
            <payFrexTransactionId>520480949</payFrexTransactionId>
            <paySolTransactionId>008043853 190190 558593 2110607174810</paySolTransactionId>
            <paymentDetails>
                <cardHolderName>Andres</cardHolderName>
                <cardNumber>49072****2227</cardNumber>
                <cardNumberToken>2420835988782227</cardNumberToken>
                <cardType>VISA/DEBIT OR CREDIT</cardType>
                <expDate>0927</expDate>
                <extraDetails>
                    <entry>
                        <key>cardCategory</key>
                        <value>Not Available</value>
                    </entry>
                    <entry>
                        <key>rememberMe</key>
                        <value>true</value>
                    </entry>
                </extraDetails>
                <issuerBank>BANCOSABADELL</issuerBank>
                <issuerCountry>ES</issuerCountry>
            </paymentDetails>
            <paymentSolution>caixapucpuce</paymentSolution>
            <status>PENDING</status>
            <respCode>
                <code>0000</code>
                <message>Successful</message>
                <uuid>a89237db_d0f9_43bf_b650_803a85e411ff</uuid>
            </respCode>
            <authCode>481157</authCode>
            <mpi>
                <eci>05</eci>
            </mpi>
            <paymentCode>000</paymentCode>
            <paymentMessage>Operación finalizada con éxito</paymentMessage>
        </operation>
    </operations>
    <optionalTransactionParams>
        <entry>
            <key>3ds</key>
            <value>2</value>
        </entry>
    </optionalTransactionParams>
    <status>SUCCESS</status>
    <workFlowResponse>
        <id>28082</id>
        <name>3RI</name>
        <version>0</version>
    </workFlowResponse>
</payfrex-response>

Other flows available in 3RI

In the example we have seen, the flow is as follows:

  1. Authenticate the amount of the 2 products.
  2. Authorize and send 1 of the products (these 2 operations have the customer present).
  3. Later, you will authenticate and authorize the second one thanks to 3RI.

However, with 3RI we can perform the operations in different ways, such as:

  • Authenticate and authorize with the customer present in a single operation.
  • Authenticate and authorize with 3RI in different steps.

Below, we are going to see the complementary indications for these cases.

Authenticate and authorize in one transaction

If we want to authenticate and authorize in a single operation, we must launch a request with these parameters, adding the “paymentRecurringType”.

In addition, we must send the basic parameters required depending on the type of integration: Hosted, Host2Host or JavaScript.

Remember that this operation can be performed with any of the integrations, but the following 3RI integrations without the client present, must be through Host2Host.

Authenticating and authorizing with 3RI in different operations

To authenticate and authorize with 3RI in different operations, follow these steps:

se steps:

  • Launch a 3RI request with the parameters of this table except for: “subscriptionPlan” and “paymentRecurringType”.
  • Save the “threeDSv2Token” from the notification of that authentication.
  • Send a 3RI authorization request with the following parameters from this table: “cardNumberToken”, “subscriptionPlan”, “paymentRecurringType”. In addition, send the “threedParams” which contains a JSON with the value of “threeDSv2Token” that you saved in the previous step.
Comparte este documento
Tabla de Contenidos

Consulta la documentación de las distintas secciones de integraciones:

Comienza a integrar

undraw_add_to_cart_re_wrdo 1 (1) (1)

Plugins para CMS

Complementa la integración

SDKs

Métodos de pago

Herramientas

Addon Payments

Consulta la documentación de Addon Payments. Aquí tienes las distintas secciones:

Integraciones

Consultas frecuentes

Portal Backoffice

Cyberpac

We are currently working on the English version of the Cyberpac documentation. You can view the Spanish version using the buttons below:

Canales BackOffice Portal

Plugins integration

Custom integrations

POS integrated Payments

Create a solution that will help you automate processes. You can even add payment processes on physical terminals.

Payment Integrated with Android POS

Payment Integrated with Smartphone POS

POS Data sheets

Addon Payments

Comercia Global Payments has several integration options so you can choose the most efficient one for you.

Integrations

Frequently Asked Questions

BackOffice Portal

Consult the documentation of the different integrations sections:​

Start integration

undraw_add_to_cart_re_wrdo 1 (1) (1)

CMS Plugins

Complement your integration

SDKs

Payment Methods

Tools