feat(mandates): allow off-session payments using `payment_method_id` #4132

Chethan-rao · 2024-03-19T12:12:06Z

Type of Change

Description

When a mandate is created on connector's end, we store the connector mandate details in our payment methods table. Now in order to make recurring payment with this, we basically have to do a token based payment where set the setup_future_usage = off_session and we list the payment methods of a customer and make a payment with payment token. But we should also allow off-session payments using payment method id without having to list customer payment methods. For this, we accept off_session = true and payment method id in the request and make a recurring mandate payment.

Additional Changes

This PR modifies the API contract
This PR modifies the database schema
This PR modifies application configuration/environment variables

Api contract changes -
Added new field in PaymentsRequest:

"recurring_details": {
      "type": "payment_method_id/mandate_id",
      "data": "String"
},

Motivation and Context

How did you test it?

mca creation -

curl --location 'https://localhost:8080/account/merchant_1710841026/connectors' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key: test_admin' \
--data '{
    "connector_type": "fiz_operations",
    "business_country": "US",
    "business_label": "default",
    "connector_name": "cybersource",
    "connector_account_details": {
        "auth_type": "SignatureKey",
        "api_key": "abc",
        "api_secret": "xyz",
        "key1": "key"
    },
    "test_mode": true,
    "disabled": false,
    "payment_methods_enabled": [
        {
            "payment_method": "card",
            "payment_method_types": [
                {
                    "payment_method_type": "credit",
                    "payment_experience": null,
                    "card_networks": [
                        "Visa",
                        "Mastercard"
                    ],
                    "accepted_currencies": null,
                    "accepted_countries": null,
                    "minimum_amount": 1,
                    "maximum_amount": 68607706,
                    "recurring_enabled": true,
                    "installment_payment_enabled": true
                }
            ]
        }
    ],
    "connector_webhook_details": {
        "merchant_secret": "Xavior"
    }
}'

Setup mandate on connector's end

curl --location 'https://localhost:8080/payments' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key: abc' \
--data-raw '{
    "amount": 0,
    "currency": "USD",
    "confirm": true,
    "profile_id": "pro_ByhEgJFlWSahAgSqaUZl",
    "capture_method": "automatic",
    "customer_id": "mandate_customer1",
    "email": "[email protected]",
    "setup_future_usage": "off_session",
    "customer_acceptance": {
        "acceptance_type": "online"
    },
    "payment_method": "card",
    "payment_method_type": "credit",
    "payment_method_data": {
        "card": {
            "card_number": "4242424242424242",
            "card_exp_month": "03",
            "card_exp_year": "2030",
            "card_holder_name": "Test Holder",
            "card_cvc": "737"
        }
    },
    "payment_type": "setup_mandate",
    "billing": {
        "address": {
            "city": "test",
            "country": "US",
            "line1": "here",
            "line2": "there",
            "line3": "anywhere",
            "zip": "560095",
            "state": "Washington",
            "first_name": "One",
            "last_name": "Two"
        },
        "phone": {
            "number": "1234567890",
            "country_code": "+1"
        },
        "email": "[email protected]"
    },
    "authentication_type": "no_three_ds"
}'

db entry -

Recurring payment using payment_method_id

curl --location 'https://localhost:8080/payments' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key: abc' \
--data-raw '{
    "amount": 499,
    "currency": "USD",
    "confirm": true,
    "profile_id": "pro_ByhEgJFlWSahAgSqaUZl",
    "capture_method": "automatic",
    "customer_id": "mandate_customer1",
    "email": "[email protected]",
    "off_session": true,
    "recurring_details": {
        "type": "payment_method_id",
        "data": "pm_lmTnIO5EdCiiMgRPrV9x"
    },
    "payment_method": "card",
    "billing": {
        "address": {
            "city": "test",
            "country": "US",
            "line1": "here",
            "line2": "there",
            "line3": "anywhere",
            "zip": "560095",
            "state": "Washington",
            "first_name": "One",
            "last_name": "Two"
        },
        "phone": {
            "number": "1234567890",
            "country_code": "+1"
        },
        "email": "[email protected]"
    },
    "authentication_type": "no_three_ds"
}'

Payment succeded -

Also try creating mandate on hyperswitch end by providing mandate_data in setup mandate request and get the mandate_id. Do the recurring payment with mandate_id. Also try another recurring payment with below structure

    "recurring_details": {
        "type": "mandate_id",
        "data": "xyz"
    }

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
I added a CHANGELOG entry if applicable

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

vspecky · 2024-03-20T09:08:19Z

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

+    req.recurring_details
+        .check_value_present("recurring_details")?;


we need to check mandate_id also right? One of the two should be given.

