Service to start a session in the 3DS Server authentication flow.

The following steps will serve as a guide for using it:

1. Create an HTTP POST request on your server with the endpoint /sessions

2. In the request header, enter the bearer token, which will allow you to register as an authorized user. This header is mandatory.

3. The header should also contain the Content-Type value of "application/json".

4. Enter in the request body the minimum required fields, which are:

  • acctNumber
  • cardExpiryDate
  • purchaseAmount
  • redirectURI
  • purchaseCurrency

The description of the request and response fields, data type, length and other specifications can be viewed in the responses section, in the data schema.

5. Send the request and get a response.

6. You can view the authentication status by redirecting to the "redirectURI", data returned in a successful response or with status "Y".

To obtain authentication states different from "Y", you can modify the "acctNumber" field of the request with the test card numbers given in this documentation.

OpenAPI (YAML)Postman collection

Implementation of the v2x Contract

The implementation of a new contract is recommended, delivering the following outcomes:

Channel
Channel Indicator
Action
Message Category
Information
APP
"01"
continue
PA, NPA
This new action allows returning the transaction result and does not require user intervention to be completed.
BRW
"02"
redirect
PA, NPA
This action is executed in BRW device flows, in which we return a redirectURL, to start the authentication flow.
3RI
"03"
continue
PA, NPA
This new action allows returning the transaction result and does not require user intervention to be completed.

For more details about the "redirect" action and its implementation, you can consult the specific documentation of the BRW authentication flow.

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 to optimize the 3DS authentication process.

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

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

For the 3RI flow, the same response contract is returned as in the Show Transaction of version 2.x. Values returned in the API response

POST/threeds/v2x/sessions

Create a BRW or RI session

This endpoint allows you to create a new session for cardholder authentication.

