feat(router): add an api to migrate the payment method

[ShankarSinghC]

Type of Change

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

Description

This is the API that will be used to migrate card details and associated data stored in another service to Hyperswitch.

How does this API differ from the existing payment method creation API?

1. It takes masked card details as input with valid first six and last four card numbers.
2. It also accepts connector_mandate_details and network_transaction_id if present.

If the masked card number is provided as input, a payment method entry is created in Hyperswitch, and no data is stored in the locker. If a valid card number is present, the card details are stored in the locker, the same as in the save card flow.

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 merchant connector account for cybersource

Test on_session saved payment

-> Crate a payment with setup_future_usage: on_session

{
    "amount": 100,
    "amount_to_capture": 100,
    "currency": "USD",
    "confirm": true,
    "capture_method": "automatic",
    "capture_on": "2022-09-10T10:11:12Z",
    "customer_id": "cu_{{$timestamp}}",
    "email": "guest@example.com",
    "name": "John Doe",
    "phone": "999999999",
    "phone_country_code": "+1",
    "description": "Its my first payment request",
    "authentication_type": "no_three_ds",
    "setup_future_usage": "on_session",
    "return_url": "http://127.0.0.1:4040",
    "customer_acceptance": {
        "acceptance_type": "offline",
        "accepted_at": "1963-05-03T04:07:52.723Z",
        "online": {
            "ip_address": "in sit",
            "user_agent": "amet irure esse"
        }
    },
    "payment_method": "card",
    "payment_method_data": {
        "card": {
            "card_number": "4242424242424242",
            "card_exp_month": "03",
            "card_exp_year": "2030",
            "card_holder_name": "joseph Doe",
            "card_cvc": "838"
        }
    },
    "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": "PiX"
        }
    },
    "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": {
        "udf1": "value1",
        "new_customer": "true",
        "login_date": "2019-09-10T10:11:12Z"
    }
}

-> Create payment with confirm false for the same customer

curl --location 'http://localhost:8080/payments' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key: dev_YsyZ2fWnqbVilsKF7TKSUd0Wuwdgf2vvxQzQVIBaCqeSGU9XRY3Pjmk9mLjNsaRm' \
--data '{
  "amount": 10000,
  "currency": "USD",
  "capture_method": "automatic",
  "authentication_type": "no_three_ds",
  "confirm": false,
  "customer_id": "cu_1720508543"
}'

-> Do payment method list with the client_secret

curl --location 'http://localhost:8080/customers/payment_methods?client_secret=pay_kGh4EiDR0G5PliuQVvcn_secret_SGva6IBvDkYjWGzkORVU' \
--header 'Accept: application/json' \
--header 'api-key: pk_dev_cad52206021b4f44932e750bb3afb1d4'

-> Confirm the payment with the payment_token

curl --location 'http://localhost:8080/payments/pay_kGh4EiDR0G5PliuQVvcn/confirm' \
--header 'api-key: pk_dev_cad52206021b4f44932e750bb3afb1d4' \
--header 'Content-Type: application/json' \
--data '{
    "payment_token": "token_8hR80yevZdbKLaW2rrY4",
    "client_secret": "pay_kGh4EiDR0G5PliuQVvcn_secret_SGva6IBvDkYjWGzkORVU",
    "payment_method": "card",
    "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"
        }
    }
}'

Test off_session saved payment

-> Create payment with setup_future_usage: off_session

