3D Secure (3DS)

This guide explains the integration process for the 3D Secure feature, including the necessary endpoints and webhooks you need to integrate into your solution.

Introduction

What is 3DS?

3D Secure (3DS) (also known as payer authentication) is a security protocol that adds an additional layer of protection to online credit and debit card payments. "3DS" refers to three domains which interact using the protocol: the merchant/acquirer domain, the issuer domain, and the interoperability domain.

How does 3DS work?

3DS requires customers to complete an additional verification step with their card issuer during the final stage of checkout in an e-commerce transaction. Typically, customers get forwarded to their bank to authenticate the payment by entering a one-time SMS code, biometrics, bank app, or other authentication methods. Some common examples of 3DS include Verified by Visa, Mastercard SecureCode, and American Express SafeKey.

3DS reduces the risk of fraud and increases protection for both the seller (merchants) and the cardholder (customers). As 3DS payments are considered secure, the customer's bank becomes liable for any fraud, which makes it a powerful tool for online sellers.

European PSD2 and Strong Customer Authentication (SCA) regulations require the use of 3DS for online card payments. PSD2 requires all issuers to apply Strong Customer Authentication (SCA) for 3DS online payments, which includes two-factor authentication (2FA). For more information about how to implement SCA in your solution, see the Strong Customer Authentication guide.

note

Please note that not all transactions require SCA. To find out more about SCA use cases and their associated authentication methods, see the SCA use cases.

3DS with Solaris cards

Solaris offers the following authentication methods for 3DS. Both methods are accessed through your application:

  • In-app method: A biometric factor inside a mobile banking app (in-app push notifications, i.e., device signing).
  • SMS OTP: A one-time password (OTP) sent to customers via SMS on their verified mobile number.
note

You are required to provide both options to your customers. Additionally, you must display the merchant name and the amount to the cardholder during the authentication process.

Requirements

You must implement the following features in your solution before you can implement 3DS:

  1. Customer onboarding with Digital Banking & Cards (debit, credit, or decoupled)
  2. Device binding
  3. Strong Customer Authentication
  4. Device monitoring

Only customers who have been successfully onboarded and identified with an active Solaris account and card (debit, credit, or decoupled) can use 3DS.

Additionally, you must subscribe to the following webhook events:

For more information on subscribing to webhook events, check the dedicated guide.

Authentication steps

  1. The cardholder initiates the process when paying by card on an e-commerce website.
  2. The Access Control Server (ACS) receives the 3DS transaction via the card scheme (e.g., Visa or Mastercard).
  3. The ACS checks if authentication is required for the transaction and sends a notification to Solaris to authenticate the user.
  4. Solaris sends you a notification on the webhook event SCA_CHALLENGE. The webhook payload includes the authenticate_change_request_id attribute, which is the change_request_id value you need to pass to the change request endpoints.
  5. Send a push notification to the cardholder's mobile app informing them that they must authorize the 3DS challenge.
  6. The customer should log into your application to accept the 3DS challenge.
  7. Once the customer decides to accept the 3DS challenge, present them with the option in your frontend to authorize via in-app device signing or SMS OTP.
  8. Trigger the authentication process by calling POST Authorize change request. Use the delivery_method requested by the customer.
  9. The customer then authorizes the transaction by signing the challenge with the device's unrestricted key or the SMS OTP received from Solaris.
  10. Confirm the authentication by sending the customer's device signature or SMS OTP to Solaris using POST Confirm change request.
  11. Solaris sends the cardholder's authentication response to the online merchant via the ACS.
  12. The merchant sends the transaction to the Card Processor (CP) for a final confirmed/declined authorization.
  13. (Decline without change request) If the customer wants to decline the 3DS challenge, call the POST/v1/cards/3ds/{challenge_id}/decline endpoint using the challenge_id provided in the SCA_CHALLENGE webhook payload. This endpoint does not use the change request process.

Step 1: Webhook notification

When customers initiate an online card payment and the ACS receives the transaction and notifies Solaris, you'll receive a notification on the webhook event SCA_CHALLENGE. The payload includes the details of the transaction and the authenticate_change_request_id, which is the change_request_id required in the following steps.

Click here to view a sample SCA_CHALLENGE webhook payload.

Step 2: Authorize change request

POST Authorize change request

After receiving the webhook notification, trigger the change request process by calling the following endpoint. Supply the value of the authenticate_change_request_id property from the webhook payload as the change_request_id in the request URL. Additionally, add the following properties in the request body:

