feat(core): populate UCS status_code in response headers

[Aishwariyaa-Anand]

Type of Change

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

Description

This PR populates UCS status_code (connector HTTP code) in response headers.
It also introduces proxy_connector_http_status_code which when enabled, configures Hyperswitch to mirror (proxy) the connector’s HTTP status code in its own response.

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?

Enable UCS Config

curl --location 'http://localhost:8080/configs/' \
--header 'api-key: test_admin' \
--header 'x-tenant-id: public' \
--header 'Content-Type: application/json' \
--data '{
    "key": "ucs_rollout_config_{{merchant_id}}_razorpay_upi_Authorize",
    "value": "1.0"
}'

Make a payment

curl --location 'http://localhost:8080/v2/payments' \
--header 'api-key: dev_mwKUL6tWhsO8FbwWtKjNllSa7GnZutXqKsv9oLxJRv4c7l8UX9muRdsC4r9Wh2A5' \
--header 'Content-Type: application/json' \
--header 'x-profile-id: pro_cQ4q1A6oYpi89Zi7zyxW' \
--header 'Authorization: api-key=dev_mwKUL6tWhsO8FbwWtKjNllSa7GnZutXqKsv9oLxJRv4c7l8UX9muRdsC4r9Wh2A5' \
--data-raw '{
    "amount_details": {
        "order_amount": 100,
        "currency": "INR"
    },
    "capture_method":"automatic",
    "description": "Its my first payment request",
    "authentication_type": "no_three_ds",
    "return_url": "https://google.com",
    "payment_method_data": {
        "upi": {
            "upi_collect": {
                "vpa_id": "success"
            }
        },
        "billing": {
            "address": {
                "line1": "1467",
                "line2": "Harrison Street",
                "line3": "Harrison Street",
                "city": "San Fransico",
                "state": "California",
                "zip": "94122",
                "country": "IN",
                "first_name": "Swangi",
                "last_name": "Kumari"
            },
            "phone": {
                "number": "8056594427",
                "country_code": "+91"
            },
            "email": "[email protected]"
        }
    },
    "payment_method_subtype": "upi_collect",
    "payment_method_type": "upi",
    "return_raw_connector_response": true
}'

Response

{
    "id": "12345_pay_019860443e3d7f939e80e9a98effba3d",
    "status": "requires_merchant_action",
    "amount": {
        "order_amount": 100,
        "currency": "INR",
        "shipping_cost": null,
        "order_tax_amount": null,
        "external_tax_calculation": "skip",
        "surcharge_calculation": "skip",
        "surcharge_amount": null,
        "tax_on_surcharge": null,
        "net_amount": 100,
        "amount_to_capture": null,
        "amount_capturable": 0,
        "amount_captured": null
    },
    "customer_id": null,
    "connector": "razorpay",
    "created": "2025-07-31T11:35:41.885Z",
    "payment_method_data": {
        "billing": {
            "address": {
                "city": "San Fransico",
                "country": "IN",
                "line1": "1467",
                "line2": "Harrison Street",
                "line3": "Harrison Street",
                "zip": "94122",
                "state": "California",
                "first_name": "Swangi",
                "last_name": "Kumari"
            },
            "phone": {
                "number": "8056594427",
                "country_code": "+91"
            },
            "email": "[email protected]"
        }
    },
    "payment_method_type": "upi",
    "payment_method_subtype": "upi_collect",
    "connector_transaction_id": "order_QzezHblnRQM45h",
    "connector_reference_id": null,
    "merchant_connector_id": "mca_BIFmH1dr6Vh5UoYu2srb",
    "browser_info": null,
    "error": {
        "code": "BAD_REQUEST_ERROR",
        "message": "Invalid VPA. Please enter a valid Virtual Payment Address",
        "unified_code": null,
        "unified_message": null,
        "network_advice_code": null,
        "network_decline_code": null,
        "network_error_message": null
    },
    "shipping": null,
    "billing": null,
    "attempts": null,
    "connector_token_details": null,
    "payment_method_id": null,
    "next_action": null,
    "return_url": "https://google.com/",
    "authentication_type": "no_three_ds",
    "authentication_type_applied": "no_three_ds",
    "is_iframe_redirection_enabled": null,
    "merchant_reference_id": null,
    "raw_connector_response": "{\"error\":{\"code\":\"BAD_REQUEST_ERROR\",\"description\":\"Invalid VPA. Please enter a valid Virtual Payment Address\",\"source\":\"customer\",\"step\":\"payment_initiation\",\"reason\":\"invalid_vpa\",\"metadata\":{},\"field\":\"vpa\"}}",
    "feature_metadata": null
}

Verify response headers for connector_http_status_code

If proxy_connector_http_status_code is enabled
Hyperswitch resoponse status code will also be 400

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/core/payments.rs	37% smaller
crates/router/src/core/payments/transformers.rs	22% smaller
crates/router/src/core/unified_connector_service.rs	16% smaller
crates/router/src/services/api.rs	15% smaller
crates/router/src/core/unified_connector_service/transformers.rs	2% smaller
Cargo.lock	Unsupported file format
config/config.example.toml	Unsupported file format
config/deployments/env_specific.toml	Unsupported file format
config/development.toml	Unsupported file format
config/docker_compose.toml	Unsupported file format
crates/external_services/Cargo.toml	Unsupported file format
crates/router/Cargo.toml	Unsupported file format
crates/router/src/compatibility/wrap.rs	0% smaller
crates/router/src/configs/secrets_transformers.rs	0% smaller
crates/router/src/configs/settings.rs	0% smaller
crates/router/src/core/payments/flows/authorize_flow.rs	0% smaller
crates/router/src/core/payments/flows/psync_flow.rs	0% smaller
crates/router/src/core/payments/flows/setup_mandate_flow.rs	0% smaller
crates/router/src/lib.rs	0% smaller

[sai-harsha-vardhan]

We do already send connector_http_status_code in response headers, why do we need it in response payload as well? @Aishwariyaa-Anand