{
    "amount": 100,
    "amount_to_capture": 100,
    "currency": "USD",
    "confirm": true,
    "capture_method": "automatic",
    "capture_on": "2022-09-10T10:11:12Z",
    "customer_id": "cu_{{$timestamp}}",
    "email": "guest@example.com",
    "name": "John Doe",
    "phone": "999999999",
    "phone_country_code": "+1",
    "description": "Its my first payment request",
    "authentication_type": "no_three_ds",
    "setup_future_usage": "off_session",
    "return_url": "http://127.0.0.1:4040",
    "customer_acceptance": {
        "acceptance_type": "offline",
        "accepted_at": "1963-05-03T04:07:52.723Z",
        "online": {
            "ip_address": "in sit",
            "user_agent": "amet irure esse"
        }
    },
    "payment_method": "card",
    "payment_method_data": {
        "card": {
            "card_number": "4242424242424242",
            "card_exp_month": "03",
            "card_exp_year": "2030",
            "card_holder_name": "joseph Doe",
            "card_cvc": "838"
        }
    },
    "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": "PiX"
        }
    },
    "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": {
        "udf1": "value1",
        "new_customer": "true",
        "login_date": "2019-09-10T10:11:12Z"
    }
}

-> Create a payment and payment method list with the client_secret

curl --location 'http://localhost:8080/payments' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key: dev_YsyZ2fWnqbVilsKF7TKSUd0Wuwdgf2vvxQzQVIBaCqeSGU9XRY3Pjmk9mLjNsaRm' \
--data '{
  "amount": 10000,
  "currency": "USD",
  "capture_method": "automatic",
  "authentication_type": "no_three_ds",
  "confirm": false,
  "customer_id": "cu_1720509577"
}'

curl --location 'http://localhost:8080/customers/payment_methods?client_secret=pay_4QhSPVojFUcfdK2HxncL_secret_4EwPFiS6npXTWyv9eQd9' \
--header 'Accept: application/json' \
--header 'api-key: pk_dev_cad52206021b4f44932e750bb3afb1d4'

-> Confirm the payment with token

curl --location 'http://localhost:8080/payments/pay_JuR2NJ9Xw3aOwVKBF7UL/confirm' \
--header 'api-key: pk_dev_cad52206021b4f44932e750bb3afb1d4' \
--header 'Content-Type: application/json' \
--data '{
    "payment_token": "token_aQehaaeF9Z6HSgPjCrPJ",
    "client_secret": "pay_JuR2NJ9Xw3aOwVKBF7UL_secret_k7d6s0Wqn8qcY6iNB2Ti",
    "payment_method": "card",
    "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"
        }
    }
}'

Test payment method migration api with connector mandate details

-> use the appropriate connector_mandate_id save the above payment method for a customer

curl --location 'http://localhost:8080/payment_methods/merchant_1720508278/migrate' \
--header 'api-key: test_admin' \
--header 'Content-Type: application/json' \
--data '{
    "payment_method": "card",
    "card": {
        "card_number": "424242xxxxxx4242",
        "card_exp_month": "10",
        "card_exp_year": "26",
        "nick_name": "Joh"
    },
    "customer_id": "cu_1720456680",
    "connector_mandate_details": {
        "mca_5opSKiHdcALo37nP7Gl": {
            "connector_mandate_id": "connector_mandate_id",
            "original_payment_authorized_amount": 6560,
            "original_payment_authorized_currency": "USD"
        }
    }
}
'

-> Create a payment for the customer with confirm false and perform payment

curl --location 'http://localhost:8080/payments' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key: dev_YsyZ2fWnqbVilsKF7TKSUd0Wuwdgf2vvxQzQVIBaCqeSGU9XRY3Pjmk9mLjNsaRm' \
--data '{
  "amount": 10000,
  "currency": "USD",
  "capture_method": "automatic",
  "authentication_type": "no_three_ds",
  "confirm": false,
  "setup_future_usage": "off_session",
  "customer_id": "cu_1720510734"
}'

-> Payment method list with the client secret

curl --location 'http://localhost:8080/customers/payment_methods?client_secret=pay_nVu4pFzZkJyzIpsZzogt_secret_RU1A52ZevqUfCHsnxSQo' \
--header 'Accept: application/json' \
--header 'api-key: pk_dev_cad52206021b4f44932e750bb3afb1d4'

-> Confirm the payment with the token, in this case payment will go through even without the card details as the connector mandate details are present

