feat(recovery): add support for custom billing api for v2 #8838

srujanchikke · 2025-08-05T08:44:42Z

Type of Change

Description

Revenue recovery incoming webhook flow handles events from external 3rd party subscription provider, If merchant has inhouse subscription solution and wants to use revenue recovery, /payments/recovery will consume the events same as incoming webhooks.

Flow :

Merchant can integrate with /payments/recovery endpoint and sends failed payments to recovery system.
recovery core will schedule the payments in process tracker.

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 payment mca :

curl --location 'http://localhost:8080/v2/connector-accounts' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-merchant-id: cloth_seller_j08ByNifXf1Q9nMHaBN6' \
--header 'x-profile-id: pro_QfvcZDEn9OJaUyLTL6Z4' \
--header 'Authorization: admin-api-key=test_admin' \
--data '{
    "connector_type": "payment_processor",
    "connector_name": "worldpayvantiv",
    "connector_account_details": {
        "auth_type": "SignatureKey",
        "api_key": "apikey",
        "key1": "key1",
        "api_secret": "secret"
    },
    "payment_methods_enabled": [
        {
            "payment_method_type": "card",
            "payment_method_subtypes": [
                {
                    "payment_method_subtype": "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
                },
                {
                    "payment_method_subtype": "debit",
                    "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
                }
            ]
        }
    ],
    "frm_configs": null,
    "connector_webhook_details": {
        "merchant_secret": ""
    },
    "metadata": {
        "report_group": "Hello",
        "merchant_config_currency": "USD"
    },
    "profile_id": "pro_QfvcZDEn9OJaUyLTL6Z4"
}'

create custom billing mca :

curl --location 'http://localhost:8080/v2/connector-accounts' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-merchant-id: cloth_seller_NjzUfz0ALVkqI8BOBP0P' \
--header 'x-profile-id: pro_HfHD4qr1QNDUSHwMyytb' \
--header 'Authorization: admin-api-key=test_admin' \
--header 'api-key: ••••••' \
--data '{
    "connector_type": "billing_processor",
    "connector_name": "custombilling",
    "connector_account_details": {
        "auth_type": "NoKey"
    },
    "feature_metadata" : {
        "revenue_recovery" : {
            "max_retry_count" : 9,
            "billing_connector_retry_threshold" : 2,
            "billing_account_reference" :{
                "mca_oc9cwYX0KTkSy76ZscY2" : "mca_oc9cwYX0KTkSy76ZscY2"
            },
            "switch_payment_method_config" : {
                "retry_threshold" : 5,
                "time_threshold_after_creation": 1
            }
        }
    },
    "profile_id": "pro_HfHD4qr1QNDUSHwMyytb"
}'

Update the profile revenue_recovery_retry_algorithm_type to cascading.

Create revenue recovery

curl --location 'http://localhost:8080/v2/payments/recovery' \
--header 'Authorization: api-key=dev_VWOtZtmJoPKjnhD9evLcDDbL6CRTI5oSrVZ6EqMTbDflaWFKJY1gapwrEYouiva4' \
--header 'x-profile-id: pro_a8uCk5nzKhOXxnm68UCv' \
--header 'x-merchant-id: cloth_seller_vMdpVbUDQDxrDB04KB6L' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount_details": {
        "order_amount": 100,
        "currency": "USD"
    },
    "merchant_reference_id": "merchant_reference_id_20jgfdh19asasd",
    "billing_merchant_connector_id" : "mca_5rHage7LWP2yB2BdNZRO",
    "payment_merchant_connector_id": "mca_86nTDgqPCM8EPXPNkzvh",
    "error": {
        "code": "card_declined",
        "message": "Your card was declined.",
        "network_advice_code": null,
        "network_decline_code": "01",
        "network_error_message": "generic_decline"
    },
    "billing": {
        "address": {
            "first_name": "John",
            "last_name": "Dough"
        },
        "email": "[email protected]"
    },
    "attempt_status": "failure",
    "payment_method_type": "card",
    "payment_method_sub_type": "credit",
    "transaction_created_at": "2025-06-20T10:11:12Z",
    "connector_customer_id": "cus_0001",
    "connector_transaction_id": "connector_transaction_id",
    "primary_processor_payment_method_token": "2541911049890008",
    "action": "schedule_failed_payment",
    "billing_started_at": "2025-07-31T10:11:12Z",
    "payment_method_units": {
        "2541911049890008": {
            "card": {
                "expiry_month": "06",
                "expiry_year": "50",
                "last_four_digits": "0008",
                "card_issuer": "Chase",
                "card_network" :"visa"
            }
        }
    }
}'

