Skip to main content

API Enhancements

To comply with the data requirements of the 3DS 2 standard, the REST API has been updated with new fields. To ensure compatibility with existing integrations, these new fields are not mandatory.

However, it's important to note that certain fields are mandatory according to the 3DS 2 standard. In cases where you don't provide these mandatory fields, PayU will default them on your behalf.

Fields required by 3DS 2 standard​

Notes

The enhancements related to the 3DS 2 standard are specific to the REST API.

The table below outlines the fields mandated by the 3DS 2 standard. These fields represent the minimum data expected to be provided by you when processing a card payment that requires 3DS 2 authentication. If you do not provide these required fields, PayU will automatically send default (dummy) values on your behalf to fulfill the 3DS 2 authentication process effectively.

You should consider sending below fields for all orders which may be subject to 3DS 2 authentication, which are:

  • orders with payMethods.payMethod.value set to any card-based payment: c, ap, jp, ma, vc,
  • orders with payMethods.payMethod.type set to CARD_TOKEN,
  • orders with payMethods.card object,
  • orders without payMethods object (in case you have any card payment configured on your POS).
Additional Comments
ParameterComment
buyer.phone
Please use +[country code] [number] format, e.g. +48 225108001
buyer.delivery
Sent as "shipping address" during 3DS 2 authentication. Please note that "state" field within buyer.delivery object is required and must be a valid ISO 3166-2 code (e.g. "UT" for Utah in the USA or "30" for "Wielkopolskie" in Poland).
threeDsAuthentication.cardholder.name
Represents name and surname printed on the card. If not provided will be created from buyer.firstName and buyer.lastName. In case neither of these fields are provided, default dummy value will be sent.
threeDsAuthentication.cardholder.billingAddress
Please note that "state" field within billingAddress object is required and must be a valid ISO 3166-2 code (e.g. "UT" for Utah in the USA or "30" for "Wielkopolskie" in Poland).
threeDsAuthentication.browser
If not sent and there is no sdk object present, default one will be created (browser.requestIp will be mapped from customerIp)
threeDsAuthentication.recurring
In case of recurring payments (transaction with recurring field set to FIRST or STANDARD) it is strongly suggested to include this object to ensure proper authentication indicator assignment during 3DS 2 processing.
threeDsAuthentication.sdk
Must be sent if authentication is to be performed using the app (SDK) flow. This object is not defaulted, if not present, browser flow is assumed.

For details on parameters, please refer to Create an Order section in our API Reference, and look for threeDsAuthentication object.

Request Example​

Notes

Below is an order create request example with minimum data required by PayU, but including also data required by 3DS 2 standard, but not made obligatory by PayU.

curl -X POST https://secure.payu.com/api/v2_1/orders \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd" \
    -d '{
    "continueUrl": "http://www.payu.pl",
    "customerIp": "216.72.35.5",
    "merchantPosId": "145227",
    "description": "Order with 3DS 2 required fields",
    "currencyCode": "PLN",
    "totalAmount": 300,
    "products": [
        {
            "name": "a product",
            "unitPrice": 300,
            "quantity": 1
        }
    ],
    "buyer": {
        "firstName": "John",
        "lastName": "Doe",
        "phone": "+48 555555555",
        "email": "john@doe.pl",
        "delivery": {
            "street": "Delivery St. 1",
            "postalCode": "55-033",
            "city": "Delivery Town",
            "state": "30",
            "countryCode": "PL"
        }
    },
    // highligh-start
    "threeDsAuthentication": {
        "cardholder": {
            "name": "Joe Doe",
            "billingAddress": {
                "street": "Billing St. 1",
                "postalCode": "33-055",
                "city": "Billington",
                "state": "30",
                "countryCode": "PL"
            }
        },
        "browser": {
            "acceptHeaders": "*/*",
            "screenWidth": "1536",
            "javaEnabled": false,
            "timezoneOffset": "-120",
            "screenHeight": "864",
            "requestIP": "216.72.35.5",
            "language": "en",
            "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:81.0) Gecko/20100101 Firefox/81.0",
            "colorDepth": "24"
        }
    }
}'

Response Example​

Below changes in response apply only to requests with card data (tokenized by PayU , tokenized by Google Pay or in plain text ) passed in payMethod object.

The changes mentioned in the response apply exclusively to requests that include card data passed in the payMethod object. These card data options include:

Browser Flow​

The response with WARNING_CONTINUE_3DS status has been updated with two additional fields:

  • threeDsProtocolVersion - currently has a constant value of 3DS2. iIdicates the version of the Three Domain Secure protocol being used.
  • iframeAllowed - indicates that the redirectUri provided in the response may be displayed within an iframe.

