Server-Side Integration

Transaction Components

  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

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

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.

x3dsSubmitted

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