authorize_3dsecure_m Guide

Last updated
Save as PDF

Authorizes a credit card for a specified amount when 3DSecure is required. Please note: This API call does not collect a payment.

API Specification:	authorize_3dsecure_m
Required Fields:	<client_no> <auth_key> <acct_no> or <client_acct_id>

Additional Guidance:

To use this API, you must have 3DS enabled and configured in your payment gateway. Contact your payment gateway representative for setup information and additional documentation.

This API call does not collect a payment.
Not all payment gateways require all of the fields and steps described below.
Currently, only Braintree, CyberSource, Adyen, Worldpay, and Ingenico support 3DS 2.0. The payment gateways documentation identifies other payment gateways that support 3DS 1.0.
If you want to use 3DS 2.0, first complete the identified fields in your payment gateway configuration.
Not all payment gateways support the fraud protection features provided by the validate_acct_fraud_scoring_m API. Please check the list of supported features for your payment gateway for more information.
If you use Direct Post, please see the Form of Payment Page Inputs documentation to identify the 3DS-related API input fields that you should pass into your form of payment page.

Your payment gateway may or may not require the specified 3DS 2.0 configuration fields. Please contact your payment gateway representative for more information about which version of 3DS is supported and other details.

3DS applies to Visa, Mastercard, American Express, Discover, and JCB (Japan Credit Bureau) for supported payment gateways. Please check your payment gateway documentation to find out the payment methods to which 3DS applies.

Example: to perform 3DS authentication, when an account holder makes a purchase with a credit or debit card:

Use one or more of the inputs and outputs in the APIs listed below based on your payment gateway's requirements:

APIs

Inputs and Outputs

Inputs:

<attempt_3d_secure> (pass true into this field)
<end_user_session_id>
<end_user_browser_accept_header>
<end_user_browser_agent>
In the <proc_field_override> array (in the authorize_electronic_payment_m or update_payment_method_m APIs):
- <pa_3ds_completion_ind>
- <pa_3ds_trans_status>
- <payer_auth_reference_id>
- <payer_auth_transaction_id>
- <payer_auth_transaction_mode>
- <end_user_ip_address>
- <end_user_browser_accept_header>
- <end_user_browser_agent>
- <end_user_browser_color_depth>
- <end_user_browser_java_enabled_ind>
- <end_user_browser_language>
- <end_user_browser_screen_height>
- <end_user_browser_screen_width>
- <end_user_browser_timezone_offset_mins>

Outputs:

<payer_auth_reference_id>
<proc_payer_auth_request>
<proc_pymnt_id>
<proc_redirect_issuer_url>
<proc_md>
<proc_initial_auth_txn_id>
Allowable values in the <proc_3dsecure_data> array (in the authorize_electronic_payment_m or validate_acct_fraud_scoring_m APIs):
- <pa_3ds_df_method_url>
- <pa_3ds_message_version>
- <payer_auth_reference_id>
- <redirect_issuer_url>
Allowable values in the <proc_3dsecure_data> array (in the authorize_electronic_payment_m or update_payment_method_m APIs):
- <pa_3ds_form_action>
- <pa_3ds_js_lib_url>
- <payer_auth_reference_id>
- <payer_auth_transaction_id>
- <client_auth_token>
- <pa_3ds_df_post_url>
- <pa_3ds_cs_post_url>
Returned by your payment gateway: <client_3ds_nonce> field name and value that you will pass into the <proc_field_override array>.

Notes:

If the <attempt_3d_secure> input is passed as 'false', then the 3DS flow will be skipped and regular authorization will be invoked (the remaining steps in this procedure will not be followed).
If the supplied credit card is not-enrolled with 3DSand if the <attempt_3d_secure> input is passed as 'true' , then the3DS flow will be skipped and regular authorization will be invoked (the remaining steps in this procedure will not be followed).

Complete either a. or b. described below, depending on your payment gateway's requirements:

If your payment gateway already confirmed that the card is enrolled in 3DS and you specified that 3DS is required for the transaction, then:	If your payment gateway did not already confirm that the card is enrolled in 3DS and you specified that 3DS is required for the transaction, then:
Based on your payment gateway's requirements, in the browser, use any applicable outputs from the list above to initiate the 3DS challenge/redirect.	To confirm that the card is enrolled in 3DS, call authorize_3dsecure_m using any required inputs and/or outputs from the list above.
Some payment gateways will ask the account holder to enter additional information for verification purposes.	Based on your payment gateway's requirements, in the browser, use any applicable outputs that are returned by the authorize_3dsecure_m API and listed above. This will initiate the 3DS challenge/redirect.
After the account holder enters the requested information, call authorize_3dsecure_m using any required inputs and/or outputs from the list above.	If the the card is enrolled in 3DS, some payment gateways will ask the account holder to enter additional information for verification purposes.
	Call authorize_3dsecure_m again using any required inputs and/or outputs from the list above.

