Session

The term "Session" refers to the authentication request in the context of 3DS. To carry out a successful authentication request, it is essential to create a session that meets the specifications and requirements of the EMV® 3D-Secure protocol. You can find the details in API - Start Session and in Session API Rules to Consider

Authorization: Refers to the essential authorization method with our API to make requests. This method is based on Bearer Token. For more information, see Authentication.

Create Session: When sending a request to create a session, 3DS Evertec checks that the card range is compatible with the EMV® 3D-Secure protocol where it verifies the protocol version it supports. Once the verification is completed, it responds by providing the URL where the redirect will be performed to complete the authentication process.

The session has a duration of 15 minutes, during which the user must be redirected (redirectURL).

Available authentication types

The session types presented below are payment transaction sessions. This means that the 3DS Requestor Authentication Indicator field has a value of 01 Payment transaction

Standard interaction

A basic authentication session refers to the process by which a single payment transaction is authenticated.

Example

{
  "acctNumber": "4009000000502",
  "cardExpiryDate": "2902",
  "purchaseAmount": "10",
  "redirectURI": "https://www.placetopay.com/web",
  "purchaseCurrency": "USD",
  "reference": "AUTH_001"
}

Response

{
  "sessionToken": "d801d6f4993fc2efd3aff71a162f33888c19282e4686bd50ff4b8624e1527dbc",
  "redirectURL": "https://3dss.placetopay.com/threeds/v2x/sessions/571/d801d6f4993fc2efd3aff71a162f33888c19282e4686bd50ff4b8624e1527dbc",
  "transactionID": 580
}

Possible errors

Code	Cause
1003	No associated merchant exists
1004	No associated subscription exists
1005	The associated brand is not enabled
1006	The associated acquirer is not enabled
1007	The associated subscription is not fully configured
1011	Invalid arguments to initiate request / Merchant is not enabled
1012	The merchant does not have a merchant category code (MCC)

{
    "error_number": 1011,
    "error_description": "Invalid arguments to initiate request",
    "errors": {
        "purchaseCurrency": [
            "The purchase currency field is required when purchase amount is present."
        ]
    }
}

Example of an error message

"Unauthenticated" message

{
  "message": "Unauthenticated."
}

This message can appear in the following cases:

The token does not exist.
The token has expired.

Non-payment (NPA)

No Payment (NPA) authentications are transactions that require cardholder authentication but are not associated with a purchase or movement of funds.

Examples:

Adding a credit card to a digital wallet.
Verifying the cardholder’s identity without performing a monetary transaction.

For this type of authentication, it is not necessary to verify account funds.

Required fields:

Authentications performed via browser:

messageCategory: NPA (02), Indicates that the transaction is of type No Payment.
deviceChannel: BRW (02), Browser. If not provided, the platform will set this value by default.
threeDSAuthenticationInd: Type of authentication requested. Options: ADD_CARD (04), MAINTAIN_CARD (05), and CARDHOLDER_VERIFICATION_AS_PART_OF_EMV_TOKEN_IDV (06).
threeDSChallengeInd: CHALLENGE_REQUESTED_MANDATE (04), Requests a mandatory challenge from the ACS. For NPA, 04 is recommended instead of 03 to ensure that the ACS performs the challenge and cannot ignore it.

POST https://3dss-dev.placetopay.ws/api/threeds/v2x/sessions

Request Lookup

{
  "deviceChannel": "BRW",
  "messageCategory": "NPA",
  "threeDSChallengeInd": "CHALLENGE_REQUESTED_MANDATE",
  "threeDSAuthenticationInd": "ADD_CARD",
  "acctNumber": "4009000000502",
  "cardExpiryDate": "2902",
  "redirectURI": "https://www.placetopay.com/web",
  "reference": "February 2024",
  "messageVersion": "2.2.0"
}

Response Lookup

{
    "action": "redirect",
    "sessionToken": "7d1dd0ee35609312d7dbeb666481d9fc18f762e83a238583fa31c904c6c028d7",
    "redirectURL": "https://3dss-dev.placetopay.ws/threeds/v2x/sessions/1254/7d1dd0ee35609312d7dbeb666481d9fc18f762e83a238583fa31c904c6c028d7",
    "transactionID": 1298
}

