Server-Side Integration

Transaction Components

1. Submit a payment transaction 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:

   1. Endpoint https://x1.cardknox.com/gateway - accepts the parameters as querystring values or application/x-www-form-urlencoded

   2. Endpoint https://x1.cardknox.com/gatewayJSON - 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

  • The transaction is complete and no further action is necessary. Jump to 3DS response fields.

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 a verification request to https://x1.cardknox.com/verify to complete the 3DS authentication and process the payment with the bank. In addition to the 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.
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.

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.