feat(router): Add external vault support in v1 payments flow #9274

prasunna09 · 2025-09-04T07:51:01Z

Type of Change

Description

Add external vault support in v1 payments flow.
Currently we only save card in hs-card-vault
Added new support to save card in external vault based merchant-profile configuration.

Changes in code -
During First CIT (fresh card for a customer c1 - setup future usage - on_session with customer acceptance)

based on profile level config, vault is decided, vault creds are fetched from MCA. payment method data is stored in respective vault.
During Repeat CIT (Saved card for a customer c1 - payment token for c1)
based on pm entry - vault type, and vault mca id, if external, mca creds are fetched, if internal, default flow.

DB changes -
In business profile in api level & db level-

is_external_vault_enabled: Option<bool>, //Indicates if external vault is enabled or not.
external_vault_connector_details: Option<ExternalVaultConnectorDetails>,// holds the active External Vault Connector Details

In Payment method table in db level (diesel model) -

pub external_vault_source: Option<common_utils::id_type::MerchantConnectorAccountId>, //holds the mca of external vault with which payment method data has been stored
pub vault_type: Option<storage_enums::VaultType>, //enum variant whether it is ext vault or internal vault

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 Vault Connector MCA (Eg - VGS)

curl --location 'http://localhost:8080/account/merchant_1758632854/connectors' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key: dev_jN7RVfxJgyz3GB7OASKFved09yY2lA17xEJSBbj47tBN03inP9rCADUooCF5Ozz6' \
--data '{
    "connector_type": "vault_processor",
    "connector_name": "vgs",
    "connector_account_details": {
        "auth_type": "SignatureKey",
        "api_key": "api key",
        "key1": "key 1",
        "api_secret": "api_secret"
    },
    "test_mode": true,
    "disabled": false,
    "business_country": "US",
    "business_label": "default",
    "payment_methods_enabled": [
    ],
    "metadata": {
        "endpoint_prefix": "ghjg",
        "google_pay": {
            "allowed_payment_methods": [
                {
                    "type": "CARD",
                    "parameters": {
                        "allowed_auth_methods": [
                            "PAN_ONLY",
                            "CRYPTOGRAM_3DS"
                        ],
                        "allowed_card_networks": [
                            "AMEX",
                            "DISCOVER",
                            "INTERAC",
                            "JCB",
                            "MASTERCARD",
                            "VISA"
                        ]
                    },
                    "tokenization_specification": {
                        "type": "PAYMENT_GATEWAY"
                    }
                }
            ],
            "merchant_info": {
                "merchant_name": "Narayan Bhat"
            }
        }
    },
     "connector_webhook_details": {
        "merchant_secret": "7091687210DF6DCA38B2E670B3D68EB53516A26CA85590E29024FFBD7CD23980"
    },
    "profile_id":"pro_KH7MujUjH2miLhfzGlAB"
}'

Update Profile with below config to enable external vault

"is_external_vault_enabled": "enable",
    "external_vault_connector_details": {
        "vault_connector_id": "mca_lRJXlrSQ557zrIJUalxK"
    }

Create payment with customer acceptance, and setup_future_usage - on_session/off_session

