Create 3DS2 Setup - Yuno API Documentation

curl --request POST \
  --url https://api-sandbox.y.uno/v1/three-d-secure/setups \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <api-key>' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>' \
  --data '
{
  "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"
    }
  ]
}
'

{
  "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"
    }
  ]
}

POST

three-d-secure

setups

curl --request POST \
  --url https://api-sandbox.y.uno/v1/three-d-secure/setups \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <api-key>' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>' \
  --data '
{
  "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"
    }
  ]
}
'

{
  "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"
    }
  ]
}

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.

Server-to-server integrations onlyUse 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.

Registration step onlyThis 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.

Device-data quality mattersThe 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.

How the merchant supplies device dataThe 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 instead.

How to use the response

Store the id. Keep three_d_secure_setup_id against the order on your side.
Reference it on the payment. On the subsequent 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 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`).

Authorizations

public-api-key

string

header

default:<Your public-api-key>

required

private-secret-key

string

header

default:<Your private-secret-key>

required

X-Idempotency-Key

string

header

default:<Your X-Idempotency-Key>

required

Body

application/json

account_id

string<uuid>

required

Account UUID that owns this 3DS2 setup.

type

enum<string>

required

Source of the device data. MERCHANT_PROVIDED means you collected the browser/device data on your side and are passing it in directly.

Available options:

MERCHANT_PROVIDED

browser_info

object

required

Browser environment captured from the cardholder's session. Forwarded verbatim to the 3DS2 server for risk scoring and frictionless decisioning.

Show child attributes

device_fingerprints

object[]

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.

Show child attributes

Response

201

three_d_secure_setup_id

string

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

string

Echo of the request account_id.

Example:

"11111111-1111-1111-1111-111111111111"

type

string

Echo of the request type.

Example:

"MERCHANT_PROVIDED"

browser_info

object

Echo of the request browser_info.

Show child attributes

device_fingerprints

object[]

Echo of the request device_fingerprints.

Show child attributes

​How to use the response

​Field rules and edge cases

Authorizations

Body

Response

How to use the response

Field rules and edge cases