feat(core): add network error related columns in payment attempt [v2]

[srujanchikke]

Type of Change

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

Description

Currently error related information is stored in payment attempt as :
error_code,error_message, error_reason in payment attempt table, apart from this we have unified_code and unified_message which are hyperswitch error codes and error messages mapped to PG error codes and messages(Static).
We need to store network error relation info as well for passive churn product.

Why does passive churn require network error relation info ?
Card network share knowledge on whether failed payments should be retried or not. Errors like Insufficient funds and Donot honor can be retried after sometime with limited no of retries. PG error codes can be only used for immediate retries not async retries.

What is the expected format across multiple connectors ?

Stripe - Stripe shares network adivice code and network decline code. source

• Network advice code: a 2 digit code which indicates the advice returned by the network on how to proceed with an error.
• Network decline code : a brand specific 2, 3, or 4 digit code which indicates the reason the authorization failed.

Adyen -

• The Merchant Advice Code (MAC) can be returned for both approved and refused Mastercard payments. This code provides additional information about the type of transaction or the reason why the payment failed. If the payment failed, the MAC gives guidance on if and when you can retry the payment.
• refusalReasonRaw: the full raw response. For example: 51 : Insufficient funds/over credit limit.
  refusalCodeRaw (only available for Visa and Mastercard transactions through our own acquiring platform): the numeric part of the raw response. For example: 51. This represents the underlying scenario that caused the transaction to fail.

Note: This fields are populated in prod based on request with adyen team.

Cybersource & Bank of america -

• processorInformation.merchantAdvice.codeRaw (source)
• processorInformation.responseCode (source).

Globalpay -
payment method result & code : source

Worldpay -
Refusal response code and refusal advice code source

Why this information should not be stored in existing columns ?

Existing columns already have different purpose like displaying them to customer/shoppers, smart retires etc .
The raw response provides additional information about why the transaction failed. Be aware that card schemes and issuers sometimes change the text without notice.To prevent the malicious use of data, you must not expose the details of raw responses to shoppers.

How should we store it in our DB ?
Create new columns in our DB

Column	type	description
network_decline_code	Nullable String<16>	a brand specific 2, 3, or 4 digit code which indicates the reason the authorization failed.
network_advice_code	Nullable String <16>	a 2 digit code which indicates the advice returned by the network on how to proceed with an error.
network_error_message	Nullable String	network message propagated by payment gateway

Note : We will try to consume this fields in 3 scenarios for internal payments(payments created by HS),

1. Authorize response handling
2. Psync response handling
3. Webhook response handling.

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?

Payment gateway's don't provide raw network response in sandbox. this won't break any connector flow since this fields are made option. I have tested it via adyen. adyen gives network error message but not code.
Payments confirm :

{
    "payment_method_data": {
        "card": {
            "card_number": "4242424242424242",
            "card_exp_month": "01",
            "card_exp_year": "27",
            "card_holder_name": "John Doe",
            "card_cvc": "100"
        }
    },
    "payment_method_type": "card",
    "payment_method_subtype": "credit",
    "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": "127.0.0.1"
    }
}

response :

{
    "id": "12345_pay_0195fa92a80f7e31b6853d04099bf5b3",
    "status": "failed",
    "amount": {
        "order_amount": 100,
        "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": 100,
        "amount_to_capture": null,
        "amount_capturable": 0,
        "amount_captured": 0
    },
    "customer_id": null,
    "connector": "adyen",
    "client_secret": "12345_pay_0195fa92a80f7e31b6853d04099bf5b3_secret_0195fa92a83f7bf3a30570f8644789ed",
    "created": "2025-04-03T07:34:30.208Z",
    "payment_method_data": {
        "billing": null
    },
    "payment_method_type": "card",
    "payment_method_subtype": "credit",
    "connector_transaction_id": "T6PKGMQJ7S7ZBMV5",
    "connector_reference_id": null,
    "merchant_connector_id": "mca_RuRHRipbbBiFX8vmwxh2",
    "browser_info": null,
    "error": {
        "code": "2",
        "message": "Refused",
        "unified_code": null,
        "unified_message": null,
        "network_advice_code": null,
        "network_decline_code": null,
        "network_error_message": "DECLINED Expiry Incorrect"
    },
    "shipping": null,
    "billing": null,
    "attempts": null,
    "connector_token_details": null,
    "payment_method_id": null,
    "next_action": null,
    "return_url": "https://google.com/success",
    "authentication_type": "no_three_ds",
    "authentication_type_applied": "no_three_ds"
}

Note: This will not effect v1 implementations and payments response. In v1 equivalent fields are issuer error code and issuer error message.

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]

Review changes with  

Changed Files

File	Status
crates/hyperswitch_connectors/src/connectors/bamboraapac.rs	59% smaller
crates/hyperswitch_connectors/src/connectors/cashtocode/transformers.rs	59% smaller
crates/hyperswitch_connectors/src/connectors/noon.rs	59% smaller
crates/hyperswitch_connectors/src/connectors/payme.rs	59% smaller
crates/hyperswitch_connectors/src/connectors/rapyd.rs	59% smaller
crates/router/src/connector/threedsecureio.rs	59% smaller
crates/router/src/core/payments/access_token.rs	59% smaller
crates/router/src/core/payouts/access_token.rs	59% smaller
crates/hyperswitch_connectors/src/connectors/billwerk/transformers.rs	57% smaller
crates/hyperswitch_connectors/src/connectors/cryptopay/transformers.rs	57% smaller
crates/hyperswitch_connectors/src/utils.rs	57% smaller
crates/router/src/utils.rs	57% smaller
crates/hyperswitch_connectors/src/connectors/aci.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/airwallex.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/amazonpay.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/bambora.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/billwerk.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/bitpay.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/cashtocode.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/chargebee.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/checkout.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/coinbase.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/coingate.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/cryptopay.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/digitalvirgo.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/dlocal.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/facilitapay.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/fiuu.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/forte.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/getnet.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/globepay.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/gocardless.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/helcim.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/hipay.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/inespay.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/jpmorgan.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/juspaythreedsserver.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/klarna.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/mollie.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/nexinets.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/nexixpay.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/novalnet.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/opayo.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/opennode.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/paybox.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/payeezy.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/paystack.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/placetopay.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/powertranz.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/prophetpay.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/recurly.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/redsys.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/shift4.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/square.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/stax.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/stripebilling.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/taxjar.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/thunes.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/unified_authentication_service.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/xendit.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/zen.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/zsl.rs	54% smaller
crates/hyperswitch_domain_models/src/errors/api_error_response.rs	54% smaller
crates/hyperswitch_interfaces/src/connector_integration_v2.rs	54% smaller
crates/router/src/connector/adyenplatform.rs	54% smaller
crates/router/src/connector/dummyconnector.rs	54% smaller
crates/router/src/connector/ebanx.rs	54% smaller
crates/router/src/connector/gpayments.rs	54% smaller
crates/router/src/connector/netcetera.rs	54% smaller
crates/router/src/connector/nmi.rs	54% smaller
crates/router/src/connector/plaid.rs	54% smaller
crates/router/src/connector/riskified.rs	54% smaller
crates/router/src/connector/signifyd.rs	54% smaller
crates/router/src/connector/utils.rs	54% smaller
crates/router/src/connector/wellsfargopayout.rs	54% smaller
crates/hyperswitch_connectors/src/connectors/razorpay.rs	52% smaller
crates/hyperswitch_connectors/src/connectors/volt/transformers.rs	52% smaller
crates/router/src/services/api.rs	52% smaller
crates/hyperswitch_connectors/src/connectors/bluesnap.rs	51% smaller
crates/hyperswitch_connectors/src/connectors/globepay/transformers.rs	51% smaller
crates/hyperswitch_connectors/src/connectors/novalnet/transformers.rs	51% smaller
crates/hyperswitch_connectors/src/connectors/nuvei/transformers.rs	51% smaller
crates/hyperswitch_connectors/src/connectors/tsys/transformers.rs	51% smaller
crates/hyperswitch_connectors/src/connectors/wellsfargo/transformers.rs	51% smaller
crates/hyperswitch_connectors/src/connectors/paystack/transformers.rs	50% smaller
crates/hyperswitch_connectors/src/connectors/rapyd/transformers.rs	50% smaller
crates/hyperswitch_connectors/src/connectors/braintree/transformers.rs	49% smaller
crates/router/src/connector/threedsecureio/transformers.rs	49% smaller
crates/hyperswitch_connectors/src/connectors/fiuu/transformers.rs	49% smaller
crates/hyperswitch_connectors/src/connectors/zsl/transformers.rs	48% smaller
crates/hyperswitch_connectors/src/connectors/redsys/transformers.rs	48% smaller
crates/hyperswitch_connectors/src/connectors/paybox/transformers.rs	48% smaller
crates/hyperswitch_connectors/src/connectors/bamboraapac/transformers.rs	47% smaller
crates/hyperswitch_connectors/src/connectors/prophetpay/transformers.rs	47% smaller
crates/hyperswitch_connectors/src/connectors/braintree.rs	47% smaller
crates/router/src/connector/plaid/transformers.rs	47% smaller
crates/hyperswitch_connectors/src/connectors/hipay/transformers.rs	47% smaller
crates/hyperswitch_connectors/src/connectors/elavon/transformers.rs	47% smaller
crates/hyperswitch_connectors/src/connectors/mifinity.rs	47% smaller
crates/hyperswitch_connectors/src/connectors/razorpay/transformers.rs	47% smaller
crates/hyperswitch_connectors/src/connectors/nomupay.rs	47% smaller
crates/hyperswitch_connectors/src/connectors/inespay/transformers.rs	46% smaller
crates/hyperswitch_connectors/src/connectors/datatrans/transformers.rs	46% smaller
crates/router/src/connector/wise.rs	46% smaller
crates/hyperswitch_connectors/src/connectors/xendit/transformers.rs	46% smaller
crates/hyperswitch_connectors/src/connectors/boku.rs	46% smaller
crates/hyperswitch_connectors/src/connectors/fiserv.rs	46% smaller
crates/hyperswitch_connectors/src/connectors/fiservemea.rs	46% smaller
crates/hyperswitch_connectors/src/connectors/noon/transformers.rs	46% smaller
crates/router/src/connector/netcetera/transformers.rs	46% smaller
crates/hyperswitch_connectors/src/connectors/authorizedotnet/transformers.rs	45% smaller
crates/hyperswitch_connectors/src/connectors/authorizedotnet.rs	45% smaller
crates/hyperswitch_connectors/src/connectors/deutschebank/transformers.rs	45% smaller
crates/hyperswitch_connectors/src/connectors/cybersource/transformers.rs	44% smaller
crates/hyperswitch_connectors/src/connectors/checkout/transformers.rs	44% smaller
crates/hyperswitch_connectors/src/connectors/datatrans.rs	44% smaller
crates/hyperswitch_connectors/src/connectors/worldpay/transformers.rs	44% smaller
crates/router/src/connector/payone.rs	44% smaller
crates/hyperswitch_connectors/src/connectors/deutschebank.rs	44% smaller
crates/hyperswitch_connectors/src/connectors/wellsfargo.rs	44% smaller
crates/hyperswitch_connectors/src/connectors/adyen.rs	44% smaller
crates/hyperswitch_connectors/src/connectors/trustpay.rs	44% smaller
crates/router/src/connector/stripe/transformers.rs	43% smaller
crates/hyperswitch_connectors/src/connectors/cybersource.rs	43% smaller
crates/hyperswitch_connectors/src/connectors/iatapay.rs	43% smaller
crates/hyperswitch_connectors/src/connectors/iatapay/transformers.rs	43% smaller
crates/hyperswitch_connectors/src/connectors/multisafepay/transformers.rs	43% smaller
crates/hyperswitch_connectors/src/connectors/bankofamerica.rs	43% smaller
crates/router/src/connector/nmi/transformers.rs	43% smaller
crates/hyperswitch_connectors/src/connectors/paypal.rs	43% smaller
crates/hyperswitch_connectors/src/connectors/powertranz/transformers.rs	42% smaller
crates/hyperswitch_connectors/src/connectors/payme/transformers.rs	41% smaller
crates/router/src/connector/stripe.rs	40% smaller
crates/hyperswitch_connectors/src/connectors/globalpay.rs	40% smaller
crates/hyperswitch_connectors/src/connectors/itaubank.rs	40% smaller
crates/hyperswitch_connectors/src/connectors/moneris.rs	40% smaller
crates/hyperswitch_connectors/src/connectors/payu.rs	40% smaller
crates/hyperswitch_connectors/src/connectors/volt.rs	40% smaller
crates/hyperswitch_connectors/src/connectors/worldpay.rs	40% smaller
crates/hyperswitch_connectors/src/connectors/zen/transformers.rs	40% smaller
crates/hyperswitch_interfaces/src/api.rs	40% smaller
crates/hyperswitch_connectors/src/connectors/trustpay/transformers.rs	40% smaller
crates/hyperswitch_connectors/src/connectors/bankofamerica/transformers.rs	36% smaller
crates/hyperswitch_domain_models/src/router_data.rs	31% smaller
crates/hyperswitch_connectors/src/connectors/adyen/transformers.rs	28% smaller
api-reference-v2/openapi_spec.json	0% smaller
crates/api_models/src/payments.rs	0% smaller
crates/diesel_models/src/payment_attempt.rs	0% smaller
crates/diesel_models/src/schema_v2.rs	0% smaller
crates/hyperswitch_connectors/src/connectors/chargebee/transformers.rs	0% smaller
crates/hyperswitch_domain_models/src/lib.rs	0% smaller
crates/hyperswitch_domain_models/src/payments/payment_attempt.rs	0% smaller
crates/hyperswitch_domain_models/src/revenue_recovery.rs	0% smaller
crates/router/src/core/payments/operations/payment_response.rs	0% smaller
crates/router/src/core/payments/retry.rs	0% smaller
crates/router/src/core/payments/transformers.rs	0% smaller
crates/router/src/core/payouts.rs	0% smaller
crates/router/src/core/refunds.rs	0% smaller
v2_migrations/2025-04-02-051959_add_network_error_info_in_payment_attempt/down.sql	Unsupported file format
v2_migrations/2025-04-02-051959_add_network_error_info_in_payment_attempt/up.sql	Unsupported file format

[AkshayaFoiger]

Connector Code changes, LGTM!