feat(payments_v2): implement create and confirm setup intent flow #7106

SanchithHegde · 2025-01-25T11:08:49Z

Type of Change

Description

This PR introduces the setup intent flow for payments v2. As of now, this PR includes a single endpoint that handles both the create intent and confirm intent steps. This is done so as to allow the payment methods v2 endpoints to create multiple-use tokens for a specified customer's payment method. The implementation mostly builds on top of payment create intent v2 and payment confirm intent v2 implementations. Note that the API contract is not finalized and is possibly subject to change.

Additional Changes

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

This PR introduces a new setup intent endpoint for payments v2.

Motivation and Context

The endpoint introduced in this PR would allow the creation of multiple-use tokens by the payments methods v2 endpoints.

How did you test it?

Using the v2 endpoints, create an organization, merchant account, profile, API key and merchant connector account.

Call the setup intent endpoint:

Since the request body is a union of the payment create intent v2 and payment confirm intent v2 request bodies, the required fields for this endpoint are amount_details, payment_method_data, payment_method_type and payment_method_subtype.

The request and response are included below:

$ curl --location 'http://localhost:8080/v2/payments' \
    --header 'x-profile-id: pro_9UhMqBMEOooRIvJFFdeW' \
    --header 'Content-Type: application/json' \
    --header 'api-key: <API key>' \
    --data '{
        "amount_details": {
            "order_amount": 0,
            "currency": "USD"
        },
        "payment_method_data": {
            "card": {
                "card_number": "4242424242424242",
                "card_exp_month": "01",
                "card_exp_year": "25",
                "card_holder_name": "John Doe",
                "card_cvc": "100"
            }
        },
        "payment_method_type": "card",
        "payment_method_subtype": "credit"
    }'
{
    "id": "12345_pay_0194aedd2b087ec1a960242f3ad8f2c1",
    "status": "succeeded",
    "amount": {
        "order_amount": 0,
        "currency": "USD",
        "shipping_cost": null,
        "order_tax_amount": null,
        "external_tax_calculation": "skip",
        "surcharge_calculation": "skip",
        "surcharge_amount": null,
        "tax_on_surcharge": null,
        "net_amount": 0,
        "amount_to_capture": null,
        "amount_capturable": 0,
        "amount_captured": 0
    },
    "customer_id": null,
    "connector": "stripe",
    "client_secret": "12345_pay_0194aedd2b087ec1a960242f3ad8f2c1_secret_0194aedd2b127f6190e5090a1527ad3e",
    "created": "2025-01-28T21:41:57.650Z",
    "payment_method_data": {
        "billing": null
    },
    "payment_method_type": "card",
    "payment_method_subtype": "credit",
    "next_action": null,
    "connector_transaction_id": "seti_1QmMXiD5R7gDAGffKPUlM0HT",
    "connector_reference_id": null,
    "connector_token_details": {
        "connector_token": "pm_1QmMXiD5R7gDAGffCf03AULQ"
    },
    "merchant_connector_id": "mca_oC8RE28uRRcVKDjgwfzG",
    "browser_info": null,
    "error": null
}

Note that the order_amount is zero in the above request. Also, note that the connector_token field is populated in the response, and the connector_transaction_id being seti_* indicates that Stripe's setup intent flow was called.
Additional fields may be passed in the request, such as customer_id, etc. which would be reflected in the response and database entries.
Passing in a non-zero value for the order_amount causes it to follow the regular create intent + confirm intent flow:

$ curl --location 'http://localhost:8080/v2/payments' \
--header 'x-profile-id: pro_9UhMqBMEOooRIvJFFdeW' \
--header 'Content-Type: application/json' \
--header 'api-key: <API key>' \
--data '{
    "amount_details": {
        "order_amount": 6540,
        "currency": "USD"
    },
    "payment_method_data": {
        "card": {
            "card_number": "4242424242424242",
            "card_exp_month": "01",
            "card_exp_year": "25",
            "card_holder_name": "John Doe",
            "card_cvc": "100"
        }
    },
    "payment_method_type": "card",
    "payment_method_subtype": "credit"
}'
{
    "id": "12345_pay_0194aedff4c57e008edc28cbd3881dee",
    "status": "succeeded",
    "amount": {
        "order_amount": 6540,
        "currency": "USD",
        "shipping_cost": null,
        "order_tax_amount": null,
        "external_tax_calculation": "skip",
        "surcharge_calculation": "skip",
        "surcharge_amount": null,
        "tax_on_surcharge": null,
        "net_amount": 6540,
        "amount_to_capture": null,
        "amount_capturable": 0,
        "amount_captured": 6540
    },
    "customer_id": null,
    "connector": "stripe",
    "client_secret": "12345_pay_0194aedff4c57e008edc28cbd3881dee_secret_0194aedff4cc719381629d4aacf19adb",
    "created": "2025-01-28T21:45:00.364Z",
    "payment_method_data": {
        "billing": null
    },
    "payment_method_type": "card",
    "payment_method_subtype": "credit",
    "next_action": null,
    "connector_transaction_id": "pi_3QmMaeD5R7gDAGff0GRZPicn",
    "connector_reference_id": null,
    "connector_token_details": {
        "connector_token": "pm_1QmMaeD5R7gDAGffZenIs1fg"
    },
    "merchant_connector_id": "mca_oC8RE28uRRcVKDjgwfzG",
    "browser_info": null,
    "error": null
}

