feat(router): add pre-confirm payments eligibility api

[sai-harsha-vardhan]

Type of Change

• Bugfix
• New feature
• Enhancement
• Refactoring
• Dependency updates
• Documentation
• CI/CD

Description

Payments Eligibility API

This PR introduces the Payments Eligibility API, which is invoked by the SDK after the payment method data filled event. The API pre-processes the submitted payment method data to determine the appropriate next action and checks eligibility based on various parameters.

As part of this change, blocklist checks have been added to the eligibility flow to ensure that ineligible or restricted payment methods are identified early in the process.

Additional Changes

• This PR modifies the API contract
• This PR modifies the database schema
• This PR modifies application configuration/environment variables

Motivation and Context

How did you test it?

Tested Manually

1. Create a blocklist rule for a card_bin (424242)
   CURL

curl --location '{{BASE_URL}}/blocklist' \
--header 'Content-Type: application/json' \
--header 'api-key: {{API_KEY}}' \
--data '{
    "type": "card_bin",
    "data": "424242"
}'

Response

{
    "fingerprint_id": "424242",
    "data_kind": "card_bin",
    "created_at": "2025-10-09T13:52:38.914Z"
}

2. Call the Eligibility API with blocklisted bin to see next_action being Deny in the response
   CURL

curl --location '{{BASE_URL}}/payments/{{PAYMENT_ID}}/eligibility' \
--header 'Content-Type: application/json' \
--header 'api-key: {{PUBLISHABLE_KEY}}' \
--data '{
    "client_secret": "pay_UvTqxnVPNNChhe1vKk1W_secret_AF9avGOwxxvcwqHhmYv0",
    "payment_method_type": "card",
    "payment_method_data": {
        "card": {
            "card_number": "4242424242424242",
            "card_exp_month": "01",
            "card_exp_year": "2050",
            "card_holder_name": "John Smith",
            "card_cvc": "349",
            "card_network": "Visa"
        },
        "billing": {
            "address": {
                "line1": "1467",
                "line2": "Harrison Street",
                "line3": "Harrison Street",
                "city": "San Fransico",
                "state": "CA",
                "zip": "94122",
                "country": "US",
                "first_name": "John",
                "last_name": "Doe"
            },
            "phone": {
                "number": "8056594427",
                "country_code": "+91"
            }
        }
    }
}'

Response

{
    "payment_id": "pay_UvTqxnVPNNChhe1vKk1W",
    "sdk_next_action": {
        "next_action": {
            "deny": {
                "message": "Card number is blocklisted"
            }
        }
    }
}

3. Call the Eligibility API with non-blocklisted bin to see next_action being Confirm in the response
   CURL

curl --location '{{BASE_URL}}/payments/{{PAYMENT_ID}}/eligibility' \
--header 'Content-Type: application/json' \
--header 'api-key: {{PUBLISHABLE_KEY}}' \
--data '{
    "client_secret": "pay_UvTqxnVPNNChhe1vKk1W_secret_AF9avGOwxxvcwqHhmYv0",
    "payment_method_type": "card",
    "payment_method_data": {
        "card": {
            "card_number": "411111111111111",
            "card_exp_month": "01",
            "card_exp_year": "2050",
            "card_holder_name": "John Smith",
            "card_cvc": "349",
            "card_network": "Visa"
        },
        "billing": {
            "address": {
                "line1": "1467",
                "line2": "Harrison Street",
                "line3": "Harrison Street",
                "city": "San Fransico",
                "state": "CA",
                "zip": "94122",
                "country": "US",
                "first_name": "John",
                "last_name": "Doe"
            },
            "phone": {
                "number": "8056594427",
                "country_code": "+91"
            }
        }
    }
}'

Response

{
    "payment_id": "pay_UvTqxnVPNNChhe1vKk1W",
    "sdk_next_action": {
        "next_action": "confirm"
    }
}

Checklist

• I formatted the code cargo +nightly fmt --all
• I addressed lints thrown by cargo clippy
• I reviewed the submitted code
• I added unit tests for my changes where possible

[semanticdiff-com]

Review changes with  

Changed Files

File	Status
crates/router/src/types/api/payments.rs	98% smaller
crates/router/src/routes/lock_utils.rs	83% smaller
crates/router/src/core/blocklist/utils.rs	64% smaller
crates/api_models/src/payments.rs	17% smaller
crates/router/src/routes/app.rs	17% smaller
api-reference/v1/openapi_spec_v1.json	7% smaller
api-reference/v2/openapi_spec_v2.json	4% smaller
crates/api_models/src/events/payment.rs	0% smaller
crates/router/src/core/payments.rs	0% smaller
crates/router/src/routes/payments.rs	0% smaller
crates/router/src/services/authentication.rs	0% smaller
crates/router_env/src/logger/types.rs	0% smaller

[jarnura]

Why we are adding serde skip and include payment_id field? The path only contains this field and not the payload. Remove this field

[jarnura]

How EligibilityCheck is polymorphic?

[jarnura]

Use function name respective to domain, these functions represents some kind of framework representation but there is no actual framework around this.