From 67fef450c3fffe960f697ffebf0841265b0fd87d Mon Sep 17 00:00:00 2001 From: William Storey Date: Tue, 3 Nov 2026 21:47:31 +0000 Subject: [PATCH 1/4] Do not report pending verifications as failed The verification result fields did not say what to send while a verification is pending. A merchant could send false for a link that the user has not clicked yet, and minFraud would see a failed check. Define the result as that of the most recent completed verification. A pending, abandoned, or expired verification is not complete and is not a failure. If no verification is complete, leave out the field. The phone method field described the most recent verification attempt, which can be pending. Make it describe the same completed verification as the result field, so that a merchant does not send a method from a pending attempt next to a result from an earlier one. Co-Authored-By: Claude Opus 5.5 --- bundled/minfraud.yaml | 6 +++--- components/minfraud-request.yaml | 27 +++++++++++++++++---------- 2 files changed, 20 insertions(+), 13 deletions(-) diff --git a/bundled/minfraud.yaml b/bundled/minfraud.yaml index 11d7b45..64cfbc6 100644 --- a/bundled/minfraud.yaml +++ b/bundled/minfraud.yaml @@ -573,7 +573,7 @@ components: - delivered_code - other description: |- - The method used for the most recent verification attempt of the phone number. Do not include this field if no verification was attempted. + The method used for the most recent completed verification of the phone number. Do not include this field if no verification was attempted or no verification is complete. - `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. @@ -583,7 +583,7 @@ components: 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 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. + description: Whether the most recent completed 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. A pending, abandoned, or expired verification is not complete and is not a failure. If no verification is complete, for example because the user has not entered the code yet, do not include this field. Do not include this field if you have not performed this check. postal: type: string maxLength: 255 @@ -693,7 +693,7 @@ components: description: The most recent date and time a verification of the email address 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. was_verification_successful: type: boolean - description: Whether the most recent verification that the end user controls this email address was successful (e.g. by confirming a link sent to the email address). `true` if the email verification was successful, or `false` if the user failed email verification. Do not include this field if you have not performed this check. + description: Whether the most recent completed verification that the end user controls this email address was successful (e.g. by confirming a link sent to the email address). `true` if the email verification was successful, or `false` if the user failed email verification. A pending, abandoned, or expired verification is not complete and is not a failure. If no verification is complete, for example because the user has not clicked the link yet, do not include this field. Do not include this field if you have not performed this check. Event: type: object properties: diff --git a/components/minfraud-request.yaml b/components/minfraud-request.yaml index 45cce93..f39b6f2 100644 --- a/components/minfraud-request.yaml +++ b/components/minfraud-request.yaml @@ -216,11 +216,14 @@ schemas: was_verification_successful: type: boolean description: >- - Whether the most recent verification that the end user controls this - email address was successful (e.g. by confirming a link sent to the - email address). `true` if the email verification was successful, or - `false` if the user failed email verification. Do not include this - field if you have not performed this check. + Whether the most recent completed verification that the end user + controls this email address was successful (e.g. by confirming a link + sent to the email address). `true` if the email verification was + successful, or `false` if the user failed email verification. A + pending, abandoned, or expired verification is not complete and is not + a failure. If no verification is complete, for example because the + user has not clicked the link yet, do not include this field. Do not + include this field if you have not performed this check. Address: type: object description: A billing or shipping address. @@ -268,8 +271,9 @@ schemas: - delivered_code - other description: >- - The method used for the most recent verification attempt of the phone - number. Do not include this field if no verification was attempted. + The method used for the most recent completed verification of the + phone number. Do not include this field if no verification was + attempted or no verification is complete. - `network`: carrier or SIM-based silent network authentication. No @@ -293,10 +297,13 @@ schemas: phone_was_verification_successful: type: boolean description: >- - Whether the most recent verification that the end user controls this - phone number was successful, using the method named in + Whether the most recent completed 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 + successful, or `false` if the user failed phone verification. A + pending, abandoned, or expired verification is not complete and is not + a failure. If no verification is complete, for example because the + user has not entered the code yet, do not include this field. Do not include this field if you have not performed this check. postal: type: string From 5286e584836186c093fd48abf5eb8d38009c3eee Mon Sep 17 00:00:00 2001 From: William Storey Date: Tue, 3 Nov 2026 21:47:40 +0000 Subject: [PATCH 2/4] Define verification time as the time of the result "The most recent date and time a verification was attempted" could mean the time the merchant sent the link or code, or the time the user used it. For email, these times can be days apart. Define the time as the time the most recent completed verification succeeded or failed. A pending verification is neutral, so the time a link or code was sent is not a result time. Co-Authored-By: Claude Opus 5.5 --- bundled/minfraud.yaml | 4 ++-- components/minfraud-request.yaml | 20 ++++++++++++-------- 2 files changed, 14 insertions(+), 10 deletions(-) diff --git a/bundled/minfraud.yaml b/bundled/minfraud.yaml index 64cfbc6..8a44bbf 100644 --- a/bundled/minfraud.yaml +++ b/bundled/minfraud.yaml @@ -580,7 +580,7 @@ components: - `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: $ref: '#/components/schemas/DateTime' - 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. + description: The date and time of the most recent completed verification of the phone number, if known, in RFC 3339 date-time format. Use the time the verification succeeded or failed, for example the time the user entered the code, not the time you sent the code. 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 completed 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. A pending, abandoned, or expired verification is not complete and is not a failure. If no verification is complete, for example because the user has not entered the code yet, do not include this field. Do not include this field if you have not performed this check. @@ -690,7 +690,7 @@ components: description: The domain of the email address. Do not include the `@`. You do not need to send this field unless you send the email address as an MD5 hash. verification_time: $ref: '#/components/schemas/DateTime' - description: The most recent date and time a verification of the email address 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. + description: The date and time of the most recent completed verification of the email address, if known, in RFC 3339 date-time format. Use the time the verification succeeded or failed, for example the time the user clicked the link, not the time you sent the link. 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. was_verification_successful: type: boolean description: Whether the most recent completed verification that the end user controls this email address was successful (e.g. by confirming a link sent to the email address). `true` if the email verification was successful, or `false` if the user failed email verification. A pending, abandoned, or expired verification is not complete and is not a failure. If no verification is complete, for example because the user has not clicked the link yet, do not include this field. Do not include this field if you have not performed this check. diff --git a/components/minfraud-request.yaml b/components/minfraud-request.yaml index f39b6f2..3bfa097 100644 --- a/components/minfraud-request.yaml +++ b/components/minfraud-request.yaml @@ -208,10 +208,12 @@ schemas: verification_time: $ref: "#/schemas/DateTime" description: >- - The most recent date and time a verification of the email address 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 + The date and time of the most recent completed verification of the + email address, if known, in RFC 3339 date-time format. Use the time + the verification succeeded or failed, for example the time the user + clicked the link, not the time you sent the link. 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. was_verification_successful: type: boolean @@ -289,10 +291,12 @@ schemas: phone_verification_time: $ref: "#/schemas/DateTime" 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 + The date and time of the most recent completed verification of the + phone number, if known, in RFC 3339 date-time format. Use the time the + verification succeeded or failed, for example the time the user + entered the code, not the time you sent the code. 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 From 78819bcdad061aead46bf02cc846ecd44087aa68 Mon Sep 17 00:00:00 2001 From: William Storey Date: Tue, 3 Nov 2026 21:47:50 +0000 Subject: [PATCH 3/4] Describe verification state as of the event time You can score a stored event later with /event/time. The verification fields did not say whether to send the state at the time of the event or at the time of the request. If a merchant sends the current state, the model sees information from after the event. Say that the email and phone verification fields must reflect the state as of the time of the event. Co-Authored-By: Claude Opus 5.5 --- bundled/minfraud.yaml | 10 ++++---- components/minfraud-request.yaml | 39 ++++++++++++++++++-------------- 2 files changed, 27 insertions(+), 22 deletions(-) diff --git a/bundled/minfraud.yaml b/bundled/minfraud.yaml index 8a44bbf..187f121 100644 --- a/bundled/minfraud.yaml +++ b/bundled/minfraud.yaml @@ -573,17 +573,17 @@ components: - delivered_code - other description: |- - The method used for the most recent completed verification of the phone number. Do not include this field if no verification was attempted or no verification is complete. + The method used for the most recent completed verification of the phone number. The value must reflect the verification state as of the time of the event. Do not include this field if no verification was attempted or no verification is complete. - `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: $ref: '#/components/schemas/DateTime' - description: The date and time of the most recent completed verification of the phone number, if known, in RFC 3339 date-time format. Use the time the verification succeeded or failed, for example the time the user entered the code, not the time you sent the code. 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 date and time of the most recent completed verification of the phone number, if known, in RFC 3339 date-time format. The value must reflect the verification state as of the time of the event. Use the time the verification succeeded or failed, for example the time the user entered the code, not the time you sent the code. 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 completed 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. A pending, abandoned, or expired verification is not complete and is not a failure. If no verification is complete, for example because the user has not entered the code yet, do not include this field. Do not include this field if you have not performed this check. + description: Whether the most recent completed verification that the end user controls this phone number was successful, using the method named in `phone_verification_method`. The value must reflect the verification state as of the time of the event. `true` if the phone verification was successful, or `false` if the user failed phone verification. A pending, abandoned, or expired verification is not complete and is not a failure. If no verification is complete, for example because the user has not entered the code yet, do not include this field. Do not include this field if you have not performed this check. postal: type: string maxLength: 255 @@ -690,10 +690,10 @@ components: description: The domain of the email address. Do not include the `@`. You do not need to send this field unless you send the email address as an MD5 hash. verification_time: $ref: '#/components/schemas/DateTime' - description: The date and time of the most recent completed verification of the email address, if known, in RFC 3339 date-time format. Use the time the verification succeeded or failed, for example the time the user clicked the link, not the time you sent the link. 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 date and time of the most recent completed verification of the email address, if known, in RFC 3339 date-time format. The value must reflect the verification state as of the time of the event. Use the time the verification succeeded or failed, for example the time the user clicked the link, not the time you sent the link. 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. was_verification_successful: type: boolean - description: Whether the most recent completed verification that the end user controls this email address was successful (e.g. by confirming a link sent to the email address). `true` if the email verification was successful, or `false` if the user failed email verification. A pending, abandoned, or expired verification is not complete and is not a failure. If no verification is complete, for example because the user has not clicked the link yet, do not include this field. Do not include this field if you have not performed this check. + description: Whether the most recent completed verification that the end user controls this email address was successful (e.g. by confirming a link sent to the email address). The value must reflect the verification state as of the time of the event. `true` if the email verification was successful, or `false` if the user failed email verification. A pending, abandoned, or expired verification is not complete and is not a failure. If no verification is complete, for example because the user has not clicked the link yet, do not include this field. Do not include this field if you have not performed this check. Event: type: object properties: diff --git a/components/minfraud-request.yaml b/components/minfraud-request.yaml index 3bfa097..4acc0b6 100644 --- a/components/minfraud-request.yaml +++ b/components/minfraud-request.yaml @@ -209,19 +209,21 @@ schemas: $ref: "#/schemas/DateTime" description: >- The date and time of the most recent completed verification of the - email address, if known, in RFC 3339 date-time format. Use the time - the verification succeeded or failed, for example the time the user - clicked the link, not the time you sent the link. 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. + email address, if known, in RFC 3339 date-time format. The value must + reflect the verification state as of the time of the event. Use the + time the verification succeeded or failed, for example the time the + user clicked the link, not the time you sent the link. 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. was_verification_successful: type: boolean description: >- Whether the most recent completed verification that the end user controls this email address was successful (e.g. by confirming a link - sent to the email address). `true` if the email verification was - successful, or `false` if the user failed email verification. A + sent to the email address). The value must reflect the verification + state as of the time of the event. `true` if the email verification + was successful, or `false` if the user failed email verification. A pending, abandoned, or expired verification is not complete and is not a failure. If no verification is complete, for example because the user has not clicked the link yet, do not include this field. Do not @@ -274,7 +276,8 @@ schemas: - other description: >- The method used for the most recent completed verification of the - phone number. Do not include this field if no verification was + phone number. The value must reflect the verification state as of the + time of the event. Do not include this field if no verification was attempted or no verification is complete. @@ -292,19 +295,21 @@ schemas: $ref: "#/schemas/DateTime" description: >- The date and time of the most recent completed verification of the - phone number, if known, in RFC 3339 date-time format. Use the time the - verification succeeded or failed, for example the time the user - entered the code, not the time you sent the code. 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 number, if known, in RFC 3339 date-time format. The value must + reflect the verification state as of the time of the event. Use the + time the verification succeeded or failed, for example the time the + user entered the code, not the time you sent the code. 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 completed 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. A + `phone_verification_method`. The value must reflect the verification + state as of the time of the event. `true` if the phone verification + was successful, or `false` if the user failed phone verification. A pending, abandoned, or expired verification is not complete and is not a failure. If no verification is complete, for example because the user has not entered the code yet, do not include this field. Do not From 9d98ec2a226c9c186eabc161add947c2a76793a7 Mon Sep 17 00:00:00 2001 From: William Storey Date: Tue, 3 Nov 2026 21:47:58 +0000 Subject: [PATCH 4/4] Leave out the verification time if there is none The time fields did not say to leave out the field when no verification was attempted. An integration that always sends a value could send a placeholder such as 1970-01-01T00:00:00Z. The web service accepts it and records a verification that did not occur. Say to leave out the time if no verification was attempted or no verification is complete. Co-Authored-By: Claude Opus 5.5 --- bundled/minfraud.yaml | 4 ++-- components/minfraud-request.yaml | 18 ++++++++++-------- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/bundled/minfraud.yaml b/bundled/minfraud.yaml index 187f121..16dba41 100644 --- a/bundled/minfraud.yaml +++ b/bundled/minfraud.yaml @@ -580,7 +580,7 @@ components: - `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: $ref: '#/components/schemas/DateTime' - description: The date and time of the most recent completed verification of the phone number, if known, in RFC 3339 date-time format. The value must reflect the verification state as of the time of the event. Use the time the verification succeeded or failed, for example the time the user entered the code, not the time you sent the code. 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 date and time of the most recent completed verification of the phone number, if known, in RFC 3339 date-time format. The value must reflect the verification state as of the time of the event. Use the time the verification succeeded or failed, for example the time the user entered the code, not the time you sent the code. Do not include this field if no verification was attempted or no verification is complete. 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 completed verification that the end user controls this phone number was successful, using the method named in `phone_verification_method`. The value must reflect the verification state as of the time of the event. `true` if the phone verification was successful, or `false` if the user failed phone verification. A pending, abandoned, or expired verification is not complete and is not a failure. If no verification is complete, for example because the user has not entered the code yet, do not include this field. Do not include this field if you have not performed this check. @@ -690,7 +690,7 @@ components: description: The domain of the email address. Do not include the `@`. You do not need to send this field unless you send the email address as an MD5 hash. verification_time: $ref: '#/components/schemas/DateTime' - description: The date and time of the most recent completed verification of the email address, if known, in RFC 3339 date-time format. The value must reflect the verification state as of the time of the event. Use the time the verification succeeded or failed, for example the time the user clicked the link, not the time you sent the link. 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 date and time of the most recent completed verification of the email address, if known, in RFC 3339 date-time format. The value must reflect the verification state as of the time of the event. Use the time the verification succeeded or failed, for example the time the user clicked the link, not the time you sent the link. Do not include this field if no verification was attempted or no verification is complete. 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. was_verification_successful: type: boolean description: Whether the most recent completed verification that the end user controls this email address was successful (e.g. by confirming a link sent to the email address). The value must reflect the verification state as of the time of the event. `true` if the email verification was successful, or `false` if the user failed email verification. A pending, abandoned, or expired verification is not complete and is not a failure. If no verification is complete, for example because the user has not clicked the link yet, do not include this field. Do not include this field if you have not performed this check. diff --git a/components/minfraud-request.yaml b/components/minfraud-request.yaml index 4acc0b6..999432e 100644 --- a/components/minfraud-request.yaml +++ b/components/minfraud-request.yaml @@ -212,10 +212,11 @@ schemas: email address, if known, in RFC 3339 date-time format. The value must reflect the verification state as of the time of the event. Use the time the verification succeeded or failed, for example the time the - user clicked the link, not the time you sent the link. 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. + user clicked the link, not the time you sent the link. Do not include + this field if no verification was attempted or no verification is + complete. 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. was_verification_successful: type: boolean description: >- @@ -298,10 +299,11 @@ schemas: phone number, if known, in RFC 3339 date-time format. The value must reflect the verification state as of the time of the event. Use the time the verification succeeded or failed, for example the time the - user entered the code, not the time you sent the code. 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. + user entered the code, not the time you sent the code. Do not include + this field if no verification was attempted or no verification is + complete. 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: >-