Server-Side Integration

Transaction Components

  1. 1.
    Submit a payment transaction to https://x1.cardknox.com/gateway on an account that has 3DS 2.x enabled. See the following request fields in addition to standard required fields for cc:sale and cc:authonly:
Field Name
Required
Description
x3dsReferenceId
Yes
This is the ck3DS.referenceId.
x3dsInitializeStatus
Yes
This is the ck3DS.initializeStatus.
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
2. [Conditional: If the previous step returned xStatusofVerify] Submit verification request to https://x1.cardknox.com/verify to complete the 3DS authentication and process the payment with the bank. In addition to standard required fields for cc:sale and cc:authonly, the following fields may be required:
Field Name
Required
Description
x3dsActionCode
Yes
This is the action code passed as the first parameter to ck3DS.configuration.onVerifyComplete.
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.
xAuthenticateStatus
Conditional
Required if x3dsActionCode=SUCCESS. This is the authenticate status passed as the fifth parameter tock3DS.configuration.onVerifyComplete.
xSignatureVerification
Conditional
Required if x3dsActionCode=SUCCESS. This is the signature verification passed as the sixth parameter tock3DS.configuration.onVerifyComplete.
The transaction response xStatus will be Approved or Declined, and the payment is now complete. 3DS Response Fields below.

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.
Export as PDF
Copy link