feat(router): Add support for Proxy api

[prasunna09]

Type of Chantge

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

Description

The Proxy allows you to use tokens with HTTP APIs without needing to access sensitive data directly within your systems. This enables solving both these problems securely while keeping your systems out of compliance scope.

proxy takes any connector request, replaces the token with payment method data from locker.
the field and its literal should be of this format - "number": "{{$card_number}}", card_number is the key stored in vault against actual card number value

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?

Create a payment method

curl --location 'http://localhost:8080/proxy' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-Profile-Id: pro_v3xtkbwrNhzIMETzrp6S' \
--header 'Authorization: api-key=dev_q4V5n3dOkwIkoQUxao26QvPI0dmd73rfvtuc8LnUkQHONmQQMCxO3eI9VgaeHUgy' \
--header 'api-key: api_key' \
--data '{
    "request_body": {
        "source": {
            "type": "card",
            "number": "{{$card_number}}",
            "expiry_month": "{{$card_exp_month}}",
            "expiry_year": "{{$card_exp_year}}",
            "billing_address": {
                "address_line1": "123 High St.",
                "address_line2": "Flat 456",
                "city": "London",
                "state": "GB",
                "zip": "SW1A 1AA",
                "country": "GB"
            }
        },
        "processing_channel_id": "pc_jx5lvimg4obe7nhoqnhptm6xoq",
        "amount": 6540,
        "currency": "USD",
        "payment_type": "Regular",
        "reference": "ORD-5023-4E89",
        "description": "Set of 3 masks",
        "capture": true,
        "capture_on": "2019-09-10T10:11:12Z",
        "billing_descriptor": {
            "name": "Withdrawal",
            "city": "London"
        },
        "shipping": {
            "address": {
                "address_line1": "Checkout.com",
                "address_line2": "Flat 456",
                "city": "London",
                "state": "GB",
                "zip": "SW1A 1AA",
                "country": "GB"
            },
            "phone": {
                "country_code": "+1",
                "number": "415 555 2671"
            }
        }
    },
    "destination_url": "https://api.sandbox.checkout.com/payments",
    "headers": {
        "Content-Type": "application/json",
        "Authorization": "checkout api key"
    },
        "token": "payment method id",
    "token_type": "payment_method_id",
    "method": "POST"

}'

response -

{
    "response": {
        "id": "pay_htbngybm5ymu7g2b63z65uy37e",
        "action_id": "act_jn52mltlalhu3f6g3u4hsqhwji",
        "amount": 6540,
        "currency": "USD",
        "approved": true,
        "status": "Authorized",
        "auth_code": "609267",
        "response_code": "10000",
        "response_summary": "Approved",
        "balances": {
            "total_authorized": 6540,
            "total_voided": 0,
            "available_to_void": 6540,
            "total_captured": 0,
            "available_to_capture": 6540,
            "total_refunded": 0,
            "available_to_refund": 0
        },
        "risk": {
            "flagged": false,
            "score": 0.0
        },
        "source": {
            "id": "src_ac7ll5fwpr7e7gjbnczoboefmm",
            "type": "card",
            "billing_address": {
                "address_line1": "123 High St.",
                "address_line2": "Flat 456",
                "city": "London",
                "state": "GB",
                "zip": "SW1A 1AA",
                "country": "GB"
            },
            "expiry_month": 12,
            "expiry_year": 2026,
            "scheme": "Visa",
            "last4": "0093",
            "fingerprint": "EEF6D525CC7C861D6AB1CEB56F9285839AE850E79BA43D7D8C06790B7A0ABD7C",
            "bin": "476136",
            "card_type": "CREDIT",
            "card_category": "CONSUMER",
            "issuer": "YES BANK, LTD.",
            "issuer_country": "IN",
            "product_id": "F",
            "product_type": "Visa Classic",
            "avs_check": "G",
            "payment_account_reference": "V001913919895558340",
            "regulated_indicator": false
        },
        "processed_on": "2025-05-19T19:15:09.1945197Z",
        "reference": "ORD-5023-4E89",
        "scheme_id": "618259364242894",
        "processing": {
            "acquirer_transaction_id": "064083903392457984441",
            "retrieval_reference_number": "368737957737",
            "merchant_category_code": "5815",
            "scheme_merchant_id": "75155",
            "scheme": "VISA",
            "aft": false,
            "pan_type_processed": "fpan",
            "cko_network_token_available": false,
            "provision_network_token": false
        },
        "expires_on": "2025-06-18T19:15:09.1945197Z",
        "_links": {
            "self": {
                "href": "https://api.sandbox.checkout.com/payments/pay_htbngybm5ymu7g2b63z65uy37e"
            },
            "actions": {
                "href": "https://api.sandbox.checkout.com/payments/pay_htbngybm5ymu7g2b63z65uy37e/actions"
            },
            "capture": {
                "href": "https://api.sandbox.checkout.com/payments/pay_htbngybm5ymu7g2b63z65uy37e/captures"
            },
            "void": {
                "href": "https://api.sandbox.checkout.com/payments/pay_htbngybm5ymu7g2b63z65uy37e/voids"
            }
        }
    },
    "status_code": 201,
    "response_headers": {
        "date": "Mon, 19 May 2025 19:15:09 GMT",
        "connection": "keep-alive",
        "content-type": "application/json; charset=utf-8",
        "content-length": "1883",
        "cko-version": "1.1045.0+e954ba003",
        "strict-transport-security": "max-age=16000000; includeSubDomains; preload;",
        "location": "https://api.sandbox.checkout.com/payments/pay_htbngybm5ymu7g2b63z65uy37e",
        "cko-request-id": "6262390c-00da-40ac-8ef8-11986b7a301a"
    }
}

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/common_utils/src/request.rs	84% smaller
crates/router/src/core/payment_methods/vault.rs	39% smaller
crates/openapi/src/openapi_v2.rs	28% smaller
api-reference-v2/api-reference/proxy/proxy.mdx	Unsupported file format
api-reference-v2/mint.json	0% smaller
api-reference-v2/openapi_spec.json	0% smaller
api-reference/openapi_spec.json	0% smaller
crates/api_models/Cargo.toml	Unsupported file format
crates/api_models/src/lib.rs	0% smaller
crates/api_models/src/proxy.rs	0% smaller
crates/api_models/src/refunds.rs	0% smaller
crates/openapi/src/routes.rs	0% smaller
crates/openapi/src/routes/proxy.rs	0% smaller
crates/router/src/core.rs	0% smaller
crates/router/src/core/proxy.rs	0% smaller
crates/router/src/core/proxy/utils.rs	0% smaller
crates/router/src/lib.rs	0% smaller
crates/router/src/routes.rs	0% smaller
crates/router/src/routes/app.rs	0% smaller
crates/router/src/routes/lock_utils.rs	0% smaller
crates/router/src/routes/proxy.rs	0% smaller
crates/router_env/src/logger/types.rs	0% smaller

[sai-harsha-vardhan]

When would we use PaymentMethodId here?

[prasunna09]

we ll be using payment method sdk to collect payment method data from customer, then will be stored in payment method table, now merchant can use payment method id for proxy

[sai-harsha-vardhan]

instead of slicing, can use get methods to avoid any kind of panics?

[sai-harsha-vardhan]

Could we try to use nom parser for multi token parsing logic as well somehow instead of manual parsing?

[prasunna09]

yeah, will be taking this multi token parsing in following pr, for now, reverted back these changes

[sai-harsha-vardhan]

This can't determine if token is present deterministically, can't be throwing error if parse_token fails