recurring_details is of type RecurringDetails in which during from conversion itself, I'm mapping the mandate_id to RecurringDetails::MandateId or else take the request.recurring_details

impl From<&PaymentsRequest> for MandateValidationFields { fn from(req: &PaymentsRequest) -> Self { let recurring_details = req .mandate_id .clone() .map(RecurringDetails::MandateId) .or(req.recurring_details.clone()); Self { recurring_details, confirm: req.confirm, customer_id: req .customer .as_ref() .map(|customer_details| &customer_details.id) .or(req.customer_id.as_ref()) .map(ToOwned::to_owned), mandate_data: req.mandate_data.clone(), setup_future_usage: req.setup_future_usage, off_session: req.off_session, } } }

vspecky · 2024-03-20T09:09:03Z

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

@@ -1949,7 +2010,8 @@ pub(crate) fn validate_payment_method_fields_present(
    utils::when(
        req.payment_method.is_some()
            && req.payment_method_data.is_none()
-            && req.payment_token.is_none(),
+            && req.payment_token.is_none()
+            && req.recurring_details.is_none(),


Why is this required?

Now that i'm getting the payment_method from payment_method_info itself instead of relying on the request as suggested by you, we can remove this

vspecky · 2024-03-20T09:09:59Z

crates/router/src/core/payments/operations/payment_complete_authorize.rs

@@ -247,6 +249,14 @@ impl<F: Send + Clone, Ctx: PaymentMethodRetrieve>
                id: profile_id.to_string(),
            })?;

+        let recurring_details = request


Why are we ignoring MandateId here?

because in PaymentsRequest, we have both mandate_id: Option<String> and recurring_details: Option<String> where recurring_details is mapped to payment method id

vspecky · 2024-03-20T09:11:16Z

crates/router/src/core/payments.rs

@@ -2263,6 +2263,7 @@ where
    pub authorizations: Vec<diesel_models::authorization::Authorization>,
    pub authentication: Option<storage::Authentication>,
    pub frm_metadata: Option<serde_json::Value>,
+    pub recurring_details: Option<String>,


It's better if this is the enum itself. With a String, we won't know later on in the flow whether it's a recurring mandate or a recurring MIT payment.

jagan-jaya · 2024-03-26T12:12:04Z

openapi/openapi_spec.json

+      "RecurringDetails": {
+        "oneOf": [
+          {
+            "type": "object",
+            "required": [
+              "type",
+              "data"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "mandate_id"
+                ]
+              },
+              "data": {
+                "type": "string"
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": [
+              "type",
+              "data"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "payment_method_id"
+                ]
+              },
+              "data": {
+                "type": "string"
+              }
+            }
+          }
+        ],
+        "discriminator": {
+          "propertyName": "type"
+        }
+      },


Suggested change

"RecurringDetails": {

"oneOf": [

{

"type": "object",

"required": [

"type",

"data"

],

"properties": {

"type": {

"type": "string",

"enum": [

"mandate_id"

]

},

"data": {

"type": "string"

}

}

},

{

"type": "object",

"required": [

"type",

"data"

],

"properties": {

"type": {

"type": "string",

"enum": [

"payment_method_id"

]

},

"data": {

"type": "string"

}

}

}

],

"discriminator": {

"propertyName": "type"

}

},

"RecurringDetails": {

"type": "object",

"required": [

"type",

"data"

],

"properties": {

"type": {

"type": "string",

"enum": [

"mandate_id",

"payment_method_id"

]

},

"data": {

"type": "string"

}

},

"discriminator": {

"propertyName": "type"

}

}

I hope the testing for recurring payment with mandate_id in root level and payment_token is done already

currently we are providing support to pass mandate_id inside recurring_details. So it has to be one of mandate_id or payment_method_id. Later we'll deprecate the mandate_id field in root level.

I hope the testing for recurring payment with mandate_id in root level and payment_token is done already

yes