Request

  • Name
    acctNumber
    Type
    string
    is Required
    REQUIRED
    Description

    Account number that will be used in the authorization request for payment transactions. Must pass Luhn Algorithm validation Accepted values: See ISO 7812 format

    Example:4005580000000040
    Max length:19
    Min length:13
  • Name
    cardExpiryDate
    Type
    string
    is Required
    REQUIRED
    Description

    Card expiration date provided by the cardholder. Format: ym Example: 2506

    Example:2506
    Max length:4
    Min length:4
  • Name
    purchaseAmount
    Type
    string
    is Required
    REQUIRED
    Description

    Transaction amount. Example: 20.5

    Example:20.5
  • Name
    purchaseCurrency
    Type
    string
    is Required
    REQUIRED
    Description

    The 3-letter alphabetic code of the currency in which the purchase amount is expressed Values: See ISO 4217 format

    Example:USD
    Max length:3
    Min length:3
  • Name
    redirectURI
    Type
    string
    is Required
    REQUIRED
    Description

    URL of the system where the cardholder will be redirected after completing an authentication transaction.

    Example:https://www.placetopay.com
    Format:uri
    Max length:256
  • Name
    threeDSAuthenticationInd
    Type
    string
    is optional
    Description

    Indicates the type of authentication request. Values:

    • PAYMENT_TRANSACTION (01) - Payment transaction
    • RECURRING_TRANSACTION (02) - Recurring transaction
    • INSTALMENT_TRANSACTION (03) - Installment transaction
    • ADD_CARD (04) - Add a card
    • MAINTAIN_CARD (05) - Maintain a card
    • CARDHOLDER_VERIFICATION_AS_PART_OF_EMV_TOKEN_IDV (06) - Cardholder verification as part of EMV token ID&V
    • BILLING_AGREEMENT (07) - Billing agreement
    • MASTERCARD_THE_PAYMENT_REQUEST_IS_FOR_AN_AGENT_PAYMENT_TRANSACTION (85) - Agent payment transaction for Mastercard
    • MASTERCARD_FOR_UNKNOWN_OR_UNDEFINED_FINAL_AMOUNT_BEFORE_PURCHASE_TRANSACTION (86) - Transaction for Mastercard with unknown or undefined final amount before purchase
    Example:01
    Max length:2
    Min length:2
  • Name
    reference
    Type
    string
    is optional
    Description

    Transaction reference.

    Max length:32
  • Name
    recurringFrequency
    Type
    string
    is optional
    Description

    Indicates the minimum number of days between authorizations. Required if threeDSAuthenticationInd equals RECURRING_TRANSACTION (02) or INSTALMENT_TRANSACTION (03) Must be present whenever recurringExpiry is sent Example values: 31, 031, 0031

    Max length:4
    Min length:1
  • Name
    recurringExpiry
    Type
    string
    is optional
    Description

    Date after which no more authorizations will be made. Required if threeDSAuthenticationInd equals RECURRING_TRANSACTION (02) or INSTALMENT_TRANSACTION (03) Must be present whenever recurringFrequency is sent Format: Ymd Example: 20250601

    Max length:8
    Min length:8
  • Name
    purchaseInstalData
    Type
    string
    is optional
    Description

    Indicates the maximum number of authorizations allowed for installment payments. The value must be greater than 1. Required if the merchant and cardholder have agreed to installment payments, i.e., if threeDSAuthenticationInd = 03. Omitted if it is not an installment payment authentication. Example values: 2, 02, 002

    Max length:3
    Min length:1
  • Name
    threeDSAuthenticationInfo
    Type
    threeDSAuthenticationInfo
    is optional
    Description

    Information about how the 3DS Requestor authenticated the cardholder before or during the transaction.

  • Name
    threeDSChallengeInd
    Type
    string
    is optional
    Description

    Indicates if a challenge is requested for this transaction. If this parameter is not sent in the request, NO_PREFERENCE (01) will be assumed as default value. Values:

    • NO_PREFERENCE (01) - No preference
    • NO_CHALLENGE_REQUESTED (02) - No challenge requested
    • CHALLENGE_REQUESTED_REQUESTOR_PREFERENCE (03) - Challenge requested (requestor preference)
    • CHALLENGE_REQUESTED_MANDATE (04) - Challenge requested (mandate)
    • NO_CHALLENGE_REQUESTED_RISK_PERFORMED (05) - No challenge requested (risk analysis performed)
    • NO_CHALLENGE_REQUESTED_DATA_SHARED_ONLY (06) - No challenge requested (data shared only)
    • NO_CHALLENGE_REQUESTED_CONSUMER_AUTH_PERFORMED (07) - No challenge requested (consumer authentication performed)
    • NO_CHALLENGE_REQUESTED_WHITELIST_EXEMPTION (08) - No challenge requested (whitelist exemption)
    • NO_CHALLENGE_REQUESTED_WHITELIST_PROMPT_REQUESTED (09) - No challenge requested (whitelist prompt requested)
    • VISA_RESERVED (82) - Reserved for VISA
    Max length:2
    Min length:2
  • Name
    threeDSRequestorID
    Type
    string
    is optional
    Description

    Identifier associated by the DS to the 3DS Requestor. Each Directory Server may impose specific format and character requirements on the content of this field.

    Max length:35
  • Name
    acctInfo
    Type
    acctInfo
    is optional
    Description

    Additional information about the cardholder account.

  • Name
    acctID
    Type
    string
    is optional
    Description

    Additional account information provided by 3DS Requestor.

    Max length:64
  • Name
    billAddrCity
    Type
    string
    is optional
    Description

    The name of the city of the billing address of the Cardholder associated with the card used for this purchase.

    Max length:50
  • Name
    billAddrCountry
    Type
    string
    is optional
    Description

    The three-letter alphabetic code that relates to the country of the billing address of the Cardholder associated with the card used for this purchase. Accepted values: See ISO 3166-1 format

    Max length:3
  • Name
    billAddrLine1
    Type
    string
    is optional
    Description

    First line of the postal address or local equivalent part of the billing address of the cardholder associated with the card used for this purchase.

    Max length:50
  • Name
    billAddrLine2
    Type
    string
    is optional
    Description

    Second line of the postal address or local equivalent part of the billing address of the cardholder associated with the card used for this purchase.

    Max length:50
  • Name
    billAddrLine3
    Type
    string
    is optional
    Description

    Third line of the postal address or local equivalent part of the billing address of the cardholder associated with the card used for this purchase.

    Max length:50
  • Name
    billAddrPostCode
    Type
    string
    is optional
    Description

    ZIP or other postal code of the billing address of the cardholder associated with the card used for this purchase.

    Max length:16
  • Name
    billAddrState
    Type
    string
    is optional
    Description

    Three-letter alphabetic code of the country subdivision that represents the state or province of the billing address of the cardholder associated with the card used for this purchase. Values: See ISO 3166-2 format

    Max length:3
  • Name
    email
    Type
    string
    is optional
    Description

    The email address associated with the account that the Cardholder entered or that is archived with the 3DS Requestor.

    Format:email
    Max length:254
  • Name
    homePhone
    Type
    PhoneProperties
    is optional
    Description

    Accepted values according to specification See format ITU-E.164

  • Name
    mobilePhone
    Type
    PhoneProperties
    is optional
    Description

    Accepted values according to specification See format ITU-E.164

  • Name
    cardholderName
    Type
    string
    is optional
    Description

    Name of the cardholder.

    Max length:45
    Min length:2
  • Name
    shipAddrCity
    Type
    string
    is optional
    Description

    Full or partial name of the city of the shipping address provided by the cardholder.

    Max length:50
  • Name
    shipAddrCountry
    Type
    string
    is optional
    Description

    The three-letter alphabetic code that relates to the country of the shipping address provided by the Cardholder. Values: See ISO 3166-1 format

    Max length:3
    Min length:3
  • Name
    shipAddrLine1
    Type
    string
    is optional
    Description

    First line of the postal address or local equivalent part of the shipping address provided by the cardholder.

    Max length:50
  • Name
    shipAddrLine2
    Type
    string
    is optional
    Description

    Second line of the postal address or local equivalent part of the shipping address provided by the cardholder.

    Max length:50
  • Name
    shipAddrLine3
    Type
    string
    is optional
    Description

    Third line of the postal address or local equivalent part of the shipping address provided by the cardholder.

    Max length:50
  • Name
    shipAddrPostCode
    Type
    string
    is optional
    Description

    ZIP or other postal code of the shipping address provided by the cardholder

    Max length:16
  • Name
    shipAddrState
    Type
    string
    is optional
    Description

    Three-letter alphabetic code of the country subdivision that represents the state or province of the shipping address provided by the cardholder. Values: See ISO 3166-2 format

    Max length:3
  • Name
    workPhone
    Type
    PhoneProperties
    is optional
    Description

    Accepted values according to specification See format ITU-E.164

  • Name
    merchantRiskIndicator
    Type
    merchantRiskIndicator
    is optional
    Description

    Merchant assessment of the fraud risk level for the specific authentication.

  • Name
    addPriorInformation
    Type
    string
    is optional
    Description

    Indicates the type of authentication request.

    Values:

    • Y - Requests 3DSS to Add PRIOR information
    • N - Requests Not to Add PRIOR information
    Example:Y
    Max length:1
    Min length:1
  • Name
    threeDSRequestorPriorAuthenticationInfo
    Type
    threeDSRequestorPriorAuthenticationInfo
    is optional
    Description

    Information about how the 3DS Requestor authenticated the cardholder before or during the transaction.

  • Name
    threeDSReqPriorAuthMethod
    Type
    string
    is optional
    Description

    Method that was used by the cardholder for the prior authentication. Values:

    • FRICTIONLESS_AUTHENTICATION (01) frictionless
    • CARDHOLDER_CHALLENGE_OCCURRED (02) with friction
    Example:FRICTIONLESS_AUTHENTICATION
  • Name
    threeDSReqPriorAuthTimestamp
    Type
    string
    is optional
    Description

    Date and time in UTC format of the prior authentication. The format is C, for example 2024-07-15T10:00:00Z.

    Example:2024-07-15T10:00:00Z
  • Name
    threeDSReqPriorRef
    Type
    string
    is optional
    Description

    The ID granted by the ACS in the prior transaction (first authentication).

    Example:abc123
  • Name
    threeDSReqPriorAuthData
    Type
    string
    is optional
    Description

    The ID granted by the DS in the prior transaction (first authentication). If this data is not sent, 3DSS assigns it. Check the session

    Example:xyz789
  • Name
    threeRIInd
    Type
    string
    is optional
    Description

    Indicates if the transaction is recurring. Values:

    • RECURRING_TRANSACTION (01) - Recurring transaction
    • INSTALMENT_TRANSACTION (02) - Installment transaction
    • ADD_CARD (03) - Add card
    • MAINTAIN_CARD_INFORMATION (04) - Maintain card information
    • ACCOUNT_VERIFICATION (05) - Account verification
    • SPLIT_OR_DELAYED_SHIPMENT (06) - Split or delayed shipment
    • TOP_UP (07) - Top up
    • MAIL_ORDER (08) - Mail order
    • TELEPHONE_ORDER (09) - Telephone order
    • WHITELIST_STATUS_CHECK (10) - Whitelist status check
    • OTHER_PAYMENT (11) - Other type of payment
    • BILLING_AGREEMENT (12) - Billing agreement
    • MASTERCARD_3RI_IS_FOR_AN_AGENT_PAYMENT_TRANSACTION (85) - Agent payment transaction for Mastercard
    • MASTERCARD_3RI_FOR_UNKNOWN_OR_UNDEFINED_FINAL_AMOUNT_BEFORE_PURCHASE_TRANSACTION (86) - Transaction for Mastercard with unknown or undefined final amount before purchase
    • VISA_UNSCHEDULED_CREDENTIAL_ON_FILE (81) - Unscheduled credential on file (Visa)