curl --location 'http://localhost:8080/payments' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key:api key' \
--data-raw '
{
    "amount": 1000,
    "currency": "USD",
    "confirm": true,
    "capture_method": "automatic",
    "capture_on": "2022-09-10T10:11:12Z",
    
    "customer_id": "cu_1758488194",
    "email": "[email protected]",
    "name": "John Doe",
    "phone": "999999999",
    "phone_country_code": "+65",
    "description": "Its my first payment request",
    "authentication_type": "no_three_ds",
    "return_url": "https://google.com",
"payment_method": "card",
    "payment_method_type": "credit",
    "payment_method_data": {
        "card": {
            "card_number": "card_number",
            "card_exp_month": "03",
            "card_exp_year": "2030",
            "card_holder_name": "joseph Doe",
            "card_cvc": "737"
        }
    },

    "billing": {
        "address": {
            "line1": "1467",
            "line2": "Harrison Street",
            "line3": "Harrison Street",
            "city": "San Fransico",
            "state": "California",
            "zip": "94122",
            "country": "US",
            "first_name": "PiX",
            "last_name": "ss"
        }
    },
    "shipping": {
        "address": {
            "line1": "1467",
            "line2": "Harrison Street",
            "line3": "Harrison Street",
            "city": "San Fransico",
            "state": "California",
            "zip": "94122",
            "country": "US",
            "first_name": "John",
            "last_name": "Doe"
        },
        "phone": {
            "number": "8056594427",
            "country_code": "+91"
        }
    },
    "browser_info": {
        "user_agent": "Mozilla\/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/70.0.3538.110 Safari\/537.36",
        "accept_header": "text\/html,application\/xhtml+xml,application\/xml;q=0.9,image\/webp,image\/apng,*\/*;q=0.8",
        "language": "nl-NL",
        "color_depth": 24,
        "screen_height": 723,
        "screen_width": 1536,
        "time_zone": 0,
        "java_enabled": true,
        "java_script_enabled": true,
        "ip_address": "125.0.0.1"
    },
    "statement_descriptor_name": "joseph",
    "statement_descriptor_suffix": "JS",
    "metadata": {},
    "order_details": [
        {
            "product_name": "Apple iphone 15",
            "quantity": 1,
            "amount": 0,
            "account_name": "transaction_processing"
        }
    ],
    "profile_id": "pro_KH7MujUjH2miLhfzGlAB"
}'

Payment method should be saved with
external_vault_source - mca_lRJXlrSQ557zrIJUalxK (VGS mca id)
vault_type - external

If VGS is not enabled, then
external_vault_source -
vault_type - internal

make repeat CIT

Please note, test backward compatibility
how to -make a payment with existing customer's saved payment method

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 · 2025-09-04T07:51:04Z

Review changes with

Changed Files

File	Status
crates/router/src/types/api/connector_mapping.rs	88% smaller
crates/router/src/core/utils.rs	49% smaller
crates/hyperswitch_domain_models/src/business_profile.rs	45% smaller
crates/hyperswitch_domain_models/src/payment_methods.rs	34% smaller
crates/router/src/core/payment_methods.rs	30% smaller
crates/diesel_models/src/schema_v2.rs	22% smaller
crates/router/src/core/payment_methods/vault.rs	14% smaller
crates/diesel_models/src/business_profile.rs	13% smaller
crates/openapi/src/openapi.rs	7% smaller
crates/router/src/core/payments/tokenization.rs	1% smaller
crates/router/src/core/admin.rs	1% smaller
api-reference/v1/openapi_spec_v1.json	0% smaller
crates/api_models/src/admin.rs	0% smaller
crates/api_models/src/payment_methods.rs	0% smaller
crates/common_enums/src/enums.rs	0% smaller
crates/diesel_models/src/payment_method.rs	0% smaller
crates/diesel_models/src/schema.rs	0% smaller
crates/hyperswitch_domain_models/src/merchant_connector_account.rs	0% smaller
crates/hyperswitch_domain_models/src/payment_method_data.rs	0% smaller
crates/payment_methods/src/controller.rs	0% smaller
crates/payment_methods/src/core/migration/payment_methods.rs	0% smaller
crates/router/src/core/errors/utils.rs	0% smaller
crates/router/src/core/payment_methods/cards.rs	0% smaller
crates/router/src/core/payment_methods/tokenize/card_executor.rs	0% smaller
crates/router/src/core/payments/helpers.rs	0% smaller
crates/router/src/core/payments/vault_session.rs	Unsupported file format
crates/router/src/core/payouts/helpers.rs	0% smaller
crates/router/src/core/pm_auth.rs	0% smaller
crates/router/src/db/events.rs	0% smaller
crates/router/src/types/api/admin.rs	0% smaller
crates/router/src/types/domain.rs	0% smaller
crates/router/src/types/payment_methods.rs	0% smaller
migrations/2025-09-20-190742_add_external_vault_source_in_payment_method_and_is_external_vault_enabled_in_profile/down.sql	Unsupported file format
migrations/2025-09-20-190742_add_external_vault_source_in_payment_method_and_is_external_vault_enabled_in_profile/up.sql	Unsupported file format

