Skip to main content

Retrieve Card Authentication

GET 
/v1/3ds/:id

Retrieve a single card authentication by its UUID.

Card authentications that belong to another acquirer return HTTP 404.

Required permission: 3ds_read.

Request​

Path Parameters

    id uuidrequired

    Card authentication UUID.

Responses​

The card authentication.

Schema

    id uuidrequired

    A 36-character UUIDv7 identifier.

    merchant

    object

    required

    Brief representation of the merchant that owns the resource.

    id uuidrequired

    A 36-character UUIDv7 identifier.

    name stringrequired

    Merchant display name (English).

    merchant_id stringrequired

    Stable, human-readable merchant identifier assigned by the acquirer. Often used as the merchant's principal reference in scheme reports.

    arabic_name string

    Merchant display name in Arabic, when configured.

    status stringrequired

    Possible values: [draft, available, in_progress, authenticated, failed]

    scheme Scheme (string)required

    Possible values: [visa, mastercard, mada, amex]

    The card scheme (network) associated with the card. mada is detected from the issuing BIN and takes precedence over Visa / Mastercard co-branding for Saudi-issued cards.

    amount Amount (integer)required

    Possible values: <= 100000000

    A non-negative integer representing a monetary value in the smallest currency unit for the associated currency (minor units).

    Examples:

    • 1.00 SAR is sent as 100
    • 1.00 KWD is sent as 1000
    • 1 JPY is sent as 1
    currency Currency (string)required

    Possible values: Value must match regular expression ^[A-Z]{3}$

    ISO 4217 three-letter currency code in uppercase.

    return_url url

    Merchant URL the cardholder is returned to after a challenge.

    message stringnullable

    Human-readable authentication outcome message.

    failure_reason stringnullable

    Possible values: [system_error, rejected, denied, unavailable, upstream_error, null]

    Populated when status = failed.

    emvco_error_code stringnullable

    EMVCo error code when the directory server rejected the request.

    emvco_error_message stringnullable
    challenge_preference string

    Possible values: [no_preference, no_challenge, preferred, mandated]

    frictionless boolean

    true when authentication completed without a cardholder challenge.

    statement_descriptor stringnullable

    challenge

    object

    nullable

    Present while a challenge is pending with the cardholder.

    url url

    ACS challenge URL the cardholder must be redirected to.

    creq string

    Base64-encoded challenge request payload.

    auth

    object

    nullable

    Authentication values, present once the authentication has succeeded. Merchants echo these values on the subsequent authorization.

    value string

    CAVV / 3DS authentication value issued by the ACS.

    status AuthStatus (string)

    Possible values: [Y, N, U, A, R]

    Transaction status from the 3DS authentication response:

    • Y: Authenticated successfully.
    • N: Not authenticated / denied.
    • U: Authentication could not be performed.
    • A: Attempt performed. Not authenticated but a CAVV was provided.
    • R: Rejected by issuer.
    eci EciIndicator (string)

    Possible values: [00, 01, 02, 05, 06, 07]

    Electronic Commerce Indicator returned by the directory server / issuer ACS. Identifies the authentication strength of a 3DS-authenticated transaction.

    version ThreeDsVersion (string)

    Possible values: [2.0.0, 2.1.0, 2.2.0, 2.3.0]

    EMV 3-D Secure protocol version the authentication was performed under.

    ds_transaction_id uuid

    A 36-character UUIDv7 identifier.

    acs_transaction_id uuid

    A 36-character UUIDv7 identifier.

    ds_reference_number string
    acs_reference_number string
    tds_purchase_date string

    Purchase date generated by the 3DS server (UTC).

    created_at date-timerequired

    ISO 8601 UTC timestamp with time zone designator.

    updated_at date-timerequired

    ISO 8601 UTC timestamp with time zone designator.

Loading...
Last updated on