Skip to main content

List Card Authentications

GET 
/v1/3ds

List the card authentications of every merchant under your acquirer. Use merchant_id to narrow the result set to a single merchant.

Required permission: 3ds_read.

Request​

Query Parameters

    items integer

    Possible values: >= 1 and <= 100

    Number of items per page.

    merchant_id string

    Narrow the result set to a single merchant, identified by the acquirer-assigned merchant_id (not the internal UUID).

    id uuid

    Filter by card authentication UUID.

    scheme Scheme

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

    status string

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

    currency Currency

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

    fingerprint string

    Filter by the card fingerprint computed during authentication.

    month integer

    Possible values: >= 1 and <= 12

    Filter by card expiry month (1–12).

    year integer

    Filter by four-digit card expiry year.

    tds_ref string

    Filter by 3DS server reference number.

    ds_ref string

    Filter by directory server reference number.

    acs_ref string

    Filter by ACS reference number.

    ds_id uuid

    Filter by directory server transaction ID.

    acs_id uuid

    Filter by ACS transaction ID.

    amount[gte] integer

    Minimum amount (inclusive, minor units).

    amount[lte] integer

    Maximum amount (inclusive, minor units).

    created_at[gte] date-time
    created_at[lte] date-time
    sort[field] string

    Possible values: [amount, created_at, updated_at]

    Default value: created_at

    sort[dir] string

    Possible values: [asc, desc]

    Default value: desc

Responses​

Paginated list of card authentications.

Schema

    card_auths

    object[]

    required

  • Array [

    • 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.

  • ]

    • 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...
Last updated on