…tch into add-external-vault-in-v1

crates/router/src/core/payments/helpers.rs

crates/router/src/core/payments/tokenization.rs

crates/router/src/core/payment_methods.rs

crates/router/src/types/payment_methods.rs

Sakilmostak · 2025-09-09T07:58:29Z

migrations/2025-09-20-195624_add_is_external_vault_enabled_in_profile/up.sql

+-- Your SQL goes here
+ALTER TABLE business_profile
+ADD COLUMN IF NOT EXISTS is_external_vault_enabled BOOLEAN;
+
+ALTER TABLE business_profile 
+ADD COLUMN IF NOT EXISTS external_vault_connector_details JSONB;


we already have same migrations present in v2_compatible_migrations, instead of multiple instances is it possible to have a common migration between both @hrithikesh026

yes, we already have v2.
but for v1 schema, v2_compatible_migrations wont be running. so its required to write under v1 migrations.
@sai-harsha-vardhan could you please help here

Sakilmostak

LGTM!

crates/router/src/core/utils.rs

crates/api_models/src/admin.rs

crates/hyperswitch_domain_models/src/business_profile.rs

…tch into add-external-vault-in-v1

jarnura · 2025-09-22T11:30:10Z

crates/router/src/core/payments/helpers.rs

+
+    let key_manager_state = &state.into();
+
+    let merchant_connector_account_details = state


We need to abstract these out, we can do this later, normally itself bad to read these static data deeper in the floe

jarnura · 2025-09-22T11:31:13Z

v2_migrations/2025-09-22-105510_remove_vault_type_in_payment_methods/down.sql

@@ -0,0 +1,2 @@
+-- This file should undo anything in `up.sql`
+ALTER TABLE payment_methods ADD COLUMN IF NOT EXISTS vault_type VARCHAR(16);


this can be more like 64, can you merge query to single up and down sql files

…tch into add-external-vault-in-v1

Co-authored-by: hyperswitch-bot[bot] <148525504+hyperswitch-bot[bot]@users.noreply.github.com>

prasunna09 added 3 commits September 3, 2025 14:43

add external support in v1

e072798

code refactoring

4a97332

add external support in v1

2e410e4

prasunna09 self-assigned this Sep 4, 2025

prasunna09 requested review from a team as code owners September 4, 2025 07:51

hyperswitch-bot bot added the M-database-changes Metadata: This PR involves database schema changes label Sep 4, 2025

hyperswitch-bot bot and others added 8 commits September 4, 2025 07:51

chore: run formatter

105c1c2

code refactoring

56ebe5d

Merge branch 'add-external-vault-in-v1' of github.com:juspay/hyperswi…

f89c4a2

…tch into add-external-vault-in-v1

chore: run formatter

f32d7e7

code refactoring

06157dd

Merge branch 'add-external-vault-in-v1' of github.com:juspay/hyperswi…

5a7af20

…tch into add-external-vault-in-v1

fix clippy for v1 and v2

d4ae747

fix import

f759367

Sakilmostak requested changes Sep 9, 2025

View reviewed changes

resolve pr comments

0ff686b

AkshayaFoiger previously approved these changes Sep 15, 2025

View reviewed changes

Sakilmostak reviewed Sep 15, 2025

View reviewed changes

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

resolve pr comments

f05116e

prasunna09 dismissed AkshayaFoiger’s stale review via f05116e September 16, 2025 06:52

Merge branch 'main' into add-external-vault-in-v1

0c9981a

Sakilmostak previously approved these changes Sep 16, 2025