Parameter Description
delivery_method The method to deliver the authorization challenge.
device_id The ID of the customer's registered device approving the transaction. Only include this property if the delivery_method is device_signing.
person_id The person to whom the SMS OTP should be sent. Only include this property if the delivery_method is mobile_number.
device_data Base64-encoded device data collected using the Seon SDK. Details about how to integrate the Seon SDK can be found in the device monitoring guide.

Request URL

Copy
Copied
POST /v1/change_requests/{change_request_id}/authorize

Response

The API returns a change request object with a unique id, which you must use in the next API call. If you used device signing, then the API will also return the string for the customer's device to sign in the string_to_sign property.

Click here to view the full API reference.

Step 3: Notify customer & solve challenge

Now you must send a push notification to the customer informing them that a transaction requires their approval.

When they open your app, you should offer them an interface for resolving the open 3DS challenge:

  • For device signing, prompt them to sign the challenge using their device.
  • For SMS OTP, prompt them to enter the six-digit code they received from Solaris.

(Device signing only) Collecting the customer's signature

The customer's device must sign the string contained in the string_to_sign attribute of the response from the previous API call using its unrestricted key. See the instructions below:

How to sign:

  1. Create a hash (SHA256) with the string_to_sign.
  2. Sign the hash with the device's private key.
  3. Encode the signature in ASN.1 format.
  4. Hex encode the ASN.1 format signature.

POST Confirm change request

Now pass the signature string or the six-digit SMS OTP to Solaris by calling the following endpoint. You have to add the change_request_id to the request URL and supply the following properties in the request body:

Parameter Description
device_id (If the delivery_method was device_signing) The ID of the customer's bound device used for authorization.
signature (If the delivery_method was device_signing) The hex-encoded signature generated by signing the text_to_sign with the device's public key.
person_id (If the delivery_method was mobile_number) The ID of the person who received the SMS OTP for authorization.
tan (If the delivery_method was mobile_number) The six-digit OTP value that the person received via SMS.
device_data Base64-encoded device data collected using the Seon SDK. Details about how to integrate the Seon SDK can be found in the device monitoring guide.

Request URL

Copy
Copied
POST /v1/change_requests/{change_request_id}/confirm

Click here to view the full API reference.

Once the cardholder authorizes the transaction, Solaris sends the cardholder's authentication response to the online merchant via the ACS. Then, the merchant sends the transaction to the Card Processor (CP) for a final confirmation or rejection.

Step 4: Decline a 3DS challenge without change request

If the customer wants to decline the 3DS challenge, you can call the following endpoint to decline the challenge without using the change request process.

POST Decline a 3DS authentication

Call this endpoint to decline a 3DS challenge and add the challenge_id returned in the SCA_CHALLENGE webhook payload in the request URL.

Request example

Copy
Copied
POST /v1/cards/3ds/{challenge_id}/decline

Click here to view the full API reference.

Testing

Solaris offers a number of endpoints for testing different 3DS scenarios. Note that these endpoints are only available on Sandbox.

Create test 3DS transaction

This endpoint creates a test 3DS transaction for a card. The API will return a JSON schema containing the HTML for the 3DS challenge screen.

URL:

Copy
Copied
POST /v1/cards/{card_id}/test_3ds_authentication

Click here to view the full API reference.

Simulate an authorization

This endpoint creates a simulated card authorization for the purpose of testing approval & denial flows.

URL:

Copy
Copied
POST /v1/cards/{card_id}/simulator/transactions/authorization

Click here to view the full API reference.

Simulate the settlement of an authorization

This endpoint executes a test card authorization settlement for the given card and transaction_key (retrieved from the endpoint described above).

URL:

Copy
Copied
POST /v1/cards/{card_id}/simulator/transactions/{transaction_key}/settle

Click here to view the full API reference.

Simulate an unauthorized settlement

This endpoint creates a simulated unauthorized settlement. It returns a transaction_key that corresponds with the settlement.

URL:

Copy
Copied
POST /v1/cards/{card_id}/simulator/transactions/settle

Click here to view the full API reference.

Simulate an expired card authorization

Use this endpoint to mark a test authorization (created using the Simulate an authorization endpoint) as expired.

URL:

Copy
Copied
POST /v1/cards/simulator/authorization/{transaction_key}/expire

Click here to view the full API reference.

Appendix I: Glossary

  • 3DS: 3D Secure
  • ACS: Access Control Server (external service provider)
  • CP: Card processor (external service provider)
  • MPI: Merchant Plug-in (an external service provider that merchants use to connect to the servers of card schemes, e.g., Visa or Mastercard)
  • OTP: One-time password