Action: redirect indicates that the API will return a redirectURL that must be consumed to continue with the flow

Add card during the process

During the payment process, the checkbox that says Save card for future payments is available and you want to verify the account funds.

POST https://3dss-dev.placetopay.ws/api/threeds/v2x/sessions

Request Lookup

{
 "deviceChannel": "BRW",
  "threeDSChallengeInd": "CHALLENGE_REQUESTED_MANDATE",
  "threeDSAuthenticationInd": "ADD_CARD",
  "acctNumber": "4009000000502",
  "cardExpiryDate": "2902",
  "purchaseAmount": "10",
  "redirectURI": "https://www.placetopay.com/web",
  "purchaseCurrency": "USD",
  "reference": "January 2024",
  "messageVersion": "2.2.0"
}

deviceChannel: BRW (02).

threeDSChallengeInd: indicates whether challenge is requested or not, the recommended options are:

CHALLENGE_REQUESTED_REQUESTOR_PREFERENCE: (03) the requestor has the preference that challenge be applied.
CHALLENGE_REQUESTED_MANDATE: (04) the challenge is mandatory.

threeDSAuthenticationInd, indicates the type of authentication. The value of 04 corresponds to adding a card.

Note: The messageCategory is PA (01) by default

Response Lookup

{
    "action": "redirect",
    "sessionToken": "e3f2d86cfffc96837f0762e08ec88a39704eff5ce2c7bbfeac83fac12c9f16d2",
    "redirectURL": "https://3dss-dev.placetopay.ws/threeds/v2x/sessions/1253/e3f2d86cfffc96837f0762e08ec88a39704eff5ce2c7bbfeac83fac12c9f16d2",
    "transactionID": 1297
}

Action: redirect indicates that the API will return a redirectURL that must be consumed to continue with the flow

Prior information

This type of information refers to sharing prior information during the authentication process to facilitate a more informed risk assessment and more accurate decision-making by the card issuer. The information that is added is always the last successful authentication that occurs at the same merchant.

The Placetopay 3DS Server has the following options:

Option 1. Request to add prior information.

addPriorInformation: if a request to create a session is sent with this field with value Y, it will be the Placetopay 3DS Server who automatically adds the necessary fields.

Example:

{
  "addPriorInformation": "Y",
  "acctNumber": "4009000000502",
  "cardExpiryDate": "2902",
  "purchaseAmount": "10",
  "redirectURI": "https://www.placetopay.com/web",
  "purchaseCurrency": "USD",
  "reference": "AUTH_001"
}

Option 2. Send the fields in the request.

In this option, the 3DS Requestor will be responsible for sending the data.

threeDSRequestorPriorAuthenticationInfo: Object that encapsulates the required information.
threeDSReqPriorAuthMethod: Method that was used by the cardholder for authentication. FRICTIONLESS_AUTHENTICATION (01) frictionless, CARDHOLDER_CHALLENGE_OCCURRED (02) with friction
threeDSReqPriorAuthTimestamp: Date and time in UTC format of the prior authentication. The format is YYYYMMDDHHMM
threeDSReqPriorRef: The ID granted by the ACS in the prior transaction.

Example:

{
  "acctNumber": "4009000000502",
  "cardExpiryDate": "2902",
  "purchaseAmount": "10",
  "redirectURI": "https://www.placetopay.com/web",
  "purchaseCurrency": "USD",
  "reference": "AUTH_001",
  "threeDSRequestorPriorAuthenticationInfo": {
    "threeDSReqPriorAuthMethod": "CARDHOLDER_CHALLENGE_OCCURRED",
    "threeDSReqPriorAuthTimestamp": "202308172252",
    "threeDSReqPriorRef": "882a6ce6-7ea2-41e5-aad7-4b6d84a942f6"
  }
}

Decoupled

Decoupled authentications are those in which the cardholder authentication and transaction authorization do not occur at the same time.

This method is especially relevant for use cases such as subscriptions or deferred payments, where the payment commitment is made in advance, but the transaction is completed at a later time.

Fields:

The values are optional, if not sent, the ACS will make the decision whether to perform decoupled challenge authentication and how long it should take.

threeDSRequestorDecReqInd: Indicates whether the 3DS Requestor requests the ACS to use Decoupled Authentication and accepts using Decoupled Authentication if the ACS confirms its use. Options Y if decoupled challenge is preferred and N to not use decoupled authentication.
threeDSRequestorDecMaxTime: Indicates the maximum amount of time that the 3DS requestor will wait for an ACS to provide the results of a decoupled authentication transaction in minutes.

The value of threeDSRequestorDecMaxTime must be between 1 and 10080

Example:

{
  "threeDSRequestorDecReqInd": "Y",
  "threeDSRequestorDecMaxTime": "5",
  "acctNumber": "4009000000502",
  "cardExpiryDate": "2902",
  "purchaseAmount": "10",
  "redirectURI": "https://www.placetopay.com/web",
  "purchaseCurrency": "USD",
  "reference": "AUTH_001"
}

Recurring transaction

This type of sessions occur when the merchant is initiating a transaction for service subscription purchases with a fixed amount over a given period.

Required fields:

For the initial transaction:

messageCategory: PA (01), Payment transaction. If not sent, the platform will add it by default with this value.
deviceChannel: BRW (02), Browser. If not sent, the platform will add it by default with this value.
threeDSAuthenticationInd: RECURRING_TRANSACTION (02)
threeDSChallengeInd: CHALLENGE_REQUESTED_REQUESTOR_PREFERENCE (03) (Challenge is requested from the 3DS Requestor) Indicates that the 3DS Requestor's preference is that the challenge be performed this field is optional but recommended to include.
recurringFrequency: Indicates the number of days between authorizations.
recurringExpiry: Date when the subscription will end. The format is Ymd, example: 20250601.

For subsequent transactions:

messageCategory: PA (01). If not sent, the platform will add it by default with this value.
deviceChannel: RI (03).
threeRIInd: RECURRING_TRANSACTION (01)
recurringFrequency: Indicates the number of days between authorizations.
recurringExpiry: Date when the subscription will end. The format is Ymd, example: 20250601.
threeDSRequestorPriorAuthenticationInfo: The prior authentication information (See Session with prior information).

Specifications

Protocol	Mastercard	Visa
Version 2.2	Supported	Not applicable

Mastercard Identity Check 2.1 does not support 3RI cases, in these cases only the first recurring transaction is sent.

Example

Initial recurring transaction

{
  "messageCategory": "PA",
  "threeDSAuthenticationInd": "RECURRING_TRANSACTION",
  "threeDSChallengeInd": "CHALLENGE_REQUESTED_REQUESTOR_PREFERENCE",
  "recurringExpiry": "20250201",
  "recurringFrequency": "30",
  "acctNumber": "4009000000502",
  "cardExpiryDate": "2902",
  "purchaseAmount": "10",
  "redirectURI": "https://www.placetopay.com/web",
  "purchaseCurrency": "USD",
  "reference": "AUTH_001"
}

Subsequent recurring transaction

{
  "messageCategory": "PA",
  "deviceChannel": "RI",
  "recurringExpiry": "20250201",
  "recurringFrequency": "30",
  "threeDSRequestorPriorAuthenticationInfo": {
    "threeDSReqPriorAuthMethod": "CARDHOLDER_CHALLENGE_OCCURRED",
    "threeDSReqPriorAuthTimestamp": "202308172252",
    "threeDSReqPriorRef": "882a6ce6-7ea2-41e5-aad7-4b6d84a942f6"
  },
  "acctNumber": "4009000000502",
  "cardExpiryDate": "2902",
  "purchaseAmount": "10",
  "redirectURI": "https://www.placetopay.com/web",
  "purchaseCurrency": "USD",
  "reference": "AUTH_001"
}

Improve authentication rates with additional data

We are pleased to invite you to visit the Additional Data section in our API documentation. This section offers crucial information for optimizing the 3DS authentication process.

Including this additional data in your requests allows issuers to perform a more accurate assessment, which can significantly improve successful authentication rates.

We recommend reviewing these guidelines to make the most of the API's capabilities and thus offer a more secure and efficient experience to your users.