--- title: "Create a 3D Secure Session" method: POST path: "/3d_secure_sessions" tags: ["3D Secure Sessions"] --- # Create a 3D Secure Session `POST /3d_secure_sessions` ## Request - Base URL: `https://finix.sandbox-payments-api.com` - URL: `https://finix.sandbox-payments-api.com/3d_secure_sessions` - Auth: HTTP basic - TypeScript: (a function with typed inputs; its response is checked against the schema) Create a `3D Secure Session` to authenticate a buyer before you charge their card. Create the session from a `payment_instrument_id` for the redirect flow or standalone `Finix.ThreeDSecure`, or from a `token_id` for the `ThreeDSecure` payment form option. For redirect flows, pass the session ID after `state` reaches `SUCCEEDED`. With Finix.js, pass it when the `succeeded` callback fires, even if the session resource still reads `PENDING`. ## Headers - `Finix-Version` string - `Content-Type` string ## Request body - union - Create3DSecureSession - `amount` integer, required: The amount to authenticate, in the smallest unit of the currency (for example, `1000` = $10.00). This amount must match the `amount` of the [Transfer](/api/transfers) or [Authorization](/api/authorizations) you later create with the session. If the two amounts differ, the liability shift is downgraded. - `currency` 'CAD' | 'USD', required: ISO 4217 3-letter currency code. - `merchant_id` string, required: The ID of the [Merchant](/api/merchants) the payment processes under. Finix validates this ID against the `merchant` of the [Transfer](/api/transfers) or [Authorization](/api/authorizations) you create later with the session. - `payment_instrument_id` string, required: The ID of the [Payment Instrument](/api/payment-instruments) to authenticate. Pass either `payment_instrument_id` or `token_id`, not both. - `redirect_url` string: The URL the [buyer](/api/identities) returns to after they finish authentication. The URL must use HTTPS. Finix passes this URL to the 3D Secure vendor as the `redirect` parameter of `3d_secure_authentication_url`. When the buyer finishes, the vendor returns them to the URL with `?status={status}&session={session_id}` appended. The `status` values are `success`, `failure`, and `error`. Only the redirect flow uses this field. Omit it when you collect the authentication with Finix.js. - `tags` Tags, nullable: Include up to 50 `key: value` pairs to annotate requests with custom metadata. - Maximum character length for individual `keys` is 40. - Maximum character length for individual `values` is 500. (For example, `order_number: 25`, `item_type: produce`, `department: sales`) - Create3DSecureSessionToken - `amount` integer, required: The amount to authenticate, in the smallest unit of the currency (for example, `1000` = $10.00). This amount must match the `amount` of the `Transfer` or `Authorization` you later create with the session. If the two amounts differ, the liability shift is downgraded. - `currency` 'CAD' | 'USD', required: ISO 4217 3-letter currency code. - `merchant_id` string, required: The ID of the `Merchant` the payment processes under. Finix validates this ID against the `merchant` of the `Transfer` or `Authorization` you later create with the session. - `tags` Tags, nullable: Include up to 50 `key: value` pairs to annotate requests with custom metadata. - Maximum character length for individual `keys` is 40. - Maximum character length for individual `values` is 500. (For example, `order_number: 25`, `item_type: produce`, `department: sales`) - `token_id` string, required: The ID of the token to authenticate. Pass either `token_id` or `payment_instrument_id`, not both. ## Response `201` A single `3D Secure Session` object. - 3dSecureSession - `id` string: The ID of the `3D Secure Session`. - `created_at` string, date-time: Timestamp of when the object was created. - `updated_at` string, date-time: Timestamp of when the object was last updated. - `3d_secure_authentication` object, nullable: The authentication values the card network returns. Pass this object, or the ID of this `3D Secure Session`, when you create the [Transfer](/api/transfers) or [Authorization](/api/authorizations). This field is `null` until the authentication process finishes. It stays `null` when `state` is `FAILED`. - `cardholder_authentication` string: Provides evidence that the cardholder authentication occurred or that the [Merchant](/api/merchants) attempted authentication. This is unique for each authentication transaction and is sometimes referred to as the cardholder authentication verification value (CAVV). - `electronic_commerce_indicator` 'AUTHENTICATED' | 'ATTEMPTED' | 'NON_AUTHENTICATED': The result of the authentication, and the value that determines who carries chargeback liability for fraud. - `AUTHENTICATED`: The issuer authenticated the [buyer](/api/identities). Liability for fraud chargebacks shifts to the issuer. - `ATTEMPTED`: The issuer could not authenticate the buyer, so the card network authenticated on the issuer's behalf. Liability for fraud chargebacks shifts to the issuer. - `NON_AUTHENTICATED`: The buyer was not authenticated. Liability for fraud chargebacks stays with the seller. - `transaction_id` string: The ID the issuer assigns to the 3D Secure transaction. - `3d_secure_authentication_session_id` string, nullable: The ID of the authentication session with the 3D Secure vendor. This is not the ID of the `3D Secure Session` resource. - `3d_secure_authentication_url` string, nullable: The hosted URL where the [buyer](/api/identities) completes authentication. Redirect the buyer to this URL to run the redirect flow. This field is `null` when you create the session from a `token_id` and complete the authentication with Finix.js. - `3d_secure_version` string, nullable: The version of the 3D Secure protocol used for the authentication. - `amount` integer: The amount that was authenticated, in the smallest unit of the currency (for example, `1000` = $10.00). - `authentication_type` 'null' | 'FRICTIONLESS' | 'CHALLENGE' | 'ATTEMPT', nullable: How the buyer was authenticated. This field is populated when `state` is `SUCCEEDED`. - `FRICTIONLESS`: The issuer authenticated the buyer from the data in the request, without presenting a challenge. - `CHALLENGE`: The issuer presented the buyer with a challenge, such as a one-time passcode. - `ATTEMPT`: The card network authenticated on the issuer's behalf. - `currency` 'CAD' | 'USD': ISO 4217 3-letter currency code. - `failure_code` 'null' | 'AUTHENTICATION_FAILED' | 'AUTHENTICATION_TIMED_OUT' | 'CARD_NOT_ENROLLED' | 'CHALLENGE_REQUIRED' | 'DIRECTORY_SERVER_UNAVAILABLE' | 'ISSUER_SERVER_UNAVAILABLE' | 'PROTOCOL_ERROR' | 'SUSPECTED_FRAUD' | 'TRANSACTION_CANCELLED_BY_CARDHOLDER' | 'TRANSACTION_NOT_PERMITTED' | 'TRANSIENT_SYSTEM_FAILURE' | 'UNSUPPORTED_3D_SECURE_VERSION', nullable: The code for why the authentication process could not finish. This field is populated when `state` is `FAILED`. - `failure_message` string, nullable: A human-readable description of why the authentication process could not finish. - `merchant_id` string: The ID of the [Merchant](/api/merchants) the payment processes under. - `payment_instrument_id` string, nullable: The ID of the [Payment Instrument](/api/payment-instruments) that was authenticated. This field is `null` when you create the session from a `token_id`. - `redirect_url` string, nullable: The URL the buyer returns to after they finish authentication. This field is `null` when you create the session from a `token_id`. - `state` 'PENDING' | 'SUCCEEDED' | 'FAILED': The state of the authentication process. A `state` of `SUCCEEDED` means the process finished. It does not mean the buyer was authenticated: a session where the issuer declined to authenticate the buyer also ends in `SUCCEEDED`. Read `3d_secure_authentication.electronic_commerce_indicator` for the authentication result. - `PENDING`: The authentication process has not finished. - `SUCCEEDED`: The authentication process finished and returned a result. - `FAILED`: The authentication process could not finish. See `failure_code` and `failure_message`. - `tags` Tags, nullable: Include up to 50 `key: value` pairs to annotate requests with custom metadata. - Maximum character length for individual `keys` is 40. - Maximum character length for individual `values` is 500. (For example, `order_number: 25`, `item_type: produce`, `department: sales`) ## Other responses - `400`: Bad Request. The server cannot process the request due to malformed syntax or invalid data. - `401`: Unauthorized. Authentication is required and has failed or has not been provided. - `403`: Forbidden. The client is authenticated but does not have permission to access the resource. - `404`: Not Found. The requested resource could not be found on the server. - `406`: Not Acceptable. The server could not accept the submitted request. Confirm how the request was formatted and submitted. ## Changes - **2026-10-14** `8c3b82d51eff`: 1 info - endpoint added [Operation history](https://skmtc.dev/finix/apis/finix-api-reference/changes/3d_secure_sessions/post.md) --- [API](https://skmtc.dev/finix/apis/finix-api-reference.md) - [All operations](https://skmtc.dev/finix/apis/finix-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/finix/apis/finix-api-reference/revisions/c62db965e7dc?raw)