Home > Aria Crescendo Documentation > Aria Crescendo core api > authorize_3dsecure_m

authorize_3dsecure_m

Authorizes a credit or debit card if you specified that 3D Secure (3DS) is required for a particular transaction and the card is enrolled in 3DS; for example, an order over a particular amount that you specify. The 3DS authentication feature provides additional fraud prevention when transactions are processed. This feature requires account holders to provide additional information such as a password when they make an online purchase using a credit or debit card.

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.

Note:

  • 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:

  1. 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 3DS and if the <attempt_3d_secure> input is passed as 'true' , then the 3DS flow will be skipped and regular authorization will be invoked (the remaining steps in this procedure will not be followed).

 

  1. Complete either a. or b. described below, depending on your payment gateway's requirements:
  1. If your payment gateway already confirmed that the card is enrolled in 3DS and you specified that 3DS is required for the transaction, then:
  1. 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:
  1. Based on your payment gateway's requirements, in the browser, use any applicable outputs from the list above to initiate the 3DS challenge/redirect. 
  1. To confirm that the card is enrolled in 3DS, call authorize_3dsecure_m using any required inputs and/or outputs from the list above.
  1. Some payment gateways will ask the account holder to enter additional information for verification purposes. 
  1. 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.
  1. After the account holder enters the requested information, call authorize_3dsecure_m using any required inputs and/or outputs from the list above.
  1. If the the card is enrolled in 3DS, some payment gateways will ask the account holder to enter additional information for verification purposes.
 
  1. 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.

 

For information about error messages generated by this API, see authorize_3dsecure_m Error Messages.

Input Arguments

Req Field Name Field Type Max Length Description
required-icon.png client_no long 22 Aria-assigned unique identifier indicating the Aria client providing service to this account.
required-icon.png auth_key string 32 Aria-assigned unique key to be passed with each method call for authenticating the validity of the requestor.
required-icon.png

acct_no

OR

client_acct_id

long

 

string

22

 

22

Aria-assigned account identifier. This value is unique across all Aria-managed accounts.

Client-defined identifier for the account. This value is unique across all Aria-managed accounts.
  proc_payment_id string   Processor ID used to identify a transaction requiring 3D Secure authorization.
Please note that this field may also be an output that specifies a processor's payment ID.
  proc_payer_auth_response string   Processor's response received from a client's plugin that approved the transaction requiring 3D Secure authorization.
  end_user_session_id string 32 Processor's customer session identifier for a transaction requiring 3D Secure authorization.
  end_user_ip_address string   IP address used for placing an online order.
  proc_md string   Payment session identifier returned by the card issuer.
Start of proc_field_override array
 

proc_field_override

 array   The processor-specific fields passed as an array of proc_field_name/proc_field_value key-value pairs. The allowable fields and values for the key-value pairs are listed below.
  proc_field_name Field Type Max Length proc_field_value
    brd_arrow.gif transaction_type string 2

Defines a transaction type for Credit Cards and Tokenized Credit Cards. A null value will default to -1.

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

Allowable values for transaction_type:

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.
Note: 3DS-related fields are listed below. 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.
  brd_arrow.gif client_3ds_nonce string 4000 The 3DS enriched nonce (token) used for the card authorization.
  brd_arrow.gif payer_auth_reference_id string 2000 Reference ID for a 3DS transaction session.
  brd_arrow.gif payer_auth_transaction_mode string 1

The transaction mode identifies the channel from which the 3DS transactions are originated.

Allowable values for payer_auth_transaction_mode:

Values Description
M MOTO (mail/telephone order)
R Retail
S eCommerce
P Mobile Device
T Tablet
  brd_arrow.gif payer_auth_transaction_id string 2000 Authentication transaction ID for a 3DS authorization.
  brd_arrow.gif end_user_browser_accept_header string 2000 Browser accept header that was used for making a purchase online.  Example: "text/html,application/xhtml+xml,application/xml ;q=0.9,&ast;/&ast;;q=0.8".      
  brd_arrow.gif end_user_browser_agent string 2000 Browser that was used for making a purchase online. Example: "Mozilla/5.0 (X11; Linux i586; rv:31.0) Gecko/20100101 Firefox/31.0".         
  brd_arrow.gif end_user_browser_color_depth string 2000 Browser color depth in bits per pixel. You can obtain this by using the browser's screen.colorDepth property. Accepted values: 1, 4, 8, 15, 16, 24, 32 or 48 bit color depth.            
  brd_arrow.gif  end_user_browser_java_enabled_ind string 2000 Boolean value indicating whether the customer's browser is able to execute Java.
  brd_arrow.gif end_user_browser_language string 2000 Browser supported language (as defined in IETF BCP-Internet Engineering Task Force Best Current Practice 47). You can obtain this by using the browser's navigator.language property.            
  brd_arrow.gif end_user_browser_screen_height string 2000 Total height of the browser that was used for placing an online order.
  brd_arrow.gif end_user_browser_screen_width string 2000

Total width of the browser that was used for placing an online order.
  brd_arrow.gif end_user_browser_timezone_offset_mins string 2000 Difference between UTC (Universal Time Coordinated) time and the customer's browser local time, in minutes.
  brd_arrow.gif pa_3ds_completion_ind string 2000 If the response of DDC (Device Data Collection) is received within 10 seconds set this field to "Y". If not, set this field to "N".    
  brd_arrow.gif pa_3ds_trans_status string 2000 If the response to the challenge shopper  (requested authentication information) is not received within 10 minutes, set this field to "U". If not, set this field to the value received from the challenge shopper response.
End of proc_field_override array
 

Output Arguments

Field Name Field Type Description
error_code long Aria-assigned error identifier. 0 indicates no error.
error_msg string Description of any error that occurred. "OK" indicates no error.
payment_method_no long

Payment method ID number.

proc_cvv_response string The processor return code from CVV (Card Verification Value) validation.
proc_avs_response string Processor return code from address validation.
proc_cavv_response string The processor return code for security validation.
proc_status_code string The processor status code.
proc_status_text string The processor status description.
proc_payment_id string The processor payment ID.
proc_auth_code string Authorization code provided by the issuing bank.
proc_merch_comments string Additional information passed to payment processor.
processor_id long The Payment Processor ID used for external collection or authorization.
proc_initial_auth_txn_id string Transaction ID from payment processor. If received as part of an authorization request, it must be retained for future settlement and match the value from the authorization response. It should also be used for future recurring transactions involving authorization/settlement.
Start of proc_3dsecure_data array
proc_3dsecure_data array

Array of 3D Secure processor-specific fields required for client-side integration. returned as proc_field_name/proc_field_value key-value pairs. The allowable fields and values for the key-value pairs are listed below.

Note: 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.
proc_field_name Field Type proc_field_value
brd_arrow.gif attempt_3ds_auth_challenge string Returns true or false to indicate whether or not the 3DS authorization challenge is enabled for the card.

brd_arrow.gif payer_auth_request

 string  The unique number for a given authorization.
brd_arrow.gif redirect_issuer_url string The URL where you must post the 3DS data to. This will redirect the customer.
brd_arrow.gif md string The payment session identifier returned by the card issuer.
brd_arrow.gif client_auth_token     string  The client authorization token required to map the merchant account with the client JS SDK (JavaScript Software Development Kit).
brd_arrow.gif cc_single_use_token string

The single use token for the credit card.
brd_arrow.gif cc_prefix string

The first six digits of the customer's card number.

Note: For Ingenico 3DS Support, this includes American Express® cards (starting with 3).
brd_arrow.gif pa_3ds_js_lib_url string Your JavaScript Library URL path used for 3DS 2.0.
brd_arrow.gif payer_auth_transaction_id string The unique number for a given transaction.
brd_arrow.gif payer_auth_reference_id string The unique number for a given authorization.
brd_arrow.gif pa_3ds_form_action string This form action is used for a Direct Post call to decide whether to attempt device data collection or credit card authorization.
brd_arrow.gif pa_3ds_df_method_url string Method URL used for Device Fingerprint for 3DS 2.0 transactions.
brd_arrow.gif pa_3ds_message_version string Message/3DS version of the ongoing 3DS authorization.
brd_arrow.gif pa_3ds_form_content string If the issuer’s Access Control Server (ACS) supports this feature, this field will receive content to populate the client’s form page to enable 3DS authentication. If the issuer’s ACS does not support this feature, no information for authentication will be returned to this field.
End of proc_3dsecure_data_array
Last modified

Tags

This page has no custom tags.

Classifications

This page has no classifications.
Powered by CXone Expert ®