Purchase - Use 3D Secure (3DSv2)

📘
Note:
To simplify your development and have consistency across the various Purchase requests - all Purchase API calls can also be reached at the following endpoint with any combination of the required Purchase... parameters :
https://<<test_api_url>>/v3/payment/sale/

QorCommerce supports processing sales for cardholders authenticated by Visa ("Verified by Visa"), MasterCard ("SecureCode"), Amex ("SafeKey"), Discover ("ProtectBuy") and JCB ("J/Secure") though 3-D Secure for eCommerce transactions.

3-D Secure allows enrolled cardholders to be authenticated with a password or PIN before processing any online payments. Sales based on a 3-D Secure authentication are much more secure and the merchant benefits from the payment guarantee (liability shift).

3-D Secure is possible for online internet, browser-based payments only. This API supports host payment authorization when required 3-D Secure digital signatures are present.

More information on 3-D Secure can be found here…

Process

The client app passes the cardholder's credit card data and purchase information as required by the 3-D Secure provider.
The cardholder's internet browser forwards the 3-D Secure request to the card issuing bank.
The customer authenticates their enrolled card with a PIN, password, certificate or any other secure identification methods required by the 3-D Secure provider.
The result of the authentication is returned to the customers browser with values required by QorCommerce to process a 3-D Secure authenticated transaction.
The client app creates a 3-D Secure sale request with the minimum required values and POSTS request to this endpoint.
QorCommerce checks the request and required parameters values. If present QorCommerce will submit the transaction to the host processor for approval.

Parameters

The following parameters are available to process a 3-D Secure authenticated sale.

parameter	description	required
mid	the Merchant ID (MID) assigned by QorCommerce or your merchant service provider (MSP)	Yes
topt	Type Of Payment Transaction - set a value to simply tag and/or route a transaction to a pre-defined provider.	No
reference_id	A reference id that will be echo'd back in the message response.	No
amount	the total amount to process that MUST equal the sum of all total_amount parameter values in the items object array (see below)	Yes
service_charge	the amount of the total sum of this transaction that is made up of the service_charge	No
creditcard	the credit card number	Yes
month	the card expiration month	Yes
year	the card expiration year	Yes
cvv	the card verification value	Yes
cardfullname	the name printed or embossed on the front of the credit card	Yes if store_card value is `true`
baddress	the card billing street address	No
baddress2	the card billing street 2 address	No
bcity	the card billing city name	No
bstate	the card billing state code	No
bzip	the card billing zip code	Yes
bcountry	the card billing country code	No
currency	The currency to process. Defaults to 'USD' if no value provided	No
invoiceid	the merchant invoice id associated with the sale	No
orderid	unique merchant order tracking number	Yes
ipaddress	The IP address of the client or server sending the request	No
cfirstname	the customer first name	No
clastname	the customer last name	No
cemail	the customer email address	No
cphone	the customer phone number	No
response_3DS	Status response from 3-D Secure provider. Possible values are typically `success`, `failure`, `noaction` or `error` but can vary depending on provider	Yes
CAVV	The 3-D Secure Cardholder Authentication Verification Value (MasterCard's UCAF value) Must be 28-32 chars in length	Yes
ECIFlag	Electronic Commerce Indicator `0` = Payment has been flagged as SSL secured transaction `1` = Payment has been flagged as SSL 3-D Secure authentication transaction (cardholder enrolled) `2` = Payment has been flagged as SSL 3-D Secure authentication transaction (cardholder not enrolled or partial authenticated)	Yes
XID	3-D Secure Transaction Identifier	Yes
risk_score	risk score associated to this transaction (*if you are using a risk prevention system)	No
store_card	if `true` will store card in the QorCommerce Vault and return a card token	No

JSON Example

The following JSON example provides test values to process a 3-D Secure authenticated sale. You can copy and paste these values in the Body Params section below to be used by the Try It feature

{
  "transaction_data": {
      "mid": "887728202",
      "amount": "86.41",
      "creditcard": "5544044490909090",
      "cvv": "123",
      "month": "12",
      "year": "22",
      "bzip": "23443",
      "cardfullname": "Endframe Systems",
      "currency": "USD",
      "invoiceid": "INV-123123",
      "orderid": "124531541",
      "ipaddress": "0.0.0.0",
      "baddress": "1338 Westport Dr",
      "baddress2": "Suite 300",
      "bcity": "Santa Clara",
      "bstate": "CA",
      "bcountry": "US",
      "cfirstname": "Dinesh",
      "clastname": "Chugtai",
      "cemail": "[email protected]",
      "cphone": "415.343.1231",
      "cwebaddress": "endframe-sys.com",
      "3DS_response": "",
      "CAVV": "",
      "ECIFlag": "",
      "XID": "",
      "risk_score": 0,
      "store_card": 0
  }
}

Store Card Option

You can store the credit card information provided in the QorCommerce Secure Vault by setting the store_card parameter to true. The response will provide a token value representing the credit card that you can associate with your customer and/or a contract to use for a future payment in place of credit card data when needed.

Response Codes

Link to details on related response codes.

Payment Response Codes