curl --location 'http://localhost:8080/payments/pay_nVu4pFzZkJyzIpsZzogt/confirm' \
--header 'api-key: pk_dev_cad52206021b4f44932e750bb3afb1d4' \
--header 'Content-Type: application/json' \
--data '{
    "payment_token": "token_vm9vZGkoxH2dcWUpsHou",
    "client_secret": "pay_nVu4pFzZkJyzIpsZzogt_secret_RU1A52ZevqUfCHsnxSQo",
    "payment_method": "card",
    "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"
        }
    }
}'

Test payment method migration api with network_transaction_id

curl --location 'http://localhost:8080/payment_methods/migrate' \
--header 'api-key: test_admin' \
--header 'Content-Type: application/json' \
--data '{
    "payment_method": "card",
    "merchant_id": "merchant_1720508278",
    "card": {
        "card_number": "4242424242424242",
        "card_exp_month": "10",
        "card_exp_year": "26",
        "nick_name": "Joh"
    },
    "customer_id": "cu_1720514044",
    "network_transaction_id": "network_transaction_id",
    "connector_mandate_details": {
        "mca_jqWPPZvDec4Y6KLWzgXe": {
            "connector_mandate_id": "connector_mandate_id",
            "original_payment_authorized_amount": 6560,
            "original_payment_authorized_currency": "USD"
        }
    }
}
'

-> Enable the is_connector_agnostic_mit_enabled for the business profile

curl --location 'http://localhost:8080/account/merchant_1720508278/business_profile/pro_7cMwkt3td8JW7UcwKcAq' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key: test_admin' \
--data '{
    "is_connector_agnostic_mit_enabled": true
}'

-> Create payment with confirm false

curl --location 'http://localhost:8080/payments' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key: dev_YsyZ2fWnqbVilsKF7TKSUd0Wuwdgf2vvxQzQVIBaCqeSGU9XRY3Pjmk9mLjNsaRm' \
--data '{
  "amount": 10000,
  "currency": "USD",
  "capture_method": "automatic",
  "authentication_type": "no_three_ds",
  "confirm": false,
  "setup_future_usage": "off_session",
  "customer_id": "cu_1720514044"
}'

-> list payment methods for customer

curl --location 'http://localhost:8080/customers/payment_methods?client_secret=pay_CjuYS0q3tS2huyVZdhQy_secret_AY0QHOox9y6WWeMA0Q07' \
--header 'Accept: application/json' \
--header 'api-key: pk_dev_cad52206021b4f44932e750bb3afb1d4'

-> Confirm the payment with the token

curl --location 'http://localhost:8080/payments/pay_CjuYS0q3tS2huyVZdhQy/confirm' \
--header 'api-key: pk_dev_cad52206021b4f44932e750bb3afb1d4' \
--header 'Content-Type: application/json' \
--data '{
    "payment_token": "token_a0AggkExh1ReYxueRT6n",
    "client_secret": "pay_CjuYS0q3tS2huyVZdhQy_secret_AY0QHOox9y6WWeMA0Q07",
    "payment_method": "card",
    "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"
        }
    }
}'

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

[Narayanbhat166]

update this field to appropriate value

[Narayanbhat166]

Suggested change

	.ok_or(errors::ApiErrorResponse::InvalidRequestData {
	get_required_value("card")

[Narayanbhat166]

@Aprabhat19 is it safe to remove this?

[Aprabhat19]

Yes its safe to remove

[Narayanbhat166]

this field should be mandatory during migration api

[ShankarSinghC]

this field should be mandatory during migration api

This is an internal API, and I will be creating another PR on this. I will include this mandatory field change in that upcoming PR.

[jarnura]

why we are creating client_secret here?

[ShankarSinghC]

This is change is form pr (#4134). Where in which the generated client_secret will be stored in db

[jarnura]

This is suppose to be server to server right? so client_secret is not required.

[ShankarSinghC]

Yes correct, as client secret is only required while adding a payment method through sdk it can be removed in this migration api.