response status indicates intent is failed (Success response)

{
    "id": "12345_pay_019883e1dc4971228aa378ab75b738f7",
    "intent_status": "failed",
}

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-08-05T08:44:45Z

Review changes with

Changed Files

File	Status
crates/router/src/routes/lock_utils.rs	84% smaller
crates/hyperswitch_connectors/src/connectors/custombilling.rs	36% smaller
crates/router/src/core/webhooks/recovery_incoming.rs	29% smaller
crates/router/src/routes/app.rs	15% smaller
crates/hyperswitch_connectors/src/connectors/custombilling/transformers.rs	1% smaller
crates/api_models/src/events/payment.rs	0% smaller
crates/api_models/src/payments.rs	0% smaller
crates/common_types/src/payments.rs	0% smaller
crates/hyperswitch_domain_models/src/revenue_recovery.rs	0% smaller
crates/router/src/core/revenue_recovery/api.rs	0% smaller
crates/router/src/core/revenue_recovery/transformers.rs	0% smaller
crates/router/src/core/webhooks/incoming_v2.rs	0% smaller
crates/router/src/routes/payments.rs	0% smaller
crates/router/src/types/api/payments.rs	0% smaller
crates/router_env/src/logger/types.rs	0% smaller

Aprabhat19 · 2025-08-07T07:59:20Z

crates/api_models/src/payments.rs

+    pub status: enums::AttemptStatus,
+
+    /// The billing details of the payment attempt. This address will be used for invoicing.
+    pub billing: Option<Address>,


Can you improve the naming

Aprabhat19 · 2025-08-07T08:00:41Z

crates/api_models/src/payments.rs

+    pub payment_method_units: CustomBillingPaymentMethodDataWithBilling,
+
+    /// recovery action
+    pub action: common_payments_types::RecoveryAction,


Can you give a descriptive comment

jagan-jaya · 2025-08-07T13:40:44Z

crates/api_models/src/payments.rs

@@ -4318,6 +4335,12 @@ pub struct PaymentMethodDataResponseWithBilling {
    pub billing: Option<Address>,
 }