The payment gateway then authorizes the payment.

Notes:

Not all payment gateways require all of the fields and steps described above.
Not all payment gateways support the fraud protection features provided by the validate_acct_fraud_scoring_m API. Please check the list of supported features for your payment gateway for more information.

Please contact your payment gateway representative for more information about which version of 3DS is supported and other details.

Input Fields

Field Name:

Notes:

<proc_field_override> (array)

<transaction_type>

Some Payment Gateways/Processors do not honor all of the allowable values, so you should check their respective documentation.

Allowable Values

Values	Description
-1	Use client configuration settings for "Send Transaction Type as Recurring for Initial Request Where Possible" or "Send Transaction Type as Recurring for Subsequent Request" as applicable. (default)
1	Single transaction mail/telephone order (MOTO) - Designates a transaction where the accountholder is not present at a merchant location and completes the sale over the phone or through the mail. The transaction is not for recurring services or products and does not include sales that are processed via an installment plan.
2	Recurring Transaction - Designates a transaction that represents an arrangement between an accountholder and the merchant where transactions are going to occur on a periodic basis.
3	Installment Transaction - Designates a group of transactions that originated from a single purchase where the merchant agrees to bill the accountholder in installments.
4	Deferred Transaction - Designates a transaction that represents an order with a payment delayed for a specified amount of time.
5	Secure Electronic Commerce Transaction - Designates a transaction completed via the Internet at a 3-D Secure capable merchant and in which the accountholder was fully authenticated. (examples: 3-D Secure includes Verified by Visa, Mastercard Identity Check, American Express SafeKey and Discover ProtectBuy.)
6	Non-Authenticated Electronic Commerce Transaction - Designates a transaction completed via the Internet at a 3-D Secure capable merchant that attempted to authenticate the accountholder using 3-D Secure (examples: 3-D Secure includes Verified by Visa and Mastercard Identity Check.) Verified by Visa, Mastercard Identity Check, American Express SafeKey and Discover ProtectBuy transactions in the event of: * A non-participating issuer * A non-participating accountholder of a participating issuer * A participating issuer, but the authentication server is not available
7	Channel Encrypted Transaction - Designates a transaction between an accountholder and a merchant completed via the Internet where the transaction includes the use of transaction encryption such as SSL (Secure Sockets Layer), but authentication was not performed. The accountholder payment data was protected with a form of Internet security, such as SSL, but authentication was not performed. For Discover, indicates an e-commerce Card Transaction with data protection in which ProtectBuy for Cardholder authentication was not used.
8	Non-Secure Electronic Commerce Transaction - Designates a transaction between an accountholder and a merchant completed via the Internet where: * The transaction does not include the use of any transaction encryption such as SSL * Authentication is not performed * An accountholder certificate is not managed.
I	IVR Transaction (PINless Debit only) - Designates a transaction where the accountholder completes the sale via an interactive voice response (IVR) system.
R	Retail Transaction - Designates a transaction where the accountholder was present at a merchant location.

<client_3ds_nonce>
<payer_auth_reference_id>
<payer_auth_transaction_mode>
<payer_auth_transaction_id>
<end_user_browser_accept_header>
<end_user_browser_agent>
<end_user_browser_color_depth>
<end_user_browser_java_enabled_ind>
<end_user_browser_language>
<end_user_browser_screen_height>
<end_user_browser_screen_width>
<end_user_browser_timezone_offset_mins>
<pa_3ds_completion_ind>
<pa_3ds_trans_status>

These are 3DS-related fields. Not all payment gateways support 3DS. The payment gateways documentation identifies payment gateways that support 3DS. Please contact your payment gateway representative for more information about which version of 3DS is supported and other details.

<payer_auth_transaction_mode>

Allowable Values

Values	Description
M	MOTO (mail/telephone order)
R	Retail
S	eCommerce
P	Mobile Device
T	Tablet

Output Fields

Field Name:	Notes:
<proc_3dsecure_data> (array)	Not all values for this field apply to all payment gateways. In addition, not all payment gateways support 3DS. The payment gateways documentation identifies payment gateways that support 3DS. Please contact your payment gateway representative for more information about which version of 3DS is supported and other details.