Open a 3DS authentication

POST

/payments/card/authentications

• Production

Refused with 403 invalid_account if the merchant is not enrolled in 3DS for this mode — a Paygasus check, made before any processor call.

Authorizations

• secret_key

Request Body^required

Open an authentication for an amount the issuer will be asked to approve.

object

amount

required

A monetary amount in the currency’s minor units (e.g. cents for USD).

integer format: int64

Example

1000

billing_address

One of:

null

null

object

The cardholder’s billing address. Same guidance, same never-stored posture. Supply it here: the processor binds cardholder details to the authentication at this step.

object

city

string | null

country

ISO 3166-1 alpha-2, e.g. US.

string | null

first_name

string | null

house_number_or_name

string | null

last_name

string | null

postal_code

string | null

state_or_province

string | null

street

string | null

currency

required

Currently supported currencies by Paygasus Pay

string

Allowed values: USD

Example

USD

customer

One of:

null

null

object

How to reach the cardholder. Optional, but the processor’s guidance is that email and/or phone materially improve the issuer’s decision, and cert showed the processor binds them at this step. Forwarded on the processor call and never stored.

object

email

string | null

phone

The cardholder’s mobile number, as they would write it.

string | null

key_id

required

string

layout

required

Array<object>

object

field

required

string

len

required

integer format: int32

payload

required

Encrypted card details. Conduit never decrypts them.

string

Example

eyJhbGciOiJSU0Et...ENCRYPTED...

Responses

201

Authentication opened. Run the fingerprint iframe if fingerprint is present, then POST /fingerprint.

An authentication, as the merchant sees it.

Built by hand rather than derived on [CardAuthentication], for the same reason CheckoutSessionResponse is: the domain type holds things that must not be echoed. consumed_by, the processor’s own handle, and the merchant id are all deliberately absent — the merchant references the ca_ id, and nothing here needs the upstream one.

object

amount

required

A monetary amount in the currency’s minor units (e.g. cents for USD).

integer format: int64

Example

1000

challenge

One of:

null

null

object

Present only in challenge_pending. Cleared the moment the authentication reaches a verdict.

object

step_up_url

required

string

token

required

string

created

required

integer format: int64

currency

required

Currently supported currencies by Paygasus Pay

string

Allowed values: USD

Example

USD

expires_at

required

When this authentication stops being usable, in every state — including authenticated: a verdict that has not been charged by this time expires and cannot be referenced. Once a charge has used it the field is informational.

integer format: int64

failure_reason

Why it failed, when it did.

string | null

fingerprint

One of:

null

null

object

Present only in created — while the browser still has the device step to run. Once the fingerprint has been reported the token is spent and is not echoed again.

object

collection_url

required

string

token

required

string

id

required

Our identifier for an authentication.

string

Example

ca_9Z3K01ARZ3NDEKTSV4RRFFQ69G5FAV

livemode

required

boolean

object

required

string

status

required

The lifecycle of one 3DS run.

A plain enum with the state-specific data on [CardAuthentication] rather than in the variants, matching [crate::checkout_session::CheckoutSessionStatus] and unlike [crate::payment_intent::CardPaymentIntentStatus]. The reason is the repository: status is one column and the outcome fields are their own columns, so [std::str::FromStr] has to round-trip from the string alone.

string

Allowed values: created fingerprint_collected challenge_pending authenticated failed expired abandoned

400

Invalid request

object

error

required

object

code

required

string

message

required

string

param

string | null

retryable

When present and true, the caller may retry the same request.

boolean | null

type

required

string

403

Merchant is not enrolled in 3DS for this mode

object

error

required

object

code

required

string

message

required

string

param

string | null

retryable

When present and true, the caller may retry the same request.

boolean | null

type

required

string

502

Processor unreachable; safe to retry

object

error

required

object

code

required

string

message

required

string

param

string | null

retryable

When present and true, the caller may retry the same request.

boolean | null

type

required

string