* 'main' of github.com:juspay/hyperswitch: refactor(core): removed the processing status for payment_method_status (#4213) docs(README): remove link to outdated early access form build(deps): bump `error-stack` from version `0.3.1` to `0.4.1` (#4188) chore(version): 2024.04.01.0 feat(mandates): allow off-session payments using `payment_method_id` (#4132) ci(CI-pr): determine modified crates more deterministically (#4233) chore(config): add billwerk base URL in deployment configs (#4243) feat(payment_method): API to list countries and currencies supported by a country and payment method type (#4126) chore(version): 2024.03.28.0 refactor(config): allow wildcard origin for development and Docker Compose setups (#4231) fix(core): Amount capturable remain same for `processing` status in capture (#4229) fix(euclid_wasm): checkout wasm metadata issue (#4198) fix(trustpay): [Trustpay] Add error code mapping '800.100.100' (#4224) feat(connector): [billwerk] add connector template code (#4123) fix(connectors): fix wallet token deserialization error (#4133) fix(log): adding span metadata to `tokio` spawned futures (#4118) chore(version): 2024.03.27.0 fix(connector): [CRYPTOPAY] Skip metadata serialization if none (#4205) fix(connector): [Trustpay] fix deserialization error for incoming webhook response for trustpay and add error code mapping '800.100.203' (#4199) fix(core): make eci in AuthenticationData optional (#4187)

feat(mandates): allow off-session payments using payment_method_id

2cdd3d7

Chethan-rao added S-waiting-on-review Status: This PR has been implemented and needs to be reviewed M-api-contract-changes Metadata: This PR involves API contract changes A-mandates Area: Mandate Flows labels Mar 19, 2024

Chethan-rao added this to the March 2024 milestone Mar 19, 2024

Chethan-rao self-assigned this Mar 19, 2024

Chethan-rao requested review from a team as code owners March 19, 2024 12:12

Chethan-rao linked an issue Mar 19, 2024 that may be closed by this pull request

Allow off-session payments using Payment Method ID (only with API Key auth) #3814

Closed

chore: run formatter

690be75

Chethan-rao force-pushed the off-session-payments-with-pmid branch from f0a52a9 to 690be75 Compare March 19, 2024 12:14

update openapi spec

4b3dcad

Chethan-rao requested a review from vspecky March 19, 2024 12:40

vspecky requested changes Mar 20, 2024

View reviewed changes

address requested changes

c323aef

Chethan-rao requested review from vspecky and jagan-jaya March 20, 2024 12:40

jagan-jaya reviewed Mar 26, 2024

View reviewed changes

Chethan-rao requested a review from jagan-jaya March 26, 2024 13:48

jagan-jaya approved these changes Mar 27, 2024

View reviewed changes

vspecky approved these changes Mar 27, 2024

View reviewed changes

Merge branch 'main' into off-session-payments-with-pmid

c29c704

pixincreate added this pull request to the merge queue Mar 28, 2024

pixincreate removed the S-waiting-on-review Status: This PR has been implemented and needs to be reviewed label Mar 28, 2024

Merged via the queue into main with commit 7b337ac Mar 28, 2024
10 of 12 checks passed

pixincreate deleted the off-session-payments-with-pmid branch March 28, 2024 12:57

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(mandates): allow off-session payments using `payment_method_id` #4132

feat(mandates): allow off-session payments using `payment_method_id` #4132

Chethan-rao commented Mar 19, 2024 •

edited

Loading

vspecky Mar 20, 2024

Chethan-rao Mar 20, 2024 •

edited

Loading

vspecky Mar 20, 2024

Chethan-rao Mar 20, 2024 •

edited

Loading

vspecky Mar 20, 2024

Chethan-rao Mar 20, 2024

vspecky Mar 20, 2024

jagan-jaya Mar 26, 2024

jagan-jaya Mar 26, 2024

Chethan-rao Mar 26, 2024 •

edited

Loading

		req.recurring_details
		.check_value_present("recurring_details")?;

feat(mandates): allow off-session payments using payment_method_id #4132

feat(mandates): allow off-session payments using payment_method_id #4132

Conversation

Chethan-rao commented Mar 19, 2024 • edited Loading

Type of Change

Description

Additional Changes

Motivation and Context

How did you test it?

Checklist

vspecky Mar 20, 2024

Choose a reason for hiding this comment

Chethan-rao Mar 20, 2024 • edited Loading

Choose a reason for hiding this comment

vspecky Mar 20, 2024

Choose a reason for hiding this comment

Chethan-rao Mar 20, 2024 • edited Loading

Choose a reason for hiding this comment

vspecky Mar 20, 2024

Choose a reason for hiding this comment

Chethan-rao Mar 20, 2024

Choose a reason for hiding this comment

vspecky Mar 20, 2024

Choose a reason for hiding this comment

jagan-jaya Mar 26, 2024

Choose a reason for hiding this comment

jagan-jaya Mar 26, 2024

Choose a reason for hiding this comment

Chethan-rao Mar 26, 2024 • edited Loading

Choose a reason for hiding this comment

feat(mandates): allow off-session payments using `payment_method_id` #4132

feat(mandates): allow off-session payments using `payment_method_id` #4132

Chethan-rao commented Mar 19, 2024 •

edited

Loading

Chethan-rao Mar 20, 2024 •

edited

Loading

Chethan-rao Mar 20, 2024 •

edited

Loading

Chethan-rao Mar 26, 2024 •

edited

Loading