View reviewed changes

chore: run formatter

c4ab147

hyperswitch-bot bot dismissed Sakilmostak’s stale review via c4ab147 September 16, 2025 09:25

AkshayaFoiger previously approved these changes Sep 16, 2025

View reviewed changes

jarnura requested changes Sep 19, 2025

View reviewed changes

crates/api_models/src/admin.rs Outdated Show resolved Hide resolved

crates/hyperswitch_domain_models/src/business_profile.rs Outdated Show resolved Hide resolved

prasunna09 added 2 commits September 22, 2025 16:35

fix v2 migrations

d35f47c

Merge branch 'add-external-vault-in-v1' of github.com:juspay/hyperswi…

f8a40bd

…tch into add-external-vault-in-v1

jarnura requested changes Sep 22, 2025

View reviewed changes

chore: run formatter

546a951

prasunna09 mentioned this pull request Sep 22, 2025

feat(connector): [Tokenex]Add external vault insert and retrieve flows #9470

Merged

14 tasks

prasunna09 and others added 6 commits September 22, 2025 19:28

resolve pr comments

dccfa33

code refactoring

67f4f81

fix clippy

e9396f8

chore: run formatter

89b8ef1

fix clippy

25e6da2

Merge branch 'add-external-vault-in-v1' of github.com:juspay/hyperswi…

f1761c8

…tch into add-external-vault-in-v1

jarnura previously approved these changes Sep 22, 2025

View reviewed changes

fix open api spec file

582af76

prasunna09 dismissed jarnura’s stale review via 582af76 September 22, 2025 20:28

prasunna09 linked an issue Sep 22, 2025 that may be closed by this pull request

[FEATURE] Add external vault support in v1 #9500

Closed

prasunna09 and others added 5 commits September 23, 2025 02:12

fix open api spec file

065c00d

fix open spec api

e42c83a

fix open api spec

7e93355

fix open api spec file

fccde44

docs(openapi): re-generate OpenAPI specification

4b052a7

hyperswitch-bot bot added the M-api-contract-changes Metadata: This PR involves API contract changes label Sep 23, 2025

Sakilmostak approved these changes Sep 23, 2025

View reviewed changes

AkshayaFoiger approved these changes Sep 23, 2025

View reviewed changes

jarnura approved these changes Sep 23, 2025

View reviewed changes

bernard-eugine added this pull request to the merge queue Sep 23, 2025

Merged via the queue into main with commit e410af2 Sep 23, 2025
21 of 25 checks passed

bernard-eugine deleted the add-external-vault-in-v1 branch September 23, 2025 07:20

prasunna09 mentioned this pull request Sep 25, 2025

fix(connector): [Tokenex] fix tokenize flow response handling for tokenex #9528

Merged

14 tasks

srujanchikke pushed a commit that referenced this pull request Sep 29, 2025

feat(router): Add external vault support in v1 payments flow (#9274)

1a24787

Co-authored-by: hyperswitch-bot[bot] <148525504+hyperswitch-bot[bot]@users.noreply.github.com>


		let key_manager_state = &state.into();

		let merchant_connector_account_details = state

		@@ -0,0 +1,2 @@
		-- This file should undo anything in `up.sql`
		ALTER TABLE payment_methods ADD COLUMN IF NOT EXISTS vault_type VARCHAR(16); No newline at end of file

feat(router): Add external vault support in v1 payments flow #9274

feat(router): Add external vault support in v1 payments flow #9274

Uh oh!

Conversation

prasunna09 commented Sep 4, 2025 • 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 Sep 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Sakilmostak Sep 9, 2025

Choose a reason for hiding this comment

Uh oh!

prasunna09 Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

Sakilmostak left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jarnura Sep 22, 2025

Choose a reason for hiding this comment

Uh oh!

jarnura Sep 22, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

prasunna09 commented Sep 4, 2025 •

edited

Loading

semanticdiff-com bot commented Sep 4, 2025 •

edited

Loading