Skip to main content

List 3DS

GET 
/v1/3ds

List all 3DS authentications visible to the authenticated principal.

Required permission: 3ds_read.

Request​

Query Parameters

    items integer

    Possible values: >= 1 and <= 100

    id uuid
    status string

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

    scheme Scheme

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

    first_digits string

    Card BIN (first six digits).

    last_digits string
    created_at[gte] date-time
    created_at[lte] date-time

Responses​

Paginated list of card authentications.

Schema

    3ds

    object[]

    required

  • Array [

    • id uuidrequired

    A 36-character UUIDv7 identifier. When used as an idempotency key on write endpoints, the client is responsible for generating a fresh UUID for each logical operation and retaining it across retries.

    merchant

    object

    Brief representation of the merchant that owns the resource.

    id uuidrequired

    A 36-character UUIDv7 identifier. When used as an idempotency key on write endpoints, the client is responsible for generating a fresh UUID for each logical operation and retaining it across retries.

    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

    For most order-creating endpoints the minimum is 100 (one full major unit). Endpoints that support zero-value operations (such as /v1/orders/verify and /v1/orders/:id/extend) allow 0.

    currency Currency (string)required

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

    ISO 4217 three-letter currency code in uppercase.

    The currency must match the currency configured for the merchant's scheme-level terminals. Once an order is created, its currency is immutable: every subsequent capture, void, refund and extension is denominated in the same currency.

    return_url urinullable
    message stringnullable

    Last message reported by the 3DS provider.

    failure_reason stringnullable

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

    emvco_error_code stringnullable

    EMVCo protocol error code (e.g. 203, 405) when the ACS rejects the request.

    emvco_error_message stringnullable
    challenge_preference stringrequired

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

    frictionless booleanrequired

    True when the authentication completed without a challenge.

    statement_descriptor stringnullable

    challenge

    object

    Challenge details returned when the ACS requires cardholder interaction.

    url uri

    ACS URL to redirect the cardholder to.

    creq string

    Base64-encoded Challenge Request (CReq) that must be POSTed to url as the creq form field.

    auth

    object

    Authentication values that must be echoed on the subsequent authorization request (as source.auth).

    value string

    CAVV / 3DS server transaction value.

    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 and is required when submitting 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. When used as an idempotency key on write endpoints, the client is responsible for generating a fresh UUID for each logical operation and retaining it across retries.

    acs_transaction_id uuid

    A 36-character UUIDv7 identifier. When used as an idempotency key on write endpoints, the client is responsible for generating a fresh UUID for each logical operation and retaining it across retries.

    ds_reference_number string
    acs_reference_number string
    tds_purchase_date TdsPurchaseDate (string)

    Possible values: Value must match regular expression ^\d{12}$

    Purchase date in YYYYMMDDHHMM format (UTC). Generated by the 3DS server during authentication. Must be echoed back verbatim when the authorization is submitted, otherwise authentication values are rejected by the scheme.

    created_at date-timerequired

    ISO 8601 UTC timestamp with time zone designator.

    updated_at date-timerequired

    ISO 8601 UTC timestamp with time zone designator.

  • ]

    • meta

    object

    required

    Cursor-style pagination metadata. next_page and prev_page are null at the boundaries. Total counts are intentionally omitted for performance on large result sets (countless pagination).

    current_page integerrequired

    Possible values: >= 1

    next_page integernullablerequired
    prev_page integernullablerequired
Loading...