To process 3-D Secure transactions, you must send all the necessary parameters.

Although numerous request parameters are optional, Peach Payments recommends that you send as many parameters as possible. This improves the success rate of risk checks during risk-based authentication and increases the number of frictionless flows.

For more information about the request and response parameters, refer to the API reference guide.

Request parameters

Basic payment data

Browser data

Customer and address details

3-D Secure specific data

Authentication amount and currency

Sometimes, the amount, currency, or both used in the authentication can differ from the one used in the payment later. For example, you might not know the payment amount at the time of the authentication, or you might want to authenticate the customer for the full amount when the customer plans to pay in multiple instalments.

If the authentication amount and the payment amount differ, then you can send the authentication amount and currency in separate fields:

• threeDSecure.amount: Amount for which you are authenticating the customer.
• threeDSecure.currency: Currency for which you are authenticating the customer.

📘

The payment amount and currency are still mandatory fields for any payment request. If you don't define the authentication amount and currency, the customer authenticates with the payment amount and currency.

3-D Secure challenge indicator and MIT agreements

Merchants have the option to specify a preference for whether to challenge for a transaction or not. This does not guarantee that the issuer requests or does not request a challenge from the cardholder. Issuers may consider the merchant's preference during the risk assessment of the transaction. For example, regional mandates might require the challenging of transactions, and the merchant should request a mandated challenge.

Merchants can send the field threeDSecure.challengeIndicator with one of the following values:

* For 04:

• Merchants performing recurring payments must have a merchant-initiated transaction (MIT) agreement with the cardholder. This grants the merchant permission to store the cardholder's card data for future transactions when the cardholder is not present.
• The following requirements apply to MIT agreements:
  • MIT agreements must have an originating cardholder-initiated transaction (CIT).
  • The initial CIT payment request must go through strong customer authentication (SCA).
  • Scheme regulations mandate that merchants must populate threeDSecure.challengeIndicator with the value 04 when sending the initial CIT; this forces the issuer to apply SCA.
  • If these requirements are not met, you could experience payment failures for future MIT requests due to not applying SCA.

📘

For initial 3-D Secure 2 CIT payment requests and any 3-D Secure 2 transactions with the createRegistration parameter set to true, the ChallengeIndicator parameter gets populated with the default value of 04 - Challenge Requested Mandate. This default value gets populated if the merchant has not provided a value for this field; merchant-provided values are not overridden.

Information about the cardholder's account and history with the merchant

The following parameters are not required, but it is strongly recommended that you send them. They affect the accuracy of the issuer's risk check, resulting in more frictionless flows.

The 3-D Secure requestor (the merchant) can collect the parameter values below about the cardholder's activity on their website.

Response parameters

In the returned response, there are two places where 3-D Secure-related response values can be present:

• threeDSecure object: Stores values that are not brand-specific and that any card brand or issuer can return.
• resultDetails object: Stores brand-specific values if the scheme directory server returns such values.

Parameters returned in the threeDSecure object

"threeDSecure": {
    "eci": "05",
    "verificationId": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
    "version": "2.2.0",
    "flow": "challenge",
    "dsTransactionId": "1231-2342-3453-4564",
    "challengeMandatedIndicator": "Y",
    "authenticationType": "2",
    "acsTransactionId": "7777-8797-4645-1233"
}

"threeDSecure":{
    "version":"2.2.0",
    "errorCode":"101",
    "errorDescription":"MerchantCategoryCode must be specified.",
    "errorSource":"3DS Server"
  },

Parameters returned in the resultDetails object

"resultDetails": {
    "ExtendedDescription": "Approved or completed successfully",
    "clearingInstituteName": "Clearing_Institute",
    "ConnectorTxID1": "12345",
    "AcquirerResponse": "00",
    "reconciliationId": "132499881",
    "CB_Authentication_value_algorithm": "2",
    "CB_Score": "55"
}

Response codes

Refer to the response codes section for information about the possible response codes.