Card Verification

Initiate a 3D Secure card verification process before a payment request.

Identifier. The verification is identified by public_id (format tds_...). Store it and send it as card_verification_data.id when initiating the transaction. The numeric id in the response is deprecated: it remains for existing integrations and will be removed from the response on a date announced in advance. Numeric ids already stored stay accepted on input. Treat every id as an opaque string and ignore response fields you do not recognise; new fields are added over time.

Frictionless flow: If the issuer does not require a challenge, the response returns immediately with the outcome in status (see the status table below) and a message that spells it out. Use the returned public_id in card_verification_data.id when initiating the transaction.

Challenge flow: The response includes a challenge_url. Redirect the cardholder there. After they complete the bank challenge, they are redirected to your auth_url with ?card_verification_id={public_id}&status={outcome} query parameters. card_verification_id is the tds_... public id, a string; pass it through as card_verification_data.id when initiating the transaction.

Outcomes. full_auth: the issuer authenticated the cardholder, proceed. attempt: the issuer could not fully authenticate but returned an attempt proof, proceed (the proof is forwarded with the payment). unavailable: the card is not enrolled or authentication could not be performed, no authentication data exists; you may still create the payment, it is processed without 3DS and may be soft-declined where SCA is required. failed: the issuer refused, do not proceed, run a new verification (an immediate failure is returned as HTTP 400 ERR_3DS_FAILED). challenge_pending: only while the cardholder is with the issuer. A payment that references a failed or unfinished verification is refused with HTTP 422.

Authenticate with a merchant API key or a partner API key plus merchant_id for the merchant being acted on behalf of (same rules as the transaction endpoint).