3D Secure verification

Boost payment security with 3D Secure support

Solidgate provides 3D Secure support for payments, enhancing security measures for both merchants and customers. To process a payment as a Guide
This process ensures secure, reliable payment processing using 3D Secure authentication to prevent fraud. 3D Secure payment, pass the force3ds parameter as a boolean true value.

When implementing 3DS payments, you may need to display the issuer’s 3D Secure page (ACS URL) if the customer’s issuing bank mandates further authentication. You can set up success_url and fail_url so that your customers are redirected to the correct page when the authentication flow completes (either successfully or unsuccessfully).

For best results with 3DS 2.0, pass necessary browser details, such as user-agent user_agent and time zone offset time_zone_offset, so that you can support frictionless flows when possible.

3D Secure payment flows

Solidgate or the payment processor can trigger 3DS authentication. Whenever 3DS authentication is invoked, you can check the status through:

check order status API request
order status Webhook notification

Common 3D Secure three_ds: flow flow types

frictionless Authentication is complete without additional customer interaction.
challenge Customer must complete extra verification steps, such as entering a one-time passcode (OTP) or using another verification method.
none Authentication was attempted, but the issuer either does not support 3D Secure or did not respond.
unspecified It is unclear if the customer participated in a 3D Secure challenge.

When the flow is null , 3D Secure authentication is not initiated. Additionally, it represents the Electronic Commerce Indicator ( Guide
ECI value represents authentication, affects authorization and liability protection. ECI ) eci security level used to authorize the payment.

External MPI data

Solidgate can also accept external Merchant Plug-In (MPI) data to maintain direct control over 3D Secure authentication. In such scenarios, you initiate the 3DS process through your MPI provider and then pass the MPI results back for payment processing. Benefits of using external MPI:

Control over 3DS authentication
You decide the authentication flow and gather the required data from your provider.
Optimal user experience
You can tailor the authentication process, potentially reducing friction and checkout time for your customers.
Regulatory compliance
You can fulfill 3DS requirements imposed by issuing banks or payment networks.

Steps for handling external MPI:

Perform 3D Secure authentication
Complete the 3DS process with your external MPI provider before you send the payment request.
Capture and store MPI data
Securely capture essential MPI data from your external provider. You will need the following required, parameters, such as three_ds_version, three_ds_flow, ds_enrollment_response, eci, cryptogram, authentication_response, and ds_transaction_id.
Submit payment request
Place the captured MPI data in the external_mpi_data object within your payment request. You can do this for one-time charges API , recurring API charges, or resign API charges.
Handle the payment response
Review the response and process successful payments. Handle exceptions where necessary.

MPI data insights

Below is a consolidated set of parameters you should pass when supplying external MPI data. These parameters apply to 3DS 2.x flows and provide the context your payment request needs to complete with liability shift and authentication details.

Value	Description
ds_enrollment_response	Y - Card is enrolled; authentication is possible.
	N - Card is not enrolled.
	U - Enrollment status is unknown.
authentication_response	Y - Authentication verification successful.
	N - Not authenticated / account not verified; transaction is denied.
	U - Authentication / account verification could not be performed; technical or other problem, as indicated in ARes or RReq.
	A - Attempts processing is performed; not authenticated or verified, but proof of the attempt is provided.
	C - Challenge is required; additional authentication is needed using the CReq and CRes.
	D - Challenge is required; decoupled authentication is confirmed (Solidgate does not support it).
	R - Authentication / account verification is rejected; the issuer rejects authentication or verification and requests that authorization is not attempted.
	I - Informational only; the 3DS requestor challenge preference is acknowledged.
	S - Challenge using Secure Payment Confirmation (SPC).
authentication_method	01 - Static passcode.
	02 - SMS One-Time Password (OTP).
	03 - Key fob or Europay, Mastercard, Visa (EMV) card reader OTP.
	04 - App OTP.
	05 - OTP other.
	06 - Knowledge-based authentication (KBA).
	07 - Out-of-band (OOB) biometrics.
	08 - OOB login.
	09 - OOB other.
	10 - Other.
	11 - Push confirmation.
	12 - Decoupled authentication (Solidgate does not support it).
	14 - SPC.
	15 - Behavioural biometrics.
	16 - Electronic ID.
	17–79 - Reserved for EMVCo future use (values invalid until defined by EMVCo).
	80–99 - Reserved for DS use.

Errors handling

If 3D Secure authentication via an external MPI provider returns an error (other than a declined transaction), you may proceed with a non-3DS payment request if you determine that the risk is manageable. To do so, you can submit a normal payment request without including the force3ds parameter. Common errors:

UUID compliance: ds_transaction_id must comply with the RFC 4122 UUID standard.
Missing
- ds_transaction_id
  Required for 3DS 2 with certain eci values (e.g., 01 , 02 , 05 , or 06 ).
- three_ds_version
  You must include a valid version when using external MPI data.
Unsupported 3DS Version: 3DS version 1 is deprecated; please upgrade to 3DS 2.

Looking for help? Contact us

Stay informed with Changelog