Cardknox is now Sola
Learn More
LogoLogo
Contact Us
  • Introduction
  • 🔗API
    • Transaction API
      • Credit Card
      • Check (ACH)
      • EBT
      • Gift Card
      • Fraud
    • Customer and Recurring API
    • Reporting API
    • Account Boarding API
      • Account Boarding Merchant Agreement
      • Account Boarding Swagger UI
    • Code Samples
    • Error Codes
  • 📦SDK
    • .NET SDK
      • Transaction Workflow
    • iOS SDK
      • iOS SDK - Technical Guide
      • Workflow
    • Android SDK
      • Android SDK - Technical Guide
  • 🧰 Cardknox Products
    • 3D Secure 2.0
      • Client-Side Integration
        • Client-Side Integration (Non-iFields)
      • Server-Side Integration
    • Account Updater
    • Batch Processing
    • Browser-Based POS systems (BBPOS)
    • CloudIM Developer Guide
    • Deep Linking
      • Deep Linking Integration for Third-Party Websites
    • EBT Online
    • Gateway Emulators
    • iFields
      • Angular iFields
    • Merchant Portal
      • FAQ
    • Mobile App
    • Split Capture
    • Tap to Phone - Android
    • Partner Portal
    • PaymentSITE
      • QR Codes for PaymentSITE
    • Webhooks
  • 📱Mobile Wallets
    • Apple Pay Hosted Checkout
      • Apple Pay Hosted Checkout Initial Setup
      • Apple Pay Prerequisites
      • Apple Pay Hosted Checkout Objects Reference (Request)
      • Apple Pay Hosted Checkout Objects Reference (Response)
      • Apple Pay iFields Integration
      • Apple Pay Hosted Checkout Sample Code
      • Apple Pay Features
      • Set up Apple Pay Merchant ID with Cardknox
    • Click-To-Pay - Hosted Checkout
      • Click-To-Pay Initial Setup
      • Click-To-Pay Sample Code
      • Click-To-Pay iFields Integration
      • Click-To-Pay Objects Reference (Request)
      • Click-To-Pay Objects Reference (Response)
    • Google Pay Hosted Checkout
      • Google Pay Control Object
      • Google Pay Request Objects
      • Google Pay Response Objects
      • Google Pay Sample Code
      • iFields Integration
      • Google Pay FAQ
  • 🔌Plugins
    • Netsuite
      • NetSuite Features and Demo
    • WooCommerce
    • Magento Plugin
    • RMH (Retail Management Hero)
    • RMS (Retail Management Systems)
  • 📖Articles
    • Frequently Asked Questions
    • How to Build POS Integration Flows
    • Card Present Integration Guide
  • Glossary of Terms
Powered by GitBook
On this page
  • Transaction Components
  • Response Fields

Was this helpful?

Export as PDF
  1. Cardknox Products
  2. 3D Secure 2.0

Server-Side Integration

Last updated 2 years ago

Was this helpful?

Transaction Components

  1. Submit a payment transaction on an account that has 3DS 2.x enabled. See the following request fields in addition to :

    1. Endpoint - accepts the parameters as querystring values or application/x-www-form-urlencoded

    2. Endpoint - accepts the payload in JSON format

Field Name

Required

Description

x3dsReferenceId

Yes

This is the ck3DS.referenceId.

x3dsInitializeStatus

Yes

This is the ck3DS.initializeStatus.

x3dsError

No

This is the ck3DS.error

xBillFirstName

Yes

xBillLastName

Yes

xBillStreet

Yes

xBillCity

Yes

xBillState

Yes

ISO state or province code in 2-digit alpha format.

xBillZip

Yes

xBillCountry

Recommended

ISO country code in 2- or 3- digit alpha format. This will default to 'US' if an unsupported value is submitted.

xBillMobile

Yes

xBillPhone

Recommended

This will default to the value submitted in xBillMobile if not submitted.

xEmail

Yes

xShipFirstName

Recommended

xShipLastName

Recommended

xShipStreet

Recommended

xShipCity

Recommended

xShipState

Recommended

ISO state or province code in 2-digit alpha format.

xShipZip

Recommended

xShipCountry

Recommended

ISO country code in 2- or 3- digit alpha format. This will default to 'US' if an unsupported value is submitted.

Possible xStatus Responses

  • Approved/Declined/Error

To configure behavior on non-authenticated 3DS responses, contact Support.

  • Verify

    • Pass the response object to the client. (The client will call ck3DS.verifyTrans with the response as a parameter to continue the 3DS authentication.)

    • This transaction response contains the 3DS fields necessary for the website to complete the authentication: xVerifyURL, xVerifyPayload, xInternalID, xRefnum, x3dsActionCode

Field Name

Required

Description

x3dsActionCode

Yes

This is the action code passed as the first parameter to ck3DS.configuration.onVerifyComplete.

xVersion

Yes

Cardknox version (current version is 5.0.0)

xCavv

Conditional

Required if x3dsActionCode=SUCCESS. This is the cavv passed as the second parameter to ck3DS.configuration.onVerifyComplete.

xEci

Conditional

Required if x3dsActionCode=SUCCESS. This is the eci flag passed as the third parameter tock3DS.configuration.onVerifyComplete.

xRefnum

Yes

This is the cardknox xRefNum passed as the fourth parameter tock3DS.configuration.onVerifyComplete.

x3dsAuthenticationStatus

Conditional

Required if x3dsActionCode=SUCCESS. This is the authenticate status passed as the fifth parameter tock3DS.configuration.onVerifyComplete.

x3dsSignatureVerificationStatus

Conditional

Required if x3dsActionCode=SUCCESS. This is the signature verification passed as the sixth parameter tock3DS.configuration.onVerifyComplete.

x3dsError

No

This is the ck3DS.error and will contain additional info in case of any errors.

Response Fields

Present on a completed cc:sale/cc:authonly

Field Name

Description

xReviewed

This will be returned only if account is configured to return this response field.

Y: Transaction was authenticated by 3ds. If authentication was submitted to the bank, the merchant will have chargeback protection.

P: Transaction was authenticated by 3ds. If authentication was submitted to the bank, the merchant may not have chargeback protection.

N: Transaction was not able to achieve 3ds authentication. If authentication was submitted to the bank, the merchant may not have chargeback protection. F: The 3ds authentication process completed but the bank response indicated that the results were invalid. The merchant will not have fraud chargeback protection.

x3dsSubmitted

This will be “1” if the bank request included 3ds data elements.

The transaction is complete and no further action is necessary. Jump to .

2. [Conditional: If the previous step returned xStatusofVerify] Submit a verification request to to complete the 3DS authentication and process the payment with the bank. In addition to the standard required fields for and , the following fields may be required:

The transaction response xStatus will be Approved or Declined, and the payment is now complete. below.

🧰
standard required fields for cc:sale and cc:authonly
https://x1.cardknox.com/gateway
https://x1.cardknox.com/gatewayJSON
https://x1.cardknox.com/verify
cc:sale
cc:authonly
3DS response fields
3DS Response Fields