Request

POST
/threeds/v2x/sessions
curl -X "POST" https://3dss-test.placetopay.com/threeds/v2x/sessions \
-H "Content-Type: application/json" \
-d '{
"acctNumber": "4005580000000040",
"cardExpiryDate": "2506",
"purchaseAmount": "20.5",
"purchaseCurrency": "USD",
"redirectURI": "https://www.placetopay.com",
"threeDSAuthenticationInd": "PAYMENT_TRANSACTION",
"reference": "12345"
}'

Response

Response received: 200 OK

To continue with the authentication process, the user must be redirected to the url received in the field (redirectURL). There they will be informed of the authentication result and subsequently, they will be redirected to the merchant.

  • Name
    sessionToken
    Type
    string
    is Required
    REQUIRED
    Description

    Authentication token.

    Example:8e580eb1948ae1b13e614aac04c75ad31d6431ef2ea7b1a85573979b7ec4e656
    Max length:64
    Min length:64
  • Name
    redirectURL
    Type
    string
    is Required
    REQUIRED
    Description

    Redirect URL to continue the authentication process.

    Example:https://3dss-test.placetopay.com/threeds/v2x/sessions/8e580eb1948ae1b13e614aac04c75ad31d6431ef2ea7b1a85573979b7ec4e656
    Max length:256
    Min length:1
  • Name
    transactionID
    Type
    integer
    is Required
    REQUIRED
    Description

    Transaction indicator.

    Example:9099

Response

POST
/threeds/v2x/sessions
{
    "action":"redirect",
    "sessionToken": "8e580eb1948ae1b13e614aac04c75ad31d6431ef2ea7b1a85573979b7ec4e656",
    "redirectURL": "https://3dss-test.placetopay.com/threeds/v2x/sessions/8e580eb1948ae1b13e614aac04c75ad31d6431ef2ea7b1a85573979b7ec4e656",
    "transactionID": 9099
}