If you are interested in utilizing the iframe approach instead of a full redirection, further details can be found in the Authentication Page section.

Response Example
{
    "status": {
        "statusCode": "WARNING_CONTINUE_3DS",
        "severity": "WARNING"
    },
    "redirectUri": "{redirectUri}",
    "iframeAllowed": true,
    "threeDsProtocolVersion": "3DS2",
    "orderId": "QK52JR2VCR201023GUEST000P01"
}

SDK Flow​

In scenarios where 3DS 2 authentication is handled natively within mobile apps, the redirectUri will not be applicable.

Instead, the challengeParameters object will be returned in the response, and this object should be passed to the mobile app.

Response Example
{
    "status": {
        "statusCode": "SUCCESS",
        "statusDesc": "Request successful"
    },
    "threeDsProtocolVersion": "3DS2",
    "challengeParameters": {
        "threeDsServerTransactionId": "0016f22b-f988-4358-b2c6-8917bba22037",
        "acsTransID": "d7c1ee99-9478-44a6-b1f2-391e29c6b340",
        "acsReferenceNumber": "3DS_LOA_ACS_201_13579",
        "acsSignedContent": "someBase64encodedString"
    },
    "orderId": "JQC8TR8L4J201023GUEST000P01"
}

3DS Details in Transaction Data​

To understand the 3DS result accurately, it is essential to examine the following fields after their retrieval in the transaction data, as is explained in the Retrieving Transaction Data section:

  • cardEciCode contains the Electronic Commerce Indicator (ECI) code associated with the card payment.

  • card3DsStatus contains status of the 3DS authentication for the card payment, which could indicate whether it was successful or not.

  • card3DsFrictionlessIndicator indicates whether the authentication was frictionless or was challenged.

  • card3DsStatusDescription displays description of the 3DS authentication status, offering further details on the outcome of the authentication process.

ECI​

ECI, short for Electronic Commerce Indicator, is a parameter that signifies the authentication level of a transaction. This indicator is particularly relevant for assessing the liability associated with fraudulent chargebacks.

For transactions involving full authentication or attempted authentication, the liability for fraudulent chargebacks rests with the card issuer. However, in cases where full authentication is not performed, the liability shifts to the merchant.

Notes

Full authentication does not indicate whether the transaction was authenticated via challenge (the cardholder had to perform some action, usually in compliance with the "strong customer authentication" requirement) or whether the authentication was frictionless (no input or action by the cardholder).

Attempted authentication means that PayU has attempted authentication, but the card issuer was unable to authenticate (in most cases because a particular card was not enrolled in the 3DS service).

A special case exists for Mastercard transactions known as "data-only" (officially referred to as Digital Transaction Insights). In this scenario, an unauthenticated transaction is subjected to 3DS processing, but it does not result in the transaction being treated as authenticated.

When you send a data-only transaction, it enriches the insights (hints) provided to the issuer by Mastercard. However, it is important to note that despite this enrichment, the transaction does not qualify as fully authenticated according to the 3DS protocol.

Transaction Data ECI Codes
Authentication LevelVisaMastercard
Full authentication - cardholder authenticated by the Issuer. Issuer Liability.
5
2
Attempted authentication - merchant attempted to authenticate the cardholder but either the cardholder or Issuer is not participating in 3DS or the Issuer’s ACS is currently unavailable. Issuer Liability.
6
1
No authentication - payment authentication has not been performed. Merchant Liability.
7
0
No authentication, 3DS data sent to card scheme
4
Full authentication, recurring transaction
7
Notes

This is not a full list of available ECI codes, it only covers values you may receive in transaction data.

Transactions are protected against risk of chargeback frauds with ECI codes:

  • 1 i 2 in case of Mastercard,
  • 5 i 6 in case of Visa.

3DS Status​

Additionally response is supplemented with the following 3DS statuses:

Transaction Data 3DS Statuses
StatusDescription
Y
Authentication successful
N
Not authenticated (usually due to unsuccessful challenge)
U
Unable to authenticate (technical problem, card not enrolled or data-only authentication)
A
Attempt processed (not authenticated, but proof of attempted authentication was provided)
R
Rejected (stronger version of N, issuer rejects without trying to challenge the cardholder)
I
Informational status (the card issuer has accepted an exception to strong authentication).
Notes

This is not a full list of statuses in 3DS 2 standard, it only covers the statuses that you may receive in transaction data.

Frictionless Indicator​

As mentioned above, ECI alone does not indicate whether the transaction was authenticated via challenge or not.

