From 37ff9312c87457e2b7a29593b9e82850f29baadf Mon Sep 17 00:00:00 2001 From: Jing Li Date: Thu, 16 Jul 2026 18:35:59 -0400 Subject: [PATCH] Add 2 more well-known values to signals.json for abuse prevention. --- docs/specification/checkout-a2a.md | 7 ++++++- docs/specification/checkout-rest.md | 7 ++++++- .../examples/encrypted-credential-handler.md | 7 ++++++- .../platform-tokenizer-payment-handler.md | 7 ++++++- .../processor-tokenizer-payment-handler.md | 7 ++++++- docs/specification/overview.md | 17 ++++++++++++++--- source/schemas/shopping/types/signals.json | 8 ++++++++ 7 files changed, 52 insertions(+), 8 deletions(-) diff --git a/docs/specification/checkout-a2a.md b/docs/specification/checkout-a2a.md index 70d9f4ab8..8b1a35c9b 100644 --- a/docs/specification/checkout-a2a.md +++ b/docs/specification/checkout-a2a.md @@ -267,7 +267,12 @@ checkout object containing an `order` attribute with `id` and `permalink_url`. "a2a.ucp.checkout.payment": { ... }, "a2a.ucp.checkout.signals": { "dev.ucp.buyer_ip": "203.0.113.42", - "dev.ucp.user_agent": "Mozilla/5.0 ..." + "dev.ucp.user_agent": "Mozilla/5.0 ...", + "dev.ucp.user_id": "0a041b9462caa4a31bac3567e...", + "dev.ucp.user_location": { + "address_region": "CA", + "address_country": "US" + } } } } diff --git a/docs/specification/checkout-rest.md b/docs/specification/checkout-rest.md index 136ef3ef4..68d3246b1 100644 --- a/docs/specification/checkout-rest.md +++ b/docs/specification/checkout-rest.md @@ -804,7 +804,12 @@ place to set these expectations via `messages`. }, "signals": { "dev.ucp.buyer_ip": "203.0.113.42", - "dev.ucp.user_agent": "Mozilla/5.0 ..." + "dev.ucp.user_agent": "Mozilla/5.0 ...", + "dev.ucp.user_id": "0a041b9462caa4a31bac3567e...", + "dev.ucp.user_location": { + "address_region": "CA", + "address_country": "US" + } } } ``` diff --git a/docs/specification/examples/encrypted-credential-handler.md b/docs/specification/examples/encrypted-credential-handler.md index 58779ce83..c8e10a360 100644 --- a/docs/specification/examples/encrypted-credential-handler.md +++ b/docs/specification/examples/encrypted-credential-handler.md @@ -334,7 +334,12 @@ Content-Type: application/json }, "signals": { "dev.ucp.buyer_ip": "203.0.113.42", - "dev.ucp.user_agent": "Mozilla/5.0 ..." + "dev.ucp.user_agent": "Mozilla/5.0 ...", + "dev.ucp.user_id": "0a041b9462caa4a31bac3567e...", + "dev.ucp.user_location": { + "address_region": "CA", + "address_country": "US" + } } } ``` diff --git a/docs/specification/examples/platform-tokenizer-payment-handler.md b/docs/specification/examples/platform-tokenizer-payment-handler.md index bf4962f2b..4c70911b9 100644 --- a/docs/specification/examples/platform-tokenizer-payment-handler.md +++ b/docs/specification/examples/platform-tokenizer-payment-handler.md @@ -403,7 +403,12 @@ Content-Type: application/json }, "signals": { "dev.ucp.buyer_ip": "203.0.113.42", - "dev.ucp.user_agent": "Mozilla/5.0 ..." + "dev.ucp.user_agent": "Mozilla/5.0 ...", + "dev.ucp.user_id": "0a041b9462caa4a31bac3567e...", + "dev.ucp.user_location": { + "address_region": "CA", + "address_country": "US" + } } } ``` diff --git a/docs/specification/examples/processor-tokenizer-payment-handler.md b/docs/specification/examples/processor-tokenizer-payment-handler.md index deac8e020..3cca38c76 100644 --- a/docs/specification/examples/processor-tokenizer-payment-handler.md +++ b/docs/specification/examples/processor-tokenizer-payment-handler.md @@ -273,7 +273,12 @@ Content-Type: application/json }, "signals": { "dev.ucp.buyer_ip": "203.0.113.42", - "dev.ucp.user_agent": "Mozilla/5.0 ..." + "dev.ucp.user_agent": "Mozilla/5.0 ...", + "dev.ucp.user_id": "0a041b9462caa4a31bac3567e...", + "dev.ucp.user_location": { + "address_region": "CA", + "address_country": "US" + } } } ``` diff --git a/docs/specification/overview.md b/docs/specification/overview.md index 452e7a5b7..dd1be6584 100644 --- a/docs/specification/overview.md +++ b/docs/specification/overview.md @@ -1696,7 +1696,12 @@ POST /checkout-sessions/{id}/complete }, "signals": { "dev.ucp.buyer_ip": "203.0.113.42", - "dev.ucp.user_agent": "Mozilla/5.0 ..." + "dev.ucp.user_agent": "Mozilla/5.0 ...", + "dev.ucp.user_id": "0a041b9462caa4a31bac3567e...", + "dev.ucp.user_location": { + "address_region": "SC", + "address_country": "US" + } } } ``` @@ -1763,7 +1768,12 @@ POST /checkout-sessions/{id}/complete }, "signals": { "dev.ucp.buyer_ip": "203.0.113.42", - "dev.ucp.user_agent": "Mozilla/5.0 ..." + "dev.ucp.user_agent": "Mozilla/5.0 ...", + "dev.ucp.user_id": "0a041b9462caa4a31bac3567e...", + "dev.ucp.user_location": { + "address_region": "CA", + "address_country": "US" + } } } ``` @@ -1845,6 +1855,7 @@ POST /checkout-sessions/{id}/complete }, "signals": { "dev.ucp.buyer_ip": "203.0.113.42", + "dev.ucp.user_id": "0a041b9462caa4a31bac3567e...", "com.example.risk_score": 0.95 }, "ap2": { @@ -1930,7 +1941,7 @@ certified and handle: UCP supports fraud prevention through [Signals](#signals) and the payment architecture: -- Platforms provide transaction environment [signals](#signals) (IP, user +- Platforms provide transaction environment [signals](#signals) (e.g., IP, user agent) on catalog, cart, and checkout requests - Businesses can require additional fields in handler configurations (e.g., 3DS requirements) diff --git a/source/schemas/shopping/types/signals.json b/source/schemas/shopping/types/signals.json index dfd58d0de..b0829e9fc 100644 --- a/source/schemas/shopping/types/signals.json +++ b/source/schemas/shopping/types/signals.json @@ -16,6 +16,14 @@ "dev.ucp.user_agent": { "type": "string", "description": "Client's HTTP User-Agent header or equivalent." + }, + "dev.ucp.user_id": { + "type": "string", + "description": "A stable, opaque identifier for the user represented by the platform. MUST be consistent across sessions for the same user." + }, + "dev.ucp.user_location": { + "$ref": "../../common/types/locality.json", + "description": "User's geographic location. Platforms SHOULD populate at least region & country." } }, "additionalProperties": true