Skip to main content
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

  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, 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

RuleBehavior
type set to a value other than MERCHANT_PROVIDED400 INVALID_PARAMETERS. Other values are reserved for future use.
browser_info.platform set to an unsupported value400 INVALID_PARAMETERS. Allowed: WEB, IOS, ANDROID.
device_fingerprints omittedAccepted. Yuno will skip device-fingerprint enrichment for any provider that wasn’t pre-supplied.
device_fingerprints[*].provider_id not found in your accountEntry is dropped silently; setup proceeds with the remaining entries.
account_id not owned by the API keyTreated 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.

​
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.

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.

​
device_fingerprints
object[]

Echo of the request device_fingerprints.