feat(payment-methods): override card subtype after BIN lookup #11191

kashif-m · 2026-02-09T11:48:12Z

Type of Change

Description

This PR makes below changes for payment methods modular service -

Made payment_method_subtype optional in PaymentMethodSessionConfirmRequest and PaymentMethodCreate
Applied BIN-subtype enrichment in payment method flows:
- persistent card create
- volatile card create
- proxy card create (persistent)
- session confirm

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?

1. Create payment method session

cURL

curl --location --request POST 'http://localhost:8080/v2/payment-method-sessions' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: api-key=dev_iS2grYhAG3C3uFV5pQq4aQfeRAVl5qtHN9g9VQNWL6gMiQeZON972dVeWZo23ThP' \
    --header 'X-Profile-Id: pro_Rctk2JtsBN7asWvUvR1C' \
    --data '{
    "customer_id": "12345_cus_019c421f985178438322e00ebdac4b30",
    "return_url": "https://example.com/return"
    }'

Response

{"id":"12345_pms_019c4234181e7f839449da20aaaae7e2","customer_id":"12345_cus_019c421f985178438322e00ebdac4b30","billing":null,"psp_tokenization":null,"network_tokenization":null,"tokenization_data":null,"expires_at":"2026-02-09T11:55:36.255Z","client_secret":"cs_019c4234181f7dd18300b7270cc752e7","return_url":"https://example.com/return","next_action":null,"authentication_details":null,"associated_payment_methods":null,"associated_token_id":null,"storage_type":null,"card_cvc_token_storage":null}

2. Confirm payment method session without card subtype

cURL

curl --location --request POST 'http://localhost:8080/v2/payment-method-sessions/12345_pms_019c422bcb6f74c2b3009cc5c139502b/confirm' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: publishable-key=pk_dev_b3304c1547914c4eb134a6666a46851c,client-secret=cs_019c4234181f7dd18300b7270cc752e7' \
    --header 'X-Profile-Id: pro_Rctk2JtsBN7asWvUvR1C' \
    --data '{
    "payment_method_type": "card",
    "payment_method_data": {
        "card": {
        "card_number": "4242424242424242",
        "card_exp_month": "12",
        "card_exp_year": "30",
        "card_holder_name": "John Test",
        "card_cvc": "123"
        }
    }
    }'

Response

{"id":"12345_pms_019c4234181e7f839449da20aaaae7e2","customer_id":"12345_cus_019c421f985178438322e00ebdac4b30","billing":null,"psp_tokenization":null,"network_tokenization":null,"tokenization_data":null,"expires_at":"2026-02-09T11:55:36.255Z","client_secret":"CLIENT_SECRET_REDACTED","return_url":"https://example.com/return","next_action":null,"authentication_details":null,"associated_payment_methods":[{"payment_method_token":{"type":"payment_method_session_token","data":"token_5YgyIHtoFwDQBOKOSzt7"}}],"associated_token_id":null,"storage_type":null,"card_cvc_token_storage":{"is_stored":true,"expires_at":"2026-02-09T11:55:51.901Z"}}

3. Get details for the token

cURL

curl --location --request GET 'http://localhost:8080/v2/payment-methods/token/token_5YgyIHtoFwDQBOKOSzt7/details' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: api-key=dev_iS2grYhAG3C3uFV5pQq4aQfeRAVl5qtHN9g9VQNWL6gMiQeZON972dVeWZo23ThP' \
    --header 'X-Profile-Id: pro_Rctk2JtsBN7asWvUvR1C' \
    --data '{
    "payment_method_type": "card",
    "payment_method_data": {
        "card": {
        "card_number": "4242424242424242",
        "card_exp_month": "11",
        "card_exp_year": "31",
        "card_holder_name": "John Test",
        "card_cvc": "123"
        }
    }
    }'

Response

{
    "id": "12345_pm_019c423454f6727282c79db9caae1554",
    "payment_method_token": "token_5YgyIHtoFwDQBOKOSzt7"
}

4. Retrieve PM

cURL

curl --location --request GET 'http://localhost:8080/v2/payment-methods/12345_pm_019c423454f6727282c79db9caae1554' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: api-key=dev_iS2grYhAG3C3uFV5pQq4aQfeRAVl5qtHN9g9VQNWL6gMiQeZON972dVeWZo23ThP' \
    --header 'X-Profile-Id: pro_Rctk2JtsBN7asWvUvR1C' \
    --data '{
    "payment_method_type": "card",
    "payment_method_data": {
        "card": {
        "card_number": "4242424242424242",
        "card_exp_month": "11",
        "card_exp_year": "31",
        "card_holder_name": "John Test",
        "card_cvc": "123"
        }
    }
    }'

