> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.

# Create 3DS2 Setup

> Register 3D Secure 2 browser and device data for server-to-server integrations and receive a three_d_secure_setup_id to use on the subsequent payment.

Register the 3D Secure 2 setup data your integration has collected — the cardholder's browser environment and any pre-computed device fingerprints — and receive a `three_d_secure_setup_id` to reference on the subsequent `POST /v1/payments`.

<Note>
  **Server-to-server integrations only**

  Use this endpoint when you operate a server-to-server (B2B) integration and collect 3DS2 device data on your side — through your own SDK, a fraud-screening provider's collector, or a 3DS2 server you call directly.

  If you integrate through the Yuno Web/Mobile SDK and a checkout session, you can skip this endpoint entirely — the SDK collects the device data and registers it automatically as part of the checkout flow.
</Note>

<Note>
  **Registration step only**

  This endpoint does not call the issuer, does not render a challenge, and does not bind to a specific card. The card and the `three_d_secure_setup_id` travel together on the payment call.
</Note>

<Warning>
  **Device-data quality matters**

  The payment provider uses `browser_info` and `device_fingerprints` to score risk and decide between frictionless flow and challenge when the payment is submitted. Missing or stale fields raise the challenge rate. Send the values exactly as observed in the cardholder's browser at the moment you call this endpoint.
</Warning>

<Note>
  **How the merchant supplies device data**

  The `type` field tells Yuno where the device data was gathered. `MERCHANT_PROVIDED` — currently the only supported value — means you collected the browser environment and device fingerprints on your side and are passing them in directly. Yuno does not run its own collector for this endpoint; if you need Yuno to capture the browser/device data, use the [SDK variant](/docs/payment-features/3ds-standalone) instead.
</Note>

## How to use the response

1. **Store the id.** Keep `three_d_secure_setup_id` against the order on your side.
2. **Reference it on the payment.** On the subsequent [Create Payment](/reference/payments/create-payment), pass it under `payment_method.detail.card.three_d_secure.three_d_secure_setup_id` alongside the card or vaulted token. Yuno attaches the registered `browser_info` and `device_fingerprints` to the request it sends to the payment provider.