In this case, the connector_transaction_id is pi_*, indicating that Stripe's authorize flow was called.

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

…ant` lint in `PaymentAttemptUpdate` enum

semanticdiff-com · 2025-01-25T11:08:52Z

Review changes with

Changed Files

File	Status
crates/router/src/types/api/payments.rs	77% smaller
crates/router/src/routes/app.rs	72% smaller
api-reference-v2/mint.json	67% smaller
crates/hyperswitch_domain_models/src/payments/payment_attempt.rs	51% smaller
crates/openapi/src/openapi_v2.rs	38% smaller
crates/router/src/routes/lock_utils.rs	29% smaller
crates/api_models/src/events/payment.rs	24% smaller
crates/hyperswitch_domain_models/src/router_data.rs	13% smaller
crates/router/src/core/payments/flows/setup_mandate_flow.rs	8% smaller
crates/openapi/src/routes/payment_method.rs	5% smaller
crates/openapi/src/routes/payments.rs	1% smaller
api-reference-v2/api-reference/payments/payments--create-and-confirm-intent.mdx	Unsupported file format
api-reference-v2/openapi_spec.json	Unsupported file format
crates/api_models/src/payments.rs	0% smaller
crates/diesel_models/src/payment_attempt.rs	0% smaller
crates/hyperswitch_domain_models/src/router_response_types.rs	0% smaller
crates/router/src/core/payments.rs	0% smaller
crates/router/src/core/payments/helpers.rs	0% smaller
crates/router/src/core/payments/operations/payment_response.rs	0% smaller
crates/router/src/core/payments/transformers.rs	0% smaller
crates/router/src/core/utils.rs	0% smaller
crates/router/src/routes/payments.rs	0% smaller
crates/router/src/services/api.rs	0% smaller
crates/router/src/types.rs	0% smaller
crates/router_env/src/logger/types.rs	0% smaller

SanchithHegde · 2025-01-25T11:10:33Z

crates/hyperswitch_domain_models/src/payments/payment_attempt.rs

@@ -1405,6 +1405,18 @@ impl PaymentAttemptUpdate {
    }
 }

+#[cfg(feature = "v2")]
+#[derive(Debug, Clone, Serialize)]
+pub struct ConfirmIntentResponseUpdate {


Had to move this as a separate struct because of the clippy::large_enum_variant lint being thrown.

SanchithHegde · 2025-01-25T11:12:36Z

crates/hyperswitch_domain_models/src/router_data.rs

+impl
+    TrackerPostUpdateObjects<
+        router_flow_types::SetupMandate,
+        router_request_types::SetupMandateRequestData,
+        payments::PaymentConfirmData<router_flow_types::SetupMandate>,
+    >
+    for RouterData<
+        router_flow_types::SetupMandate,
+        router_request_types::SetupMandateRequestData,
+        router_response_types::PaymentsResponseData,
+    >


This is almost entirely a copy-paste of the implementation of the Autorize flow. Didn't bother to reduce code duplication between these two implementations.

SanchithHegde · 2025-01-25T11:15:31Z

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

+impl<F: Clone> PostUpdateTracker<F, PaymentConfirmData<F>, types::SetupMandateRequestData>
+    for PaymentResponse


Again, a copy-paste of the authorize flow implementation.

SanchithHegde · 2025-01-25T11:16:33Z

crates/router/src/routes/app.rs

+                    .route(web::post().to(payments::payments_create_intent)),
+            )
+            .service(
+                web::resource("/setup-intent")


Let me know if the path needs to be changed.

SanchithHegde · 2025-01-25T11:17:44Z

crates/router/src/services/api.rs

@@ -592,7 +592,6 @@ async fn handle_response(

            match status_code {
                200..=202 | 302 | 204 => {
-                    logger::debug!(response=?response);


Removed this redundant log line, since the response is being logged (with the same key) on line 589, before the match block.

jarnura

This API is not setup-intent, it is just /payments. The term we need to use payments and not setup-intent.

crates/router/src/core/payments.rs

…sRequest` and `SetupIntentWrapperResponse` to `PaymentsResponse`

