Skip to main content
GET
Get a 3D Secure session of a merchant

Authorizations

x-api-key
string
header
required

Company API key for authentication

Path Parameters

merchantId
string<uuid>
required

Merchant/Company ID

Example:

"123e4567-e89b-12d3-a456-426614174000"

sessionId
string<uuid>
required

3DS session ID (id from the create response)

Example:

"550e8400-e29b-41d4-a716-446655440000"

Response

The 3DS session

id
string<uuid>
required

Internal 3DS session ID (use as three_d_secure_session_id when creating a transaction)

Example:

"550e8400-e29b-41d4-a716-446655440000"

tds_session_id
string
required

Provider session ID (use with the client-side SDK for challenge flows)

Example:

"tds_visa_e7c2yfa3867c"

card_id
string<uuid> | null
required

The stored card this session authenticated, or null when the card was sent inline. When both this and the transaction's card_data.card_id are set, they must match or the transaction is rejected.

Example:

"123e4567-e89b-12d3-a456-426614174000"

auth_status
enum<string>
required

Current authentication status:

  • ACTION_REQUIRED: Cardholder must complete 3DS challenge
  • AUTHENTICATED: Authentication successful (frictionless or completed challenge), or only attempted: with authentication_flow: attempt the cardholder was not authenticated and only proof of the attempt exists
  • FAILED: Authentication failed
Available options:
ACTION_REQUIRED,
AUTHENTICATED,
FAILED
Example:

"AUTHENTICATED"

consumption_status
enum<string>
required

Whether this session has been used for a transaction:

  • NOT_CONSUMED: Available for use
  • PROCESSING: Currently being used (atomic claim)
  • CONSUMED: Already used for a transaction
Available options:
NOT_CONSUMED,
PROCESSING,
CONSUMED
Example:

"NOT_CONSUMED"

amount
integer
required

Amount in minor units (cents)

Example:

10000

currency
string
required

ISO 4217 currency code

Example:

"BRL"

failure_reason
string | null
required

Reason for authentication failure (only present when auth_status is FAILED)

Example:

null

liability_shift
boolean | null
required

Whether liability has shifted to the issuer

Example:

true

authentication_flow
string | null
required

3DS authentication flow type (frictionless, challenge, attempt). attempt comes with auth_status: AUTHENTICATED, but the cardholder was not authenticated: only proof of the authentication attempt exists.

Example:

"frictionless"

acs_transaction_id
string | null
required

Transaction ID the issuer's Access Control Server (ACS) assigned to the authentication. Recorded with the outcome: null while auth_status is ACTION_REQUIRED, and when it was not reported.

Example:

"b0bb6068-8d68-40a1-9606-20fa01ba74de"

ds_transaction_id
string | null
required

Transaction ID the card network's Directory Server (DS) assigned to the authentication, which the network uses to find it, for example in a chargeback dispute. Recorded with the outcome: null while auth_status is ACTION_REQUIRED, and when it was not reported.

Example:

"cfb8d11b-8129-414e-983a-3e95f0f4f6c6"

server_transaction_id
string | null
required

Transaction ID the 3DS Server assigned to the authentication. Recorded with the outcome: null while auth_status is ACTION_REQUIRED, and when it was not reported.

Example:

"dc46fbb1-a898-4760-b8a2-56dae36cb0e2"

protocol_version
string | null
required

EMV 3-D Secure protocol version of the authentication. Recorded with the outcome: null while auth_status is ACTION_REQUIRED, and when it was not reported.

Example:

"2.2.0"

expires_at
string<date-time>
required

Session expiration time

Example:

"2026-02-06T20:35:00.000Z"

created_at
string<date-time>
required
Example:

"2026-02-06T19:35:00.000Z"

updated_at
string<date-time>
required
Example:

"2026-02-06T19:35:00.000Z"