Skip to main content

Create

POST 
/v1/3ds

Initialize a 3DS authentication against the directory server for the scheme identified from the card BIN. The card's fingerprint is computed and stored; the same PAN, expiry month and expiry year must be supplied to authenticate to prove continuity.

On success the returned CardAuth is in status available, ready for authenticate.

Required permission: 3ds_create.

Request​

Body

required

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

    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.

    number CardPan (string)required

    Possible values: Value must match regular expression ^\d{13,19}$

    Primary Account Number (PAN) as a continuous digit string, no separators. Sent in request bodies only — PAN is never returned in full in responses; only first_digits and last_digits are echoed.

    month integerrequired

    Possible values: >= 1 and <= 12

    year integerrequired

    Possible values: >= 2000

    Four-digit expiry year.

Responses​

Authentication initialized.

Schema

    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.

Loading...