…nt()` to `payments_create_and_confirm_intent()`

…plementation on `PaymentConfirmData`

…unction

…tsConfirmIntentResponse`

…e_and_confirm_intent()`

…rder amount in `payments_create_and_confirm_intent()`

…n OpenAPI spec

…in API reference

SanchithHegde added 3 commits January 24, 2025 23:30

feat(payments_v2): implement create and confirm setup intent flow

727253a

chore: remove redundant log line in handle_response()

4ce2685

refactor(hyperswitch_domain_models): address `clippy::large_enum_vari…

67fa8f7

…ant` lint in `PaymentAttemptUpdate` enum

SanchithHegde added A-core Area: Core flows C-feature Category: Feature request or enhancement 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-payments Area: payments api-v2 labels Jan 25, 2025

SanchithHegde added this to the January 2025 Release milestone Jan 25, 2025

SanchithHegde requested review from jarnura, Narayanbhat166 and ShivanshMathurJuspay January 25, 2025 11:08

SanchithHegde self-assigned this Jan 25, 2025

SanchithHegde requested review from a team as code owners January 25, 2025 11:08

hyperswitch-bot bot removed the M-api-contract-changes Metadata: This PR involves API contract changes label Jan 25, 2025

SanchithHegde commented Jan 25, 2025

View reviewed changes

jarnura requested changes Jan 27, 2025

View reviewed changes

crates/router/src/core/payments.rs Show resolved Hide resolved

SanchithHegde added 8 commits January 27, 2025 14:57

Merge branch 'main' into setup-intent-v2

ecc7bdf

refactor(api_models): rename PaymentsSetupIntentRequest to `Payment…

8942c15

…sRequest` and `SetupIntentWrapperResponse` to `PaymentsResponse`

feat(api_models): copy over doc comments for PaymentsRequest v2 stuct

dcf5948

refactor(payments_v2): rename `payments_create_and_confirm_setup_inte…

a7469d8

…nt()` to `payments_create_and_confirm_intent()`

refactor(payments_v2): remove GenerateResponse<PaymentsResponse> im…

c49e4f5

…plementation on `PaymentConfirmData`

refactor(payments_v2): extract JSON response handling to a separate f…

1e40714

…unction

refactor(payments_v2): add connector_token_details field to `Paymen…

7e70079

…tsConfirmIntentResponse`

refactor(payments_v2): return PaymentsResponse from `payments_creat…

01d3c80

…e_and_confirm_intent()`

SanchithHegde added 4 commits January 28, 2025 19:48

refactor(payments_v2): call authorize or setup intent flow based on o…

ae04358

…rder amount in `payments_create_and_confirm_intent()`

docs(openapi): include payments_create_and_confirm_intent() route i…

267b0a5

…n OpenAPI spec

docs(mintlify): include payments_create_and_confirm_intent() route …

7c88e0f

…in API reference

Merge branch 'main' into setup-intent-v2

a5dce07

SanchithHegde requested a review from a team as a code owner January 28, 2025 21:28

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

refactor(payments_v2): remove unnecessary mutable binding of variable

2b8ca14

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(payments_v2): implement create and confirm setup intent flow #7106

feat(payments_v2): implement create and confirm setup intent flow #7106

SanchithHegde commented Jan 25, 2025 •

edited

Loading

semanticdiff-com bot commented Jan 25, 2025 •

edited

Loading

SanchithHegde Jan 25, 2025

SanchithHegde Jan 25, 2025

SanchithHegde Jan 25, 2025

SanchithHegde Jan 25, 2025

SanchithHegde Jan 25, 2025

jarnura left a comment

		impl<F: Clone> PostUpdateTracker<F, PaymentConfirmData<F>, types::SetupMandateRequestData>
		for PaymentResponse

feat(payments_v2): implement create and confirm setup intent flow #7106

Are you sure you want to change the base?

feat(payments_v2): implement create and confirm setup intent flow #7106

Conversation

SanchithHegde commented Jan 25, 2025 • edited Loading

Type of Change

Description

Additional Changes

Motivation and Context

How did you test it?

Checklist

semanticdiff-com bot commented Jan 25, 2025 • edited Loading

SanchithHegde Jan 25, 2025

Choose a reason for hiding this comment

SanchithHegde Jan 25, 2025

Choose a reason for hiding this comment

SanchithHegde Jan 25, 2025

Choose a reason for hiding this comment

SanchithHegde Jan 25, 2025

Choose a reason for hiding this comment

SanchithHegde Jan 25, 2025

Choose a reason for hiding this comment

jarnura left a comment

Choose a reason for hiding this comment

SanchithHegde commented Jan 25, 2025 •

edited

Loading

semanticdiff-com bot commented Jan 25, 2025 •

edited

Loading