Authenticate

POST /v1/3ds/:id/authenticate

Submit the cardholder's device information and authentication preferences to the ACS. The provider may either complete the authentication frictionlessly (no cardholder interaction) or return a challenge URL to which the browser must be redirected.

Business rules:

The CardAuth must be in status available.
number / month / year must match the fingerprint recorded on the CardAuth at creation. Any mismatch is a security failure and is rejected with HTTP 400.
When customer_device.javascript_enabled = true, the color_depth, screen_height, screen_width and timezone fields are mandatory.

Required permission: 3ds_create. Concurrency: authenticate acquires a 15-second Redis lock on the CardAuth. Parallel authenticate requests return HTTP 400.

Request

Path Parameters

id uuidrequired

CardAuth UUID.

application/json

Body

required

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

channel stringrequired

Possible values: [browser, decoupled]

Default value: browser

browser: cardholder present in a browser. Challenge will be delivered via a redirect to challenge.url.
decoupled: cardholder authenticates out of band (e.g. via a banking app push). No challenge URL is returned.

return_url urirequired

Absolute URL the ACS redirects the browser to after the challenge.

statement_descriptor string

Possible values: non-empty and <= 40 characters

challenge_preference stringrequired

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

Default value: no_preference

no_preference: let the ACS decide.
no_challenge: request frictionless; the issuer may still force a challenge.
preferred: request a challenge.
mandated: require a challenge (regulatory flows).

customer

object

name string

Possible values: >= 2 characters and <= 45 characters

email email

Possible values: <= 254 characters

mobile string

Possible values: non-empty and <= 18 characters

Phone number. E.164 format is recommended.

billing_address

object

Billing or shipping address. All fields are optional.

line_1 string

Possible values: non-empty and <= 50 characters

line_2 string

Possible values: non-empty and <= 50 characters

line_3 string

Possible values: non-empty and <= 50 characters

city string

Possible values: non-empty and <= 50 characters

state string

Possible values: non-empty and <= 50 characters

postal_code string

Possible values: non-empty and <= 16 characters

country Country (string)

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

ISO 3166-1 alpha-2 country code in uppercase.

shipping_address

object

Billing or shipping address. All fields are optional.

line_1 string

Possible values: non-empty and <= 50 characters

line_2 string

Possible values: non-empty and <= 50 characters

line_3 string

Possible values: non-empty and <= 50 characters

city string

Possible values: non-empty and <= 50 characters

state string

Possible values: non-empty and <= 50 characters

postal_code string

Possible values: non-empty and <= 16 characters

country Country (string)

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

ISO 3166-1 alpha-2 country code in uppercase.

customer_device

object

Cardholder's browser / device metadata. Collected via the 3DS Method (browser fingerprint script) and forwarded to the ACS for risk scoring. When javascript_enabled = true, the screen and timezone fields are mandatory.

ip_address string

Public IPv4 or IPv6 address of the customer.

user_agent string

Possible values: non-empty and <= 2048 characters

accept_header string

Possible values: non-empty and <= 2048 characters

javascript_enabled boolean

language string

Possible values: non-empty and <= 8 characters

BCP 47 language tag (e.g. en-US).

color_depth string

Possible values: [1, 4, 8, 15, 16, 24, 32, 48]

screen_height integer

Possible values: >= 1 and <= 999999

screen_width integer

Possible values: >= 1 and <= 999999

timezone string

Possible values: Value must match regular expression ^[+-]\d{1,4}$

Browser timezone offset in minutes from UTC as returned by Date#getTimezoneOffset(), prefixed with sign. Example: '-180' for UTC+3.

Responses

Authentication processed. If frictionless, status is authenticated and auth is populated. Otherwise status is in_progress and challenge.url contains the ACS URL.

application/json

Schema
Example (from schema)

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.

{
  "id": "0191f5a7-3d99-7f81-b7ec-962a5f5fdd7c",
  "merchant": {
    "id": "0191f5a7-3d99-7f81-b7ec-962a5f5fdd7c",
    "name": "Example Store",
    "merchant_id": "MERCHANT001",
    "arabic_name": "متجر الأمثلة"
  },
  "status": "draft",
  "scheme": "visa",
  "amount": 10000,
  "currency": "SAR",
  "return_url": "string",
  "message": "string",
  "failure_reason": "system_error",
  "emvco_error_code": "string",
  "emvco_error_message": "string",
  "challenge_preference": "no_preference",
  "frictionless": true,
  "statement_descriptor": "string",
  "challenge": {
    "url": "string",
    "creq": "string"
  },
  "auth": {
    "value": "string",
    "status": "Y",
    "eci": "05",
    "version": "2.0.0",
    "ds_transaction_id": "0191f5a7-3d99-7f81-b7ec-962a5f5fdd7c",
    "acs_transaction_id": "0191f5a7-3d99-7f81-b7ec-962a5f5fdd7c",
    "ds_reference_number": "string",
    "acs_reference_number": "string",
    "tds_purchase_date": "202501151430"
  },
  "created_at": "2025-01-15T14:30:00Z",
  "updated_at": "2025-01-15T14:30:00Z"
}

CardAuth is not available, card details do not match the fingerprint, or a concurrent authenticate is in progress.

application/json

Schema
Example (from schema)

Schema

message stringrequired

{
  "message": "This order cannot be captured."
}

Authentication failed.

application/json

Schema
Example (from schema)

Schema

message stringrequired

{
  "message": "Missing authentication information"
}

The authenticated principal lacks the required permission.

application/json

Schema
Example (from schema)

Schema

message stringrequired

{
  "message": "Unauthorized"
}

The referenced resource does not exist.

application/json

Schema
Example (from schema)

Schema

message stringrequired

{
  "message": "The Order you are looking for was not found."
}

Validation error.

application/json

Schema
Example (from schema)

Schema

message stringrequired

errors

object

required

property name*

string[]

Array [

string

]

{
  "message": "The given data was invalid.",
  "errors": {
    "amount": [
      "The amount field must be at least 100."
    ],
    "source.number": [
      "The number must be a valid credit card."
    ]
  }
}

Authenticate

/v1/3ds/:id/authenticate

Request​

Path Parameters

Body

Responses​

Request

Responses