+#[derive(Debug, Clone, Eq, PartialEq, serde::Deserialize, ToSchema, serde::Serialize)]
+pub struct CustomBillingPaymentMethodDataWithBilling {


Suggested change

pub struct CustomBillingPaymentMethodDataWithBilling {

pub struct CustomRecoveryPaymentMethodData {

jagan-jaya · 2025-08-07T13:42:41Z

crates/api_models/src/payments.rs

+    )]
+    pub id: id_type::GlobalPaymentId,
+
+    #[schema(value_type = IntentStatus, example = "failed", default = "requires_confirmation")]


add merchant_reference_id in the response to correlate between their input and our response

jagan-jaya · 2025-08-07T13:43:49Z

crates/api_models/src/payments.rs

+
+    /// primary payment method token at payment processor end.
+    #[schema(value_type = String, example = "token_1234")]
+    pub primary_processor_payment_method_token: String,


Suggested change

pub primary_processor_payment_method_token: String,

pub primary_processor_payment_method_token: Secret<String>,

jagan-jaya · 2025-08-07T13:44:01Z

crates/api_models/src/payments.rs

+
+    /// customer id at payment connector for which mandate is attached.
+    #[schema(value_type = String, example = "cust_12345")]
+    pub connector_customer_id: String,


Suggested change

pub connector_customer_id: String,

pub connector_customer_id: Secret<String>,

jagan-jaya · 2025-08-07T13:44:13Z

crates/api_models/src/payments.rs

+    pub billing_started_at: Option<PrimitiveDateTime>,
+
+    /// Transaction if reference at payment connector end.
+    pub connector_transaction_id: Option<String>,


Suggested change

pub connector_transaction_id: Option<String>,

pub connector_transaction_id: Option<Secret<String>>,

jagan-jaya · 2025-08-07T13:54:13Z

crates/router/src/core/revenue_recovery/transformers.rs

+            retry_count: None,
+            next_billing_at: None,


Suggested change

retry_count: None,

next_billing_at: None,

retry_count: None,

next_billing_at: None,

can these be provided from api input? or it will not be allowed always in request?

It will be not allowed in request, it would always be calculated in recovery system with attempt count.

jagan-jaya · 2025-08-07T13:55:15Z

crates/router/src/core/webhooks/recovery_incoming.rs

+    > {
+        let primary_token = &data.primary_processor_payment_method_token.to_string();
+        let card_info = data.payment_method_units.units.get(primary_token);
+        let recovery_attempt = Self(revenue_recovery::RevenueRecoveryAttemptData {


Suggested change

let recovery_attempt = Self(revenue_recovery::RevenueRecoveryAttemptData {

let recovery_attempt = Self(revenue_recovery::RevenueRecoveryAttemptData::from(data)

jagan-jaya · 2025-08-07T13:55:59Z

crates/router/src/core/webhooks/recovery_incoming.rs

@@ -906,7 +967,8 @@ impl RevenueRecoveryAttempt {
        .change_context(errors::RevenueRecoveryError::ProcessTrackerCreationError)
        .attach_printable("Failed to construct process tracker entry")?;

-        db.insert_process(process_tracker_entry)
+        let tracker = db


Suggested change

let tracker = db

db

remove if not needed

jagan-jaya · 2025-08-07T13:56:55Z

crates/router/src/core/webhooks/recovery_incoming.rs

+        ),
+    ) -> CustomResult<webhooks::WebhookResponseTracker, errors::RevenueRecoveryError> {
+        match self.action {
+            common_types::payments::RecoveryAction::CancelInvoice => todo!(),


is this intentional?

Yes, we need to implment stop flow, which will alter process tracker flow.

jagan-jaya · 2025-08-07T13:58:45Z

crates/router/src/core/webhooks/recovery_incoming.rs

+                }
+            }
+            common_types::payments::RecoveryAction::SuccessPaymentExternal => {
+                router_env::logger::info!("Payment has been succeeded via external system");


Suggested change

router_env::logger::info!("Payment has been succeeded via external system");

logger::info!("Payment has been succeeded via external system");

change here and in below places also

hrithikesh026 · 2025-08-08T06:41:44Z

crates/api_models/src/payments.rs

+    #[serde(default, with = "common_utils::custom_serde::iso8601::option")]
+    pub billing_started_at: Option<PrimitiveDateTime>,
+
+    /// Transaction if reference at payment connector end.


This sentence is not clear

hrithikesh026 · 2025-08-08T06:44:31Z

crates/api_models/src/payments.rs

+    pub payment_merchant_connector_id: id_type::MerchantConnectorAccountId,
+
+    #[schema(value_type = AttemptStatus, example = "charged")]
+    pub status: enums::AttemptStatus,


status in response type is IntentStatus. Here it is AttemptStatus.

Yes, We depend on transaction status for external payment, But want to share intent status in response.

hrithikesh026 · 2025-08-08T06:48:37Z

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

@@ -267,6 +267,14 @@ pub async fn construct_payment_router_data_for_authorize<'a>(
        .and_then(|customer| customer.email.clone())
        .map(pii::Email::from);

+    let additional_payment_method_data: Option<api_models::payments::AdditionalPaymentData> =


Where is this additional_payment_method_data being used?

add custombilling api

c822b82

srujanchikke self-assigned this Aug 5, 2025

srujanchikke changed the title ~~feat(recovery): add support for custom billing api~~ feat(recovery): add support for custom billing api for v2 Aug 5, 2025

srujanchikke added C-feature Category: Feature request or enhancement api-v2 labels Aug 5, 2025

Chikke Srujan and others added 5 commits August 5, 2025 14:27

Merge branch 'main' into custombillingapi

0b6a480

chore: run formatter

dd981de

minor fix

bc57109

chore: run formatter

c1254ed

fix v1 clippy

f5d3cd6

srujanchikke marked this pull request as ready for review August 7, 2025 05:09

srujanchikke requested review from a team as code owners August 7, 2025 05:09

hyperswitch-bot bot and others added 5 commits August 7, 2025 05:09

chore: run formatter

9528eae

minor fix

d5a00c7

clippy fix

c5addb8

chore: run formatter

41ac4bc

resolve comments

2e503db

srujanchikke requested a review from a team as a code owner August 7, 2025 08:02

Chikke Srujan added 2 commits August 7, 2025 14:08

remove v2 config

04ace8a

clippy fix

1d8b4c2

Aprabhat19 reviewed Aug 7, 2025

View reviewed changes

Chikke Srujan and others added 2 commits August 7, 2025 15:38

resolve comments

a5b822e

Merge branch 'main' into custombillingapi

d810db5

jagan-jaya requested changes Aug 7, 2025

View reviewed changes

Chikke Srujan added 2 commits August 7, 2025 21:11

resolve comments

0cafafd

clippy fix

4bce737

jagan-jaya previously approved these changes Aug 7, 2025

View reviewed changes

AkshayaFoiger previously approved these changes Aug 7, 2025

View reviewed changes

tsdk02 previously approved these changes Aug 7, 2025

View reviewed changes

Aprabhat19 previously approved these changes Aug 7, 2025

View reviewed changes

hrithikesh026 reviewed Aug 8, 2025

View reviewed changes

resolve comments

975cba7

srujanchikke dismissed stale reviews from Aprabhat19, tsdk02, AkshayaFoiger, and jagan-jaya via 975cba7 August 8, 2025 07:03

hyperswitch-bot bot and others added 3 commits August 8, 2025 07:04

chore: run formatter

4c45b22

resolve comments

1de5de9

Merge branch 'main' into custombillingapi

f4476a5

hrithikesh026 approved these changes Aug 8, 2025

View reviewed changes

tsdk02 approved these changes Aug 8, 2025

View reviewed changes

AkshayaFoiger approved these changes Aug 8, 2025

View reviewed changes

likhinbopanna enabled auto-merge August 8, 2025 09:14

likhinbopanna added this pull request to the merge queue Aug 8, 2025

Merged via the queue into main with commit 9e8df84 Aug 8, 2025
21 of 26 checks passed

likhinbopanna deleted the custombillingapi branch August 8, 2025 09:52

srujanchikke mentioned this pull request Aug 10, 2025

fix(revenue_recovery): Populate payment method data in record attempt flow for V2 #8886

Open

14 tasks

	pub struct CustomBillingPaymentMethodDataWithBilling {
	pub struct CustomRecoveryPaymentMethodData {

	pub primary_processor_payment_method_token: String,
	pub primary_processor_payment_method_token: Secret<String>,

	pub connector_customer_id: String,
	pub connector_customer_id: Secret<String>,

	pub connector_transaction_id: Option<String>,
	pub connector_transaction_id: Option<Secret<String>>,

	let recovery_attempt = Self(revenue_recovery::RevenueRecoveryAttemptData {
	let recovery_attempt = Self(revenue_recovery::RevenueRecoveryAttemptData::from(data)

	router_env::logger::info!("Payment has been succeeded via external system");
	logger::info!("Payment has been succeeded via external system");

feat(recovery): add support for custom billing api for v2 #8838

feat(recovery): add support for custom billing api for v2 #8838

Uh oh!

Conversation

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

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

srujanchikke commented Aug 5, 2025 •

edited

Loading

semanticdiff-com bot commented Aug 5, 2025 •

edited

Loading