Skip to main content

Create Card Authentication

POST 
/card_auths

Start a standalone 3D Secure authentication for a card, without charging it.

Standalone 3D Secure is enabled only for selected merchants.

When the authentication is created, its status will be one of:

  • available — a challenge is required; redirect the cardholder to transaction_url.
  • failed — the card is not enrolled or enrollment failed.

Once the cardholder completes the in-browser flow, the status becomes authenticated or failed and result is populated. You can then reuse the authentication in a payment via source.card_auth_id.

Request​

Body

required

    amount Amount (integer)required

    Possible values: >= 100

    A positive integer representing the payment amount in the smallest currency unit.

    Examples:

    • 1.00 SAR = 100
    • 1.00 KWD = 1000
    • 1 JPY = 1
    currency Currency (string)required

    ISO-4217 three-letter currency code.

    callback_url urirequired

    URL the cardholder is returned to after completing the authentication.

    source

    object

    required

    type stringrequired

    Possible values: [creditcard]

    The source type to authenticate.

    name stringrequired

    Cardholder name.

    number PanNumber (string)required

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

    The card number as a string without any separators.

    month stringrequired

    Card expiry month.

    year stringrequired

    Card expiry year.

    cvc Cvc (string)required

    Possible values: >= 3 characters and <= 4 characters, Value must match regular expression ^\d{3,4}$

    The card security code. CVV for Visa, CVC for Mastercard or CSC for other brands. Must be 4 digits long for AMEX.

Responses​

Successful operation

Schema

    id uuid

    Unique identifier of the card authentication.

    status CardAuthStatus (string)

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

    • available — enrollment succeeded; redirect the cardholder to transaction_url.
    • in_progress — the cardholder is completing the challenge.
    • authenticated — completed successfully; result is populated.
    • failed — enrollment or authentication failed.
    amount Amount (integer)

    Possible values: >= 100

    A positive integer representing the payment amount in the smallest currency unit.

    Examples:

    • 1.00 SAR = 100
    • 1.00 KWD = 1000
    • 1 JPY = 1
    currency Currency (string)

    ISO-4217 three-letter currency code.

    callback_url uri
    transaction_url stringnullable

    Redirect the cardholder here to complete the challenge. null once the authentication is no longer awaiting a challenge.

    card

    object

    company Company (string)

    Possible values: [mada, visa, master, amex, unionpay]

    The scheme through which the payment is processed.

    last_digits LastFourPanNumber (string)

    Masked card number showing only last four digits.

    result

    object

    nullable

    Populated once the authentication reaches a terminal state (authenticated or failed). Returned only when the request is authenticated with the secret key; publishable-key requests always receive null.

    eci EciIndicator (string)

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

    The Electronic Commerce Indicator (ECI).

    authentication_value string

    The authentication value (CAVV / AAV), Base64 encoded.

    ds_transaction_id string

    Directory Server transaction ID.

    version string

    3DS protocol version.

    transaction_status string

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

    EMVCo transaction status.

    transaction_status_reason stringnullable

    EMVCo transaction status reason code, when provided.

    auth_scheme string

    Directory Server used to perform the authentication.

    acs_transaction_id string

    ACS transaction ID.

    ds_reference_number string

    Directory Server reference number.

    acs_reference_number string

    ACS reference number.

    three_ds_server_transaction_id string

    3DS Server transaction ID.

    is_frictionless boolean

    true if authenticated without a challenge, false otherwise.

    message stringnullable

    Human-readable message, set on failures.

    created_at date-time
Loading...