To help you understand whether the cardholder was challenged by the issuer and had to perform some action, we prepared, an additional field that is not a part of the 3DS 2 standard. This field helps determine if the challenge involved actions like confirming the transaction in a mobile app ("out of bound authentication"), entering a one-time password (OTP, often received via SMS text message, "dynamic authentication"), or entering a static password ("static authentication").

It is important to note that "challenge" does not necessarily mean strong customer authentication (SCA, as required in the European Economic Area countries). This is because SCA requires Two-Factor Authentication (2FA), and issuers can only apply one factor. While issuers based in the EEA may consider challenge as equivalent to SCA, this may not apply to issuers from other regions.

The possible values of the frictionless indicator field are:

  • YES
  • NO
  • UNKNOWN

3DS Status Description​

The 3DS status description field provides detailed information about the 3DS result and is presented as a comma-separated array of multiple 3DS 2 data fields. Each element in the array represents descriptive representations of 3DS 2 codes specific to a given field.

Due to the large number of possible values, the array elements are not enumerated. Instead, they are descriptive representations of codes specified in the 3DS2 standard. These values are taken directly from the specification "as is." It's important to note that the standard itself defines the meaning of each field but does not provide an exhaustive explanation of all possible values they can take. Therefore, the use of certain values may vary depending on the specific implementation.

For instance, confirming a transaction in a mobile application may be referred to as "dynamic authentication" by one issuer and "out of bound" by another. The variation in the values used by different issuers is due to the flexibility allowed by the standard in defining the specific descriptions for each code.

3DS Status Description
PositionSourceComment
0
3DS 2 version
Specifies message version number (currently 2.1.0 or 2.2.0).
1
Device Channel
Specifies whether the authentication took place in the browser or natively in a mobile app. Currently always "browser flow".
2
3DS Method Completion Indicator
Specifies whether the issuer notified completion of fingerprinting by means of a hidden iframe displayed in the browser.
3
Authentication Type
Applicable to authentications with challenge. Most common values are "dynamic authentication" and "out of boud". See Frictionless indicator for more details regarding challenge.
4
Challenge Cancel
Applicable to authentications with challenge. Specifies whether the challenge was canceled and why.
5
Transaction Status Reason
Provides information on why the Transaction Status field has the specified value.

Examples​

Below are some of the most common examples of 3DS status descriptions:

Successful Authentication of a Mastercard Cardholder Using 2.1.0 Version
//3DS method was not applied, cardholder was challenged.
"cardEciCode": "2",
"card3DsStatus": "Y",
"card3DsFrictionlessIndicator": "NO",
"card3DsStatusDescription": "MessageVersion=2.1.0,browser flow,3DS method not available,dynamic authentication,no cancel indicator,no status reason"

Successful Authentication of a Visa Cardholder Using 2.2.0 Version
//3DS method was applied and no challenge was performed.
"cardEciCode": "5",
"card3DsStatus": "Y",
"card3DsFrictionlessIndicator": "YES",
"card3DsStatusDescription": "MessageVersion=2.2.0,browser flow,3DS method completed,frictionless authentication,no challenge,no status reason"

Unauthenticated Transaction for which 3DS Data was Provided to Mastercard
"cardEciCode": "4",
"card3DsStatus": "U",
"card3DsFrictionlessIndicator": "YES",
"card3DsStatusDescription": "MessageVersion=2.1.0,browser flow,3DS method not available,frictionless authentication,no challenge,data-only"

Unsuccessful Authentication of a Mastercard Cardholder
//Cardholder did not complete the challenge and transaction was timed out by the issuer.
"cardEciCode": "0",
"card3DsStatus": "N",
"card3DsFrictionlessIndicator": "NO",
"card3DsStatusDescription": "MessageVersion=2.1.0,browser flow,3DS method not available,out of band authentication,challenge displayed - ACS timeout,timed out at ACS"

Unsuccessful Authentication of a Visa Cardholder
//Cardholder canceled the challenge.
"cardEciCode": "7",
"card3DsStatus": "N",
"card3DsFrictionlessIndicator": "NO",
"card3DsStatusDescription": "MessageVersion=2.1.0,browser flow,3DS method not available,dynamic authentication,challenge canceled by cardholder,authentication failed"

Unsuccessful authentication of a Visa cardholder
//Challenge was not displayed and transaction was timed out by the issuer.
//Usually challenge is not displayed because there is no redirection to the URL of the authentication page returned from PayU.
"cardEciCode": "7",
"card3DsStatus": "N",
"card3DsFrictionlessIndicator": "NO",
"card3DsStatusDescription": "MessageVersion=2.1.0,browser flow,3DS method not available,dynamic authentication,challenge not displayed,timed out at ACS"

On this page