Response

{"id":"12345_pm_019c423454f6727282c79db9caae1554","merchant_id":"acme_retail_FHnPnZIScDdRwUReUuiE","customer_id":"12345_cus_019c421f985178438322e00ebdac4b30","payment_method_type":"card","payment_method_subtype":"credit","recurring_enabled":false,"created":"2026-02-09T11:40:51.830Z","last_used_at":"2026-02-09T11:40:51.830Z","payment_method_data":{"card":{"issuer_country":null,"last4_digits":"4242","expiry_month":"11","expiry_year":"31","card_holder_name":"John Test","card_fingerprint":null,"nick_name":null,"card_network":"Visa","card_isin":null,"card_issuer":"STRIPE PAYMENTS UK LIMITED","card_type":null,"saved_to_locker":true}},"connector_tokens":null,"network_token":null,"storage_type":"persistent","card_cvc_token_storage":{"is_stored":true,"expires_at":"2026-02-09T11:55:51.697Z"},"network_transaction_id":null,"raw_payment_method_data":null}

5. Create persistent PM (without card subtype or wrong subtype)

cURL

curl --location --request POST 'http://localhost:8080/v2/payment-methods' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: api-key=dev_iS2grYhAG3C3uFV5pQq4aQfeRAVl5qtHN9g9VQNWL6gMiQeZON972dVeWZo23ThP' \
    --header 'X-Profile-Id: pro_Rctk2JtsBN7asWvUvR1C' \
    --data '{
        "payment_method_type": "card",
        "customer_id": "12345_cus_019c421f985178438322e00ebdac4b30",
        "payment_method_data": {
        "card": {
            "card_number": "4242424242424242",
            "card_exp_month": "11",
            "card_exp_year": "35",
            "card_holder_name": "John Test",
            "card_cvc": "123"
        }
        },
        "storage_type": "persistent"
    }'

Response

{"id":"12345_pm_019c4b3b76537900afcf2ae2a95b74b3","merchant_id":"acme_retail_FHnPnZIScDdRwUReUuiE","customer_id":"12345_cus_019c421f985178438322e00ebdac4b30","payment_method_type":"card","payment_method_subtype":"credit","recurring_enabled":false,"created":"2026-02-11T05:45:14.067Z","last_used_at":"2026-02-11T05:45:14.067Z","payment_method_data":{"card":{"issuer_country":null,"last4_digits":"4242","expiry_month":"11","expiry_year":"35","card_holder_name":"John Test","card_fingerprint":null,"nick_name":null,"card_network":"Visa","card_isin":null,"card_issuer":"STRIPE PAYMENTS UK LIMITED","card_type":null,"saved_to_locker":true}},"connector_tokens":null,"network_token":null,"storage_type":"persistent","card_cvc_token_storage":{"is_stored":true,"expires_at":"2026-02-11T06:00:14.099Z"},"network_transaction_id":null,"raw_payment_method_data":null}

6. Create volatile PM (without card subtype or wrong subtype)

cURL

curl --location --request POST 'http://localhost:8080/v2/payment-methods' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: api-key=dev_iS2grYhAG3C3uFV5pQq4aQfeRAVl5qtHN9g9VQNWL6gMiQeZON972dVeWZo23ThP' \
    --header 'X-Profile-Id: pro_Rctk2JtsBN7asWvUvR1C' \
    --data '{
        "payment_method_type": "card",
        "customer_id": "12345_cus_019c421f985178438322e00ebdac4b30",
        "payment_method_data": {
        "card": {
            "card_number": "4242424242424242",
            "card_exp_month": "11",
            "card_exp_year": "39",
            "card_holder_name": "John Test",
            "card_cvc": "123"
        }
        },
        "storage_type": "volatile"
    }'

Response

{"id":"12345_pm_019c4b3cf14a7651a5fef71de4d300eb","merchant_id":"acme_retail_FHnPnZIScDdRwUReUuiE","customer_id":"12345_cus_019c421f985178438322e00ebdac4b30","payment_method_type":"card","payment_method_subtype":"credit","recurring_enabled":false,"created":"2026-02-11T05:46:51.086Z","last_used_at":"2026-02-11T05:46:51.086Z","payment_method_data":{"card":{"issuer_country":null,"last4_digits":"4242","expiry_month":"11","expiry_year":"39","card_holder_name":"John Test","card_fingerprint":null,"nick_name":null,"card_network":"Visa","card_isin":null,"card_issuer":"STRIPE PAYMENTS UK LIMITED","card_type":null,"saved_to_locker":true}},"connector_tokens":null,"network_token":null,"storage_type":"volatile","card_cvc_token_storage":{"is_stored":true,"expires_at":"2026-02-11T06:01:51.089Z"},"network_transaction_id":null,"raw_payment_method_data":null}

7. Create proxy PM (persistent)

cURL

curl --location --request POST 'http://localhost:8080/v2/payment-methods' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: api-key=dev_iS2grYhAG3C3uFV5pQq4aQfeRAVl5qtHN9g9VQNWL6gMiQeZON972dVeWZo23ThP' \
    --header 'X-Profile-Id: pro_Rctk2JtsBN7asWvUvR1C' \
    --data '{
        "payment_method_type": "card",
        "customer_id": "12345_cus_019c421f985178438322e00ebdac4b30",
        "payment_method_data": {
        "proxy_card": {
            "card_number": "tok_card_abc123",
            "card_exp_month": "11",
            "card_exp_year": "31",
            "bin_number": "424242",
            "last_four": "4242",
            "card_holder_name": "John Test",
            "card_cvc": "123"
        }
        },
        "storage_type": "persistent"
    }'

Response

{"id":"12345_pm_019c4b3fabf77581bd407744f69e9dcc","merchant_id":"acme_retail_FHnPnZIScDdRwUReUuiE","customer_id":"12345_cus_019c421f985178438322e00ebdac4b30","payment_method_type":"card","payment_method_subtype":"credit","recurring_enabled":false,"created":"2026-02-11T05:49:49.945Z","last_used_at":"2026-02-11T05:49:49.945Z","payment_method_data":{"card":{"issuer_country":null,"last4_digits":"4242","expiry_month":"11","expiry_year":"31","card_holder_name":"John Test","card_fingerprint":null,"nick_name":null,"card_network":"Visa","card_isin":"424242","card_issuer":"STRIPE PAYMENTS UK LIMITED","card_type":"CREDIT","saved_to_locker":false}},"connector_tokens":null,"network_token":null,"storage_type":"persistent","card_cvc_token_storage":null,"network_transaction_id":null,"raw_payment_method_data":null}

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 · 2026-02-09T11:48:15Z

Review changes with

Changed Files

File	Status
crates/router/src/core/payments/operations/external_vault_proxy_payment_intent.rs	96% smaller
crates/router/src/core/payments/operations/payment_confirm_intent.rs	96% smaller
crates/api_models/src/payment_methods.rs	67% smaller
api-reference/v2/openapi_spec_v2.json	49% smaller
crates/router/src/core/payment_methods.rs	44% smaller
crates/router/src/types/api/payment_methods.rs	26% smaller

crates/router/src/core/payment_methods.rs

…reate and session flows

…irm request

kashif-m self-assigned this Feb 9, 2026

kashif-m requested a review from a team as a code owner February 9, 2026 11:48

hyperswitch-bot bot requested a review from a team as a code owner February 9, 2026 12:09

hyperswitch-bot bot added the M-api-contract-changes Metadata: This PR involves API contract changes label Feb 9, 2026

ShankarSinghC reviewed Feb 9, 2026

View reviewed changes

crates/router/src/core/payment_methods.rs Outdated Show resolved Hide resolved

kashif-m added the S-test-ready Status: This PR is ready for cypress-tests label Feb 10, 2026

feat(payment-methods): override card subtype after BIN lookup in PM c…

b19a4fb

…reate and session flows

kashif-m force-pushed the feat-pm-session-bin-lookup-override branch from fd5ed6b to b19a4fb Compare February 11, 2026 05:53

kashif-m requested a review from a team as a code owner February 11, 2026 05:53

hyperswitch-bot bot added M-api-contract-changes Metadata: This PR involves API contract changes and removed M-api-contract-changes Metadata: This PR involves API contract changes labels Feb 11, 2026

chore(payment-methods): add pm subtype validation for PM session conf…

7bd7a47

…irm request

kashif-m force-pushed the feat-pm-session-bin-lookup-override branch from da1b6af to 7bd7a47 Compare February 11, 2026 06:06

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(payment-methods): override card subtype after BIN lookup #11191

feat(payment-methods): override card subtype after BIN lookup #11191

Uh oh!

kashif-m commented Feb 9, 2026 •

edited

Loading

Uh oh!

semanticdiff-com bot commented Feb 9, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat(payment-methods): override card subtype after BIN lookup #11191

Are you sure you want to change the base?

feat(payment-methods): override card subtype after BIN lookup #11191

Uh oh!

Conversation

kashif-m commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Type of Change

Description

Additional Changes

Motivation and Context

How did you test it?

Checklist

Uh oh!

semanticdiff-com bot commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kashif-m commented Feb 9, 2026 •

edited

Loading

semanticdiff-com bot commented Feb 9, 2026 •

edited

Loading