From 25b86c506175f5ed478d79fc90082d1051e40151 Mon Sep 17 00:00:00 2001 From: Gregory Oschwald Date: Fri, 9 Oct 2026 20:42:29 +0000 Subject: [PATCH 1/5] Add phone verification inputs to minFraud The minFraud request `billing` and `shipping` objects now accept three optional inputs that describe the most recent verification of the phone number: `phone_verification_method`, `phone_was_verification_successful`, and `phone_verification_time`. Risk scoring uses the shipping phone when the billing phone is absent. Both objects share the `Address` schema, so the inputs live there. The request example and the bundled spec include them. Co-Authored-By: Claude Opus 5.5 --- bundled/minfraud.yaml | 25 +++++++++++++++++++++++++ components/minfraud-request.yaml | 30 ++++++++++++++++++++++++++++++ examples/minfraud/request.yaml | 6 ++++++ 3 files changed, 61 insertions(+) diff --git a/bundled/minfraud.yaml b/bundled/minfraud.yaml index ebfa7fc..0a58be1 100644 --- a/bundled/minfraud.yaml +++ b/bundled/minfraud.yaml @@ -550,6 +550,25 @@ components: type: string maxLength: 255 description: The phone number, without the country code. MaxMind strips punctuation characters. After that, the number must contain only digits. + phone_verification_method: + type: string + enum: + - delivered_code + - network + - other + description: |- + The most recent method used to verify the phone number. + + - `delivered_code`: a code delivered to the phone, such as by SMS, voice call, or messaging app. + - `network`: verification through the mobile network operator, such as silent network authentication. + - `other`: another verification method. + phone_verification_time: + type: string + format: date-time + description: The date and time of the most recent verification of the phone number, in RFC 3339 date-time format. The time must not be before 1970-01-01T00:00:00Z or more than two days in the future. For a time outside this range, MaxMind ignores the input and returns a warning. + phone_was_verification_successful: + type: boolean + description: Whether the most recent verification of the phone number succeeded. Omit this field if no verification was attempted. postal: type: string maxLength: 255 @@ -1901,6 +1920,9 @@ components: last_name: Doe phone_country_code: '1' phone_number: 203-000-0000 + phone_verification_method: delivered_code + phone_verification_time: '2026-10-01T14:30:00Z' + phone_was_verification_successful: true postal: '06511' region: CT credit_card: @@ -1956,6 +1978,9 @@ components: last_name: Doe phone_country_code: '1' phone_number: 203-000-0000 + phone_verification_method: delivered_code + phone_verification_time: '2026-10-01T14:35:00Z' + phone_was_verification_successful: true postal: '06515' region: CT shopping_cart: diff --git a/components/minfraud-request.yaml b/components/minfraud-request.yaml index 36b3f8e..32535c8 100644 --- a/components/minfraud-request.yaml +++ b/components/minfraud-request.yaml @@ -246,6 +246,36 @@ schemas: description: >- The phone number, without the country code. MaxMind strips punctuation characters. After that, the number must contain only digits. + phone_verification_method: + type: string + enum: + - delivered_code + - network + - other + description: >- + The most recent method used to verify the phone number. + + + - `delivered_code`: a code delivered to the phone, such as by SMS, + voice call, or messaging app. + + - `network`: verification through the mobile network operator, such as + silent network authentication. + + - `other`: another verification method. + phone_verification_time: + type: string + format: date-time + description: >- + The date and time of the most recent verification of the phone number, + in RFC 3339 date-time format. The time must not be before + 1970-01-01T00:00:00Z or more than two days in the future. For a time + outside this range, MaxMind ignores the input and returns a warning. + phone_was_verification_successful: + type: boolean + description: >- + Whether the most recent verification of the phone number succeeded. + Omit this field if no verification was attempted. postal: type: string maxLength: 255 diff --git a/examples/minfraud/request.yaml b/examples/minfraud/request.yaml index faa4c49..5192029 100644 --- a/examples/minfraud/request.yaml +++ b/examples/minfraud/request.yaml @@ -13,6 +13,9 @@ value: last_name: Doe phone_country_code: "1" phone_number: 203-000-0000 + phone_verification_method: delivered_code + phone_verification_time: "2026-10-01T14:30:00Z" + phone_was_verification_successful: true postal: "06511" region: CT credit_card: @@ -70,6 +73,9 @@ value: last_name: Doe phone_country_code: "1" phone_number: 203-000-0000 + phone_verification_method: delivered_code + phone_verification_time: "2026-10-01T14:35:00Z" + phone_was_verification_successful: true postal: "06515" region: CT shopping_cart: From 4cf587968a335f2b4febfdce9e66d6679d85b402 Mon Sep 17 00:00:00 2001 From: Gregory Oschwald Date: Mon, 19 Oct 2026 20:43:59 +0000 Subject: [PATCH 2/5] Use the dev docs wording for phone verification inputs Match the descriptions on dev.maxmind.com. The method and time describe the most recent verification attempt, not the most recent successful one. The method is omitted when no verification was attempted. The network, delivered_code and other descriptions now give the same examples as the docs, in the same order. Co-Authored-By: Claude Opus 5.5 --- bundled/minfraud.yaml | 14 ++++++------- components/minfraud-request.yaml | 34 ++++++++++++++++++++------------ 2 files changed, 28 insertions(+), 20 deletions(-) diff --git a/bundled/minfraud.yaml b/bundled/minfraud.yaml index 0a58be1..ae165e3 100644 --- a/bundled/minfraud.yaml +++ b/bundled/minfraud.yaml @@ -553,22 +553,22 @@ components: phone_verification_method: type: string enum: - - delivered_code - network + - delivered_code - other description: |- - The most recent method used to verify the phone number. + The method used for the most recent verification attempt of the phone number. Do not include this field if no verification was attempted. - - `delivered_code`: a code delivered to the phone, such as by SMS, voice call, or messaging app. - - `network`: verification through the mobile network operator, such as silent network authentication. - - `other`: another verification method. + - `network`: carrier or SIM-based silent network authentication. No code is sent to the device. + - `delivered_code`: a one-time code delivered to the phone number by SMS, an automated voice call, or an over-the-top messaging channel such as WhatsApp or RCS, and entered by the user. + - `other`: a method not listed above, such as flash or missed call verification, or a method you do not know because a third party performed the check. phone_verification_time: type: string format: date-time - description: The date and time of the most recent verification of the phone number, in RFC 3339 date-time format. The time must not be before 1970-01-01T00:00:00Z or more than two days in the future. For a time outside this range, MaxMind ignores the input and returns a warning. + description: The most recent date and time a verification of the phone number was attempted, if known, in RFC 3339 date-time format. The time must not be before 1970-01-01T00:00:00Z or more than two days in the future. For a time outside this range, MaxMind ignores the input and returns a warning. phone_was_verification_successful: type: boolean - description: Whether the most recent verification of the phone number succeeded. Omit this field if no verification was attempted. + description: Whether the most recent verification that the end user controls this phone number was successful, using the method named in `phone_verification_method`. `true` if the phone verification was successful, or `false` if the user failed phone verification. Do not include this field if you have not performed this check. postal: type: string maxLength: 255 diff --git a/components/minfraud-request.yaml b/components/minfraud-request.yaml index 32535c8..d2c5460 100644 --- a/components/minfraud-request.yaml +++ b/components/minfraud-request.yaml @@ -249,33 +249,41 @@ schemas: phone_verification_method: type: string enum: - - delivered_code - network + - delivered_code - other description: >- - The most recent method used to verify the phone number. + The method used for the most recent verification attempt of the phone + number. Do not include this field if no verification was attempted. - - `delivered_code`: a code delivered to the phone, such as by SMS, - voice call, or messaging app. + - `network`: carrier or SIM-based silent network authentication. No + code is sent to the device. - - `network`: verification through the mobile network operator, such as - silent network authentication. + - `delivered_code`: a one-time code delivered to the phone number by + SMS, an automated voice call, or an over-the-top messaging channel + such as WhatsApp or RCS, and entered by the user. - - `other`: another verification method. + - `other`: a method not listed above, such as flash or missed call + verification, or a method you do not know because a third party + performed the check. phone_verification_time: type: string format: date-time description: >- - The date and time of the most recent verification of the phone number, - in RFC 3339 date-time format. The time must not be before - 1970-01-01T00:00:00Z or more than two days in the future. For a time - outside this range, MaxMind ignores the input and returns a warning. + The most recent date and time a verification of the phone number was + attempted, if known, in RFC 3339 date-time format. The time must not + be before 1970-01-01T00:00:00Z or more than two days in the future. + For a time outside this range, MaxMind ignores the input and returns a + warning. phone_was_verification_successful: type: boolean description: >- - Whether the most recent verification of the phone number succeeded. - Omit this field if no verification was attempted. + Whether the most recent verification that the end user controls this + phone number was successful, using the method named in + `phone_verification_method`. `true` if the phone verification was + successful, or `false` if the user failed phone verification. Do not + include this field if you have not performed this check. postal: type: string maxLength: 255 From f662b295efe6f4c3037978048a3837048df94029 Mon Sep 17 00:00:00 2001 From: Gregory Oschwald Date: Mon, 19 Oct 2026 20:44:24 +0000 Subject: [PATCH 3/5] Require the RFC 3339 form that the web service accepts format: date-time follows RFC 3339, which allows a lowercase "t" and "z" and a leap second. The web service rejects these and ignores the input with a warning. Add a pattern to the event time and the phone verification time that allows only an uppercase "T" and "Z", hours 00 to 23, minutes and seconds 00 to 59, and offsets up to 23:59. Co-Authored-By: Claude Opus 5.5 --- bundled/minfraud.yaml | 2 ++ components/minfraud-request.yaml | 2 ++ 2 files changed, 4 insertions(+) diff --git a/bundled/minfraud.yaml b/bundled/minfraud.yaml index ae165e3..f828175 100644 --- a/bundled/minfraud.yaml +++ b/bundled/minfraud.yaml @@ -565,6 +565,7 @@ components: phone_verification_time: type: string format: date-time + pattern: ^\d{4}-\d{2}-\d{2}T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z|[+-]([01]\d|2[0-3]):[0-5]\d)$ description: The most recent date and time a verification of the phone number was attempted, if known, in RFC 3339 date-time format. The time must not be before 1970-01-01T00:00:00Z or more than two days in the future. For a time outside this range, MaxMind ignores the input and returns a warning. phone_was_verification_successful: type: boolean @@ -689,6 +690,7 @@ components: time: type: string format: date-time + pattern: ^\d{4}-\d{2}-\d{2}T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z|[+-]([01]\d|2[0-3]):[0-5]\d)$ description: |- The time the event occurred, in RFC 3339 format. If you omit this field, MaxMind uses the time it receives the request. MaxMind does not recommend this field for live transactions. It can be useful for stored transactions that you score later. diff --git a/components/minfraud-request.yaml b/components/minfraud-request.yaml index d2c5460..b6c2ea7 100644 --- a/components/minfraud-request.yaml +++ b/components/minfraud-request.yaml @@ -113,6 +113,7 @@ schemas: time: type: string format: date-time + pattern: "^\\d{4}-\\d{2}-\\d{2}T([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(\\.\\d+)?(Z|[+-]([01]\\d|2[0-3]):[0-5]\\d)$" description: >- The time the event occurred, in RFC 3339 format. If you omit this field, MaxMind uses the time it receives the request. MaxMind does not @@ -270,6 +271,7 @@ schemas: phone_verification_time: type: string format: date-time + pattern: "^\\d{4}-\\d{2}-\\d{2}T([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(\\.\\d+)?(Z|[+-]([01]\\d|2[0-3]):[0-5]\\d)$" description: >- The most recent date and time a verification of the phone number was attempted, if known, in RFC 3339 date-time format. The time must not From 30399f371c2de9260cdca794431e68f60fe95101 Mon Sep 17 00:00:00 2001 From: Gregory Oschwald Date: Mon, 19 Oct 2026 20:44:24 +0000 Subject: [PATCH 4/5] Use the same shipping verification time as the dev docs Co-Authored-By: Claude Opus 5.5 --- bundled/minfraud.yaml | 2 +- examples/minfraud/request.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/bundled/minfraud.yaml b/bundled/minfraud.yaml index f828175..368801b 100644 --- a/bundled/minfraud.yaml +++ b/bundled/minfraud.yaml @@ -1981,7 +1981,7 @@ components: phone_country_code: '1' phone_number: 203-000-0000 phone_verification_method: delivered_code - phone_verification_time: '2026-10-01T14:35:00Z' + phone_verification_time: '2026-10-01T14:30:00Z' phone_was_verification_successful: true postal: '06515' region: CT diff --git a/examples/minfraud/request.yaml b/examples/minfraud/request.yaml index 5192029..6cde525 100644 --- a/examples/minfraud/request.yaml +++ b/examples/minfraud/request.yaml @@ -74,7 +74,7 @@ value: phone_country_code: "1" phone_number: 203-000-0000 phone_verification_method: delivered_code - phone_verification_time: "2026-10-01T14:35:00Z" + phone_verification_time: "2026-10-01T14:30:00Z" phone_was_verification_successful: true postal: "06515" region: CT From 5f17866b3f70f791581569b884bde7bbf87e556f Mon Sep 17 00:00:00 2001 From: Gregory Oschwald Date: Mon, 19 Oct 2026 20:44:24 +0000 Subject: [PATCH 5/5] Mark the bundled specs as generated GitHub then collapses bundled/ in pull request diffs. Co-Authored-By: Claude Opus 5.5 --- .gitattributes | 1 + 1 file changed, 1 insertion(+) create mode 100644 .gitattributes diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..53a7517 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +bundled/** linguist-generated=true