Note that this request requires an `X-Idempotency-Key`. The same key with the same payload returns the original setup id within a 24-hour replay window. Check the [Authentication](/reference/authentication#idempotency) page for more information.

## Field rules and edge cases

| Rule                                                           | Behavior                                                                                          |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `type` set to a value other than `MERCHANT_PROVIDED`           | `400 INVALID_PARAMETERS`. Other values are reserved for future use.                               |
| `browser_info.platform` set to an unsupported value            | `400 INVALID_PARAMETERS`. Allowed: `WEB`, `IOS`, `ANDROID`.                                       |
| `device_fingerprints` omitted                                  | Accepted. Yuno will skip device-fingerprint enrichment for any provider that wasn't pre-supplied. |
| `device_fingerprints[*].provider_id` not found in your account | Entry is dropped silently; setup proceeds with the remaining entries.                             |
| `account_id` not owned by the API key                          | Treated as an authorization failure (`403`).                                                      |


## OpenAPI

````yaml openapi/three-d-secure-setups/create-three-d-secure-setup.json POST /three-d-secure/setups
openapi: 3.1.0
info:
  title: three-d-secure-setups-api
  version: 1.0.0
servers:
  - url: https://api-sandbox.y.uno/v1
security:
  - sec0: []
    sec1: []
    sec2: []
paths:
  /three-d-secure/setups:
    post:
      summary: Create 3DS2 Setup
      description: >-
        Register the 3D Secure 2 setup data your integration has collected — the
        cardholder's browser environment and any pre-computed device
        fingerprints — and receive a `three_d_secure_setup_id` to reference on
        the subsequent `POST /v1/payments`.
      operationId: create-three-d-secure-setup
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - account_id
                - type
                - browser_info
              properties:
                account_id:
                  type: string
                  format: uuid
                  description: Account UUID that owns this 3DS2 setup.
                type:
                  type: string
                  description: >-
                    Source of the device data. `MERCHANT_PROVIDED` means you
                    collected the browser/device data on your side and are
                    passing it in directly.
                  enum:
                    - MERCHANT_PROVIDED
                browser_info:
                  type: object
                  description: >-
                    Browser environment captured from the cardholder's session.
                    Forwarded verbatim to the 3DS2 server for risk scoring and
                    frictionless decisioning.
                  required:
                    - user_agent
                    - accept_header
                    - color_depth
                    - screen_height
                    - screen_width
                    - language
                  properties:
                    user_agent:
                      type: string
                      description: '`navigator.userAgent` of the cardholder''s browser.'
                    accept_header:
                      type: string
                      description: Value of the `Accept` HTTP header sent by the browser.
                    color_depth:
                      type: string
                      description: '`screen.colorDepth`, e.g. `"24"`.'
                    screen_height:
                      type: string
                      description: '`screen.height` in pixels.'
                    screen_width:
                      type: string
                      description: '`screen.width` in pixels.'
                    language:
                      type: string
                      description: >-
                        BCP-47 language tag from `navigator.language`, e.g.
                        `"es-CO"`.
                    javascript_enabled:
                      type: boolean
                      description: >-
                        Whether JavaScript is enabled. Defaults to `true` when
                        omitted.
                    java_enabled:
                      type: boolean
                      description: >-
                        Whether the Java plugin is enabled. Almost always
                        `false` on modern browsers.
                    browser_time_difference:
                      type: string
                      description: >-
                        UTC offset of the browser in minutes, signed (e.g.
                        `"-300"` for UTC-5). Equivalent to `new
                        Date().getTimezoneOffset()`.
                    platform:
                      type: string
                      description: Channel that captured the data.
                      enum:
                        - WEB
                        - IOS
                        - ANDROID
                    accept_content:
                      type: string
                      description: Optional `Accept-Encoding` value if you capture it.
                    accept_browser:
                      type: string
                      description: Optional `Accept-Language` value if you capture it.
                device_fingerprints:
                  type: array
                  description: >-
                    One or more provider-scoped device fingerprints already
                    collected on your side. Yuno will not run device collection
                    again for any `provider_id` you include here.
                  items:
                    type: object
                    required:
                      - provider_id
                      - id
                    properties:
                      provider_id:
                        type: string
                        format: uuid
                        description: >-
                          UUID of the fraud or device-intelligence connection in
                          your Yuno account that produced this fingerprint. Find
                          it in **Dashboard → Connections** or via `GET
                          /v1/connections`.
                      id:
                        type: string
                        description: >-
                          The fingerprint value as returned by that provider's
                          collector.
            examples:
              With device fingerprints:
                value:
                  account_id: 11111111-1111-1111-1111-111111111111
                  type: MERCHANT_PROVIDED
                  browser_info:
                    user_agent: >-
                      Mozilla/5.0 (Windows NT 10.0; Win64; x64)
                      AppleWebKit/537.36
                    accept_header: text/html,application/xhtml+xml,application/xml;q=0.9
                    color_depth: '24'
                    screen_height: '1080'
                    screen_width: '1920'
                    language: es-CO
                    javascript_enabled: true
                    java_enabled: false
                    browser_time_difference: '-300'
                    platform: WEB
                  device_fingerprints:
                    - provider_id: f3a8b5d2-9c4e-4a7b-b1f8-2d6c9e0a4f12
                      id: fp_abc123xyz
              Without device fingerprints:
                value:
                  account_id: 11111111-1111-1111-1111-111111111111
                  type: MERCHANT_PROVIDED
                  browser_info:
                    user_agent: >-
                      Mozilla/5.0 (Windows NT 10.0; Win64; x64)
                      AppleWebKit/537.36
                    accept_header: text/html,application/xhtml+xml,application/xml;q=0.9
                    color_depth: '24'
                    screen_height: '1080'
                    screen_width: '1920'
                    language: es-CO
                    javascript_enabled: true
                    java_enabled: false
                    browser_time_difference: '-300'
                    platform: WEB
      responses:
        '201':
          description: '201'
          content:
            application/json:
              examples:
                With device fingerprints:
                  value:
                    three_d_secure_setup_id: a17b4f2c-08d1-4e9b-b6c5-9a3e0c7f1b22
                    account_id: 11111111-1111-1111-1111-111111111111
                    type: MERCHANT_PROVIDED
                    browser_info:
                      user_agent: >-
                        Mozilla/5.0 (Windows NT 10.0; Win64; x64)
                        AppleWebKit/537.36
                      accept_header: text/html,application/xhtml+xml,application/xml;q=0.9
                      color_depth: '24'
                      screen_height: '1080'
                      screen_width: '1920'
                      language: es-CO
                      javascript_enabled: true
                      java_enabled: false
                      browser_time_difference: '-300'
                      platform: WEB
                    device_fingerprints:
                      - provider_id: f3a8b5d2-9c4e-4a7b-b1f8-2d6c9e0a4f12
                        id: fp_abc123xyz
              schema:
                type: object
                properties:
                  three_d_secure_setup_id:
                    type: string
                    description: >-
                      Generated identifier of the 3DS2 setup. Pass this under
                      `payment_method.detail.card.three_d_secure.three_d_secure_setup_id`
                      on the subsequent `POST /v1/payments`.
                    example: a17b4f2c-08d1-4e9b-b6c5-9a3e0c7f1b22
                  account_id:
                    type: string
                    description: Echo of the request `account_id`.
                    example: 11111111-1111-1111-1111-111111111111
                  type:
                    type: string
                    description: Echo of the request `type`.
                    example: MERCHANT_PROVIDED
                  browser_info:
                    type: object
                    description: Echo of the request `browser_info`.
                    properties:
                      user_agent:
                        type: string
                        example: >-
                          Mozilla/5.0 (Windows NT 10.0; Win64; x64)
                          AppleWebKit/537.36
                      accept_header:
                        type: string
                        example: text/html,application/xhtml+xml,application/xml;q=0.9
                      color_depth:
                        type: string
                        example: '24'
                      screen_height:
                        type: string
                        example: '1080'
                      screen_width:
                        type: string
                        example: '1920'
                      language:
                        type: string
                        example: es-CO
                      javascript_enabled:
                        type: boolean
                        example: true
                      java_enabled:
                        type: boolean
                        example: false
                      browser_time_difference:
                        type: string
                        example: '-300'
                      platform:
                        type: string
                        example: WEB
                  device_fingerprints:
                    type: array
                    description: Echo of the request `device_fingerprints`.
                    items:
                      type: object
                      properties:
                        provider_id:
                          type: string
                          example: f3a8b5d2-9c4e-4a7b-b1f8-2d6c9e0a4f12
                        id:
                          type: string
                          example: fp_abc123xyz
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Invalid parameters:
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - account_id must be a valid UUIDv4
                    httpCode: 400
                Missing parameters:
                  value:
                    code: MISSING_PARAMETERS
                    messages:
                      - account_id is required
                    httpCode: 400
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: INVALID_PARAMETERS
                  messages:
                    type: array
                    items:
                      type: string
                      example: account_id must be a valid UUIDv4
                  httpCode:
                    type: integer
                    example: 400
        '401':
          description: '401'
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    code: NOT_AUTHENTICATED
                    messages:
                      - Missing API credentials
                    httpCode: 401
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: NOT_AUTHENTICATED
                  messages:
                    type: array
                    items:
                      type: string
                      example: Missing API credentials
                  httpCode:
                    type: integer
                    example: 401
        '403':
          description: '403'
          content:
            application/json:
              examples:
                Forbidden:
                  value:
                    code: FORBIDDEN
                    messages:
                      - Account inactive or lacks 3DS2 entitlement
                    httpCode: 403
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: FORBIDDEN
                  messages:
                    type: array
                    items:
                      type: string
                      example: Account inactive or lacks 3DS2 entitlement
                  httpCode:
                    type: integer
                    example: 403
      deprecated: false
components:
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: public-api-key
      x-default: <Your public-api-key>
    sec1:
      type: apiKey
      in: header
      name: private-secret-key
      x-default: <Your private-secret-key>
    sec2:
      type: apiKey
      in: header
      name: X-Idempotency-Key
      x-default: <Your X-Idempotency-Key>

````