Skip to main content

Risk metadata

riskMetadata is the field on a tokenization request that carries the customer's device, browser, and session context to the issuer. The richer the data you send, the higher the chance of a frictionless 3DS outcome and the better PaymentsAI can score the transaction for fraud.

Sending complete riskMetadata on every tokenization call, including for returning customers, is a significant way to increase approval rates.

Scope:

riskMetadata is accepted only on the production tokenization endpoint (POST https://tokenization.payments.ai/tokens). It is not a field on POST /transactions or POST /subscriptions because fraud and 3DS signals must be captured at tokenization time. The stage endpoint (POST /v1/public-api/.../payment-instruments/tokens) uses a different body shape and rejects riskMetadata. See the Tokenization endpoint tutorial.

Where it goes​

riskMetadata is an optional object on the tokenization request body. Example:

{
  "method": "payment-card",
  "paymentInstrument": { "pan": "...", "cvv": "...", "expMonth": 12, "expYear": 2030 },
  "riskMetadata": {
    "ipAddress": "93.92.91.90",
    "fingerprint": "pIUt3xbgX3l9g3YDiLbx",
    "httpHeaders": {
      "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
    },
    "browserData": {
      "colorDepth": 24,
      "isJavaEnabled": true,
      "language": "en-US",
      "screenWidth": 1920,
      "screenHeight": 1080,
      "timeZoneOffset": 300,
      "isAdBlockEnabled": false
    },
    "extraData": {
      "kountFraudSessionId": "abcdefg12345abababab123456789012",
      "payPalMerchantSessionId": "dd65ratxc5qv15iph3vyoq7l6davuowa",
      "threatMetrixSessionId": "dd65ratxc5qv15iph3vyoq7l6davuowa"
    }
  }
}

Field reference​

ipAddress​

The customer's real IP address at the moment of payment.

  • Send the customer's IP, not your server IP, not a proxy. A common mistake is to capture the request's source IP on your backend, which records your own server or a load balancer.
  • The issuer uses this for geolocation matching: an IP whose country matches the billing country is a positive risk signal; a mismatch is a fraud signal.
  • This is a key factor for 3DS frictionless authentication in the EU.

fingerprint​

A stable device fingerprint generated client-side.

  • The same customer on the same device should produce the same fingerprint every time. Do not regenerate the fingerprint on every page load; sudden fingerprint changes for the same customer are flagged as fraud.
  • Returning customers with a consistent fingerprint history are more likely to authenticate frictionlessly.

httpHeaders​

A copy of the customer's HTTP request headers, typically Accept and User-Agent.

  • These contribute to device fingerprinting and bot detection.
  • Pass the headers from the customer's actual request, not your server's default headers.

browserData: required for 3DS2 frictionless​

Under PSD2 SCA, the issuer needs the full set of browser fields to decide whether the transaction can go through frictionless. Missing any of these fields commonly causes the issuer to fall back to a 3DS challenge, causing a popup or redirect for the customer.

Required fields under 3DS2:

  • colorDepth: Screen color depth in bits.
  • isJavaEnabled: Whether Java is enabled in the browser.
  • language: Browser language (en-US, pl-PL, etc.).
  • screenWidth: Screen width in pixels.
  • screenHeight: Screen height in pixels.
  • timeZoneOffset: UTC offset in minutes (300 for UTC-5, -60 for UTC+1).

Optional but recommended:

  • isAdBlockEnabled: Whether an ad blocker is active.

Sending the full browserData set gives approximately a 5% to 10% approval rate uplift for EU transactions by maximizing the chance of frictionless authentication.

extraData: fraud platform session IDs​

If you use a third-party fraud platform, pass its session ID here so PaymentsAI can correlate the transaction with that platform's risk score.

  • kountFraudSessionId: Kount session.
  • payPalMerchantSessionId: PayPal Fraud Net session.
  • threatMetrixSessionId: ThreatMetrix session.

Typical uplift from including fraud platform session IDs lands between 1% and 3%.

Always send on every call​

Send riskMetadata on every tokenization call, including for returning customers. The issuer scores each transaction in isolation; there is no trusted customer shortcut on the network. Skipping riskMetadata for returning customers drops your baseline approval rate.

For the broader approval rate strategy, see How to increase approval rate.