Skip to main content

3-D Secure authentication

3-D Secure (3DS) is an authentication service that allows you to verify the identity of your cardholder prior to completing the payment authorization or verification. A successful authentication can:

  • Reduce fraudulent card transactions
  • Shift the cost liability of fraud-related chargebacks to the card issuer
  • Help you to meet EU/UK Payment Services Directive 2 (PSD2) Strong Customer Authentication (SCA) requirements

Before you begin

To begin authenticating cardholders using 3DS, you must first choose and integrate with the 3-D Secure API. 

Who should use 3DS authentication?

In general, you would leverage 3DS authentication if you have consumers in Europe (or another market where 3DS is required), or if you want to reduce your card payments risk liability. We support the following 3DS options on our Commerce platform:

  • 3DS API — Manage the entire 3DS workflow yourself separate from the card payment process.
  • Pass-through 3DS — Pass-through 3DS values obtained from a 3DS provider in your payment transactions to J.P. Morgan.

How 3DS works

  1. Your consumer places an order on your website.
  2. If you determine that the purchase warrants authentication, send a 3DS authentication request to the 3DS API. Reasons a transaction warrants authentication may include:
    • The authentication is mandated by a regulation like PSD2 in Europe.
    • The cardholder is a new consumer with whom you have no prior business relationship.
    • The item being purchased is a common target for fraudulent purchases.
    • To enable future recurring payment Merchant Initiated Transactions (MIT).
    • Adding a consumer's card details to a merchant’s file (card-on-file).
  3. The 3DS API passes the authentication request through to the card issuer.
  4. The card issuer processes the authentication one of two ways:
    1. Frictionless — The issuer completes the authentication using only information from the authentication API call and device information from the browser.
    2. Challenge — The issuer prompts the cardholder to provide additional information to complete the authentication.
  5. The issuer returns the authentication results to you via the 3DS API.
  6. If authenticated successfully, you send the required 3DS authentication and payment details to Managed Recurring Payments using a POST /recurringprograms call to complete the transaction.

Pass-through 3DS

You can use Pass-through 3DS if you are using a 3DS authentication provider, like the 3DS API. This allows you to perform the full authentication flow via the 3DS API and use the 3DS results in the Managed Recurring Payments transactions.

Specific values are provided to you in the 3DS authentication response that must be mapped to the appropriate request fields without altering the field values. Fields to populate with pass-through 3DS authentication data are:

Pass-through 3DS authentication fields
Field name Description
authentication.threeDS.authenticationValue 3DS Base64 cryptogram obtained prior to the payment request.
authentication.threeDS.authenticationTransactionId The directory server transaction ID.
authentication.threeDS.threeDSProgramProtocol Value based on the version of 3DS used to complete the authentication.
authentication.electronicCommerceIndicator The outcome of the authentication.

Electronic Commerce Indicator (ECI) values for 3DS

The 3DS API will send you these ECI values in the authentication response, which you will pass in the request.

  • Fully authenticated  — The issuer has successfully authenticated the cardholder. 
  • Attempted authentication  — The issuer did not attempt to authenticate, but the card brand did and was successful. 
  • Not authenticated — The authentication failed.
ECI values for 3DS
Type Visa Mastercard/International Maestro American Express Discover/Diners Japan Credit bureau Union Pay
Fully-authenticated 05 02 05 05 05 05
Attempted authentication 06 01 06 06 06 06
Not authenticated 07 00 07 07 07 07

Method: POST

Endpoint: /recurringprograms

Scenario: Creating a new recurring program for an existing consumer and payment method with 3DS authentication details.

Json
{
    "consumerProfile": {
        "consumerProfileId": "JPMCW-CQFA05GK4OIBWKH2",
        "paymentMethodId": "9d8b7667-f604-4536-a4eb-1513093508b1"
    },
    "merchantRecurringProgramId": "YOUR_RECUR_PROG_ID_002",
    "recurringProgramName": "Your New Recurring Program Text Label",
    "recurringProgramDescription": "Your New Recurring Program Text Notes",
    "startDate": "2024-09-12",
    "endDate": "2024-09-30",
    "recurringProgramAutoRenewable": false,
    "planId": "XixLPpKQyk",
    "recurringPlanDefault": true,
    "communicationPreference": {
        "preferredEmail": "your.consumer@email.com",
        "preferredEmailOptin": true
    },
    "merchantSalesChannelName": "INTERNET",
    "authentication": {
        "electronicCommerceIndicator": "05",
        "threeDS": {
            "authenticationValue": "kEyn7YFi1EUAREAAAAvNUe6Hv812",
            "authenticationTransactionId": "01ade6ae340005c681c3a1890418",
            "threeDSProgramProtocol": 2
        }
    }
}

Response:

Json
{
    "recurringProgramId": "kRARQI0Dfm",
    "merchantId": "998152096533",
    "requestId": "f2ebe284-32b2-4bb5-a873-a5cafccbd6bb",
    "consumerProfile": {
        "consumerProfileId": "JPMCW-CQFA05GK4OIBWKH2",
        "paymentMethodId": "9d8b7667-f604-4536-a4eb-1513093508b1",
        "paymentMethodType": {
            "card": {
                "cardType": "MC",
                "last4CardNumber": "5114",
                "first6CardNumber": "511234",
                "maskedAccountNumber": "511234XXXXXX5114"
            }
        }
    },
    "merchantRecurringProgramId": "YOUR_RECUR_PROG_ID_002",
    "recurringProgramName": "Your New Recurring Program Text Label",
    "recurringProgramDescription": "Your New Recurring Program Text Notes",
    "startDate": "2024-09-12",
    "endDate": "2024-09-30",
    "recurringProgramAutoRenewable": false,
    "planId": "XixLPpKQyk",
    "merchantPlanId": "Your_PLAN_ID",
    "planName": "Your Plan Text Label",
    "billingFrequencyUnit": "DAYS",
    "billingFrequencyCount": 1,
    "recurringPlanDefault": true,
    "recurringProgramQuantity": 1,
    "recurringProgramAmount": 1000,
    "currencyCode": "USD",
    "recurringProgramStatus": "SCHEDULED",
    "statusChangeDate": "2024-09-11T22:41:21.580735",
    "communicationPreference": {
        "preferredPhoneOptIn": false,
        "preferredEmail": "your.consumer@email.com",
        "preferredEmailOptin": true
    },
    "paymentMethodTypeVerification": {
        "transactionId": "5b1ae3eb-e111-4356-8a12-47ca931f3d13",
        "transactionDate": "2024-09-11T22:41:21.669Z",
        "responseStatus": "SUCCESS",
        "approvalCode": "tst954",
        "hostMessage": "Transaction accepted"
    },
    "billingInformation": {
        "billingCyclesTotalCount": 19,
        "billingCyclesProcessedCount": 0,
        "billingCyclesPaymentSuccessCount": 0,
        "billingCyclesPaymentFailureCount": 0,
        "currencyCode": "USD",
        "pastDueAmount": 0,
        "creditAmount": 0
    },
    "merchantSalesChannelName": "INTERNET",
    "authentication": {
        "electronicCommerceIndicator": "05"
    },
    "isBillPayment": false
}

You can also send authentication details for a new payment method that is added to an existing recurring program.

Method: PATCH

Endpoint: /recurringprograms/kRARQI0Dfm

Scenario: Updating an existing recurring program with a new payment method and 3DS authentication details.

Json
{
    "consumerProfile": {
        "consumerProfileId": "JPMCW-CQFA05GK4OIBWKH2",
        "paymentMethodType": {
            "card": {
                "accountNumber": "4470051311111111118",
                "cardExpirationMonthYearNumber": "02/2027",
                "firstName": "First",
                "middleName": "Middle",
                "lastName": "Last",
                "billingAddress": {
                    "firstName": "First",
                    "lastName": "Last",
                    "line1": "4010 Baker St",
                    "line2": "Apt 123",
                    "state": "FL",
                    "city": "Tampa",
                    "postalCode": "304230",
                    "countryCode": "USA"
                }
            }
        }
    },
    "authentication": {
        "electronicCommerceIndicator": "05",
        "threeDS": {
            "authenticationValue": "kEyn7YFi1EUAREAAAAvNUe6Hv812",
            "authenticationTransactionId": "01ade6ae340005c681c3a1890418",
            "threeDSProgramProtocol": 2
        }
    }
}

Response:

Json
{
    "recurringProgramId": "kRARQI0Dfm",
    "merchantId": "998152096533",
    "requestId": "cf135724-13c8-4125-b77e-0fbc31ff87d5",
    "consumerProfile": {
        "consumerProfileId": "JPMCW-CQFA05GK4OIBWKH2",
        "paymentMethodId": "7c11ab9b-0147-4d78-8037-bd3edc1f3573",
        "paymentMethodType": {
            "card": {
                "cardType": "VI",
                "last4CardNumber": "1118",
                "first6CardNumber": "447005",
                "maskedAccountNumber": "447005XXXXXXXXX1118",
                "originalNetworkTransactionId": "014255692160441"
            }
        }
    },
    "merchantRecurringProgramId": "YOUR_RECUR_PROG_ID_002",
    "recurringProgramName": "Your New Recurring Program Text Label",
    "recurringProgramDescription": "Your New Recurring Program Text Notes",
    "startDate": "2024-09-12",
    "endDate": "2024-09-30",
    "recurringProgramAutoRenewable": false,
    "planId": "XixLPpKQyk",
    "merchantPlanId": "YOUR_PLAN_ID",
    "planName": "Your Plan Name",
    "billingFrequencyUnit": "DAYS",
    "billingFrequencyCount": 1,
    "recurringPlanDefault": true,
    "recurringProgramQuantity": 1,
    "recurringProgramAmount": 1000,
    "currencyCode": "USD",
    "recurringProgramStatus": "SCHEDULED",
    "communicationPreference": {
        "preferredPhoneOptIn": false,
        "preferredEmail": "your.consumer@email.com",
        "preferredEmailOptin": true
    },
    "paymentMethodTypeVerification": {
        "transactionId": "311f2498-a664-4301-b1a1-de61f0144a04",
        "transactionDate": "2024-09-11T22:58:07.155Z",
        "responseStatus": "SUCCESS",
        "approvalCode": "tst549",
        "hostMessage": "Transaction accepted"
    },
    "billingInformation": {
        "billingCyclesTotalCount": 19,
        "billingCyclesProcessedCount": 0,
        "billingCyclesPaymentSuccessCount": 0,
        "billingCyclesPaymentFailureCount": 0,
        "currencyCode": "USD",
        "pastDueAmount": 0,
        "creditAmount": 0
    },
    "authentication": {
        "threeDS": {
            "authenticationTransactionId": "01ade6ae340005c681c3a1890418",
            "threeDSProgramProtocol": "2"
        },
        "electronicCommerceIndicator": "05"
    },
    "isBillPayment": false
}