Search the Aria Knowledgebase for
User Documentation, APIs, SDKs, and more!



 

Home > 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. 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, and Worldpay 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
  • 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 API):
      • <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>
    • Allowable values in the <proc_3dsecure_data> array (in the authorize_electronic_payment_m or validate_acct_fraud_scoring_m API):

      • <pa_3ds_df_method_url>
      • <pa_3ds_message_version>
      • <payer_auth_reference_id>
    • Allowable values in the <proc_3dsecure_data> array (in the authorize_electronic_payment_m or update_payment_method_m  API):

      • <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>.
  2. 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. Some payment gateways will ask the account holder to enter additional information for verification purposes. 
  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. 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
client_no long 22 Aria-assigned unique identifier indicating the Aria client providing service to this account.
auth_key string 32 Aria-assigned unique key to be passed with each method call for authenticating the validity of the requestor.

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

  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.
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.
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.
End of proc_3dsecure_data_array
Last modified

Tags

This page has no custom tags.

Classifications

This page has no classifications.