Bring Your Own 3DS

Technical Author Note

Confirm the field names and accepted values on this page against the schema before publication.

Authenticate the cardholder with a 3DS provider of your choice, then pass the result to PAYSTRAX with the payment — PAYSTRAX doesn't run the challenge itself, only forwards what your provider returns.

Use this flow for any card payment that needs Strong Customer Authentication or liability shift, on top of whichever flow you're already using. 3DS attempts are mandatory for Accept a payment, Authorise a payment, and Fund a card — Issue a payout does not use 3DS.

How it works

1. Authenticate the cardholder using your own 3DS provider. PAYSTRAX doesn't perform the authentication itself — your provider does, and how it does it is handled entirely on their side.
2. Take the authentication result your provider returns and map its values into the 3ds_v2 fields (see Field reference below).
3. Include custom_data.authentication.3ds_v2 in the payment request when the transaction was authenticated with 3DS. Omit the object entirely for non-3DS transactions.

Field reference

Field	Type	Required	Description
3ds_v2	object	conditional	Container. Include when the transaction was 3DS2-authenticated.
3ds_v2.ds_transaction_id	string	required when object present	UUID v4 from the card scheme's Directory Server.
3ds_v2.cavv	string	conditional	Base64-encoded 20-byte value from the ACS (CAVV/AAV/AEVV). Required when ds_transaction_status is Y or A.
3ds_v2.eci	string	conditional	Electronic Commerce Indicator (scheme-specific, see below).
3ds_v2.version	string	conditional	Negotiated 3DS version, e.g. 2.1.0 or 2.2.0.
3ds_v2.authentication_response	string	conditional	ACS transaction status. Pass null if not returned.
3ds_v2.ds_transaction_status	string	conditional	Directory Server status. Use this when both are available.

ECI values by scheme

ECI	Visa / Amex	Mastercard
05 / 02	Fully authenticated	Fully authenticated
06 / 01	Attempted	Attempted

Status values

Applies to both authentication_response and ds_transaction_status.

Value	Meaning
Y	Authentication / account verification successful.
N	Not authenticated — denied.
U	Unable to authenticate (technical).
A	Attempted — proof of attempt generated.
C	Challenge required (CReq/CRes).
D	Decoupled authentication confirmed.
R	Rejected by issuer — do not authorise.

Example

custom_data.authentication — 3DS2

{
  "custom_data": {
    "authentication": {
      "cvc": "123",
      "3ds_v2": {
        "cavv": "AAABCIEiZwAAAAAAAAAAAAAAAAA=",
        "eci": "05",
        "ds_transaction_id": "a7f1e2b3-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
        "version": "2.2.0",
        "authentication_response": "Y",
        "ds_transaction_status": "Y"
      }
    }
  }
}

note

SCA exemptions (custom_data.authentication.sca_exemption, e.g. low_value) must be applied in co-operation with PAYSTRAX.

This object sits inside custom_data alongside any flow-specific fields — for example, account_funding: true on Fund a card, where 3DS is currently required.