hyperswitch
hyperswitch copied to clipboard
juspay
feat(core): Hyperswitch <|> UCS Integration
Type of Change
- [ ] Bugfix
- [x] New feature
- [ ] Enhancement
- [ ] Refactoring
- [ ] Dependency updates
- [ ] Documentation
- [ ] CI/CD
Description
The payment flow starts in call_connector_service()
1. Determining Unified Connector Service Eligibility:
The flow starts with should_call_unified_connector_service() which determines if a payment should be routed through the unified connector service.
The function:
- Gets the merchant ID and connector name
- Constructs a config key using
merchant_id,connector_name,payment_method, andflow_name - Checks the database for a rollout configuration using this key
- If a config exists, it parses the rollout percentage
- Generates a random value and compares it with the rollout percentage
- If the random value is less than the rollout percentage, it attempts to connect to the unified connector service
- Returns either a connected client or None
2. Calling Unified Connector Service:
If the service is eligible, the call_unified_connector_service() function is invoked:
The function:
- Constructs the authorization request using
construct_ucs_authorize_request() - Creates a new gRPC request
- Adds metadata to the request using
construct_ucs_request_metadata() - Makes the gRPC call to authorize the payment
- Processes the response using
construct_router_data_from_ucs_authorize_response()
3. Request Metadata Construction:
The construct_ucs_request_metadata() function adds necessary metadata to the request:
The function:
- Extracts the connector authentication type
- Gets the connector name
- Adds the connector name to metadata
- Adds authentication headers based on the auth type (e.g., header key)
4. Post-Processing and Tracker Updates:
After the unified connector service call:
- If needed, adds a task to the process tracker
- Updates payment trackers with the latest information
- Records timing information for monitoring
Additional Changes
- [ ] This PR modifies the API contract
- [ ] This PR modifies the database schema
- [x] This PR modifies application configuration/environment variables
Motivation and Context
Unified Connector Service (UCS) is an open source, stateless merchant payments abstraction service (built using gRPC) that enables developers to integrate with a wide variety of payment processors using a unified contract. It offers the following capabilities.
- Unified contract across multiple payment processors
- Establishing and accepting connections to numerous remote endpoints of payment processors like Stripe/Adyen/Razorpay
- Supports all payment payment life-cycle management operations like including authorization, capture, refunds, status and chargebacks across processors
- Client-SDKs in multiple programming languages (Java, Python, Go, Rust, PHP) for rapid integration.
The goal is to integrate Hyperswitch with Unified Connector Service (UCS), such that Hyperswitch can start routing traffic through the Unified Connector Service (UCS), depending on config based staggering.
How did you test it?
Happy Case (Adyen)
Payment (Through Hyperswitch)
-Request
curl --location 'http://localhost:8080/payments' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key: dev_7xsxWdU69lVRQZHPxhX3m4retRElSfYR5UPaVTwoOPvwrAmzLyqVCmmTCIU6bJ2p' \
--data-raw '{
"amount": 1000,
"currency": "USD",
"confirm": true,
"capture_method": "automatic",
"capture_on": "2022-09-10T10:11:12Z",
"amount_to_capture": 1000,
"customer_id": "abcdef",
"email": "[email protected]",
"name": "John Doe",
"phone": "999999999",
"phone_country_code": "+65",
"description": "Its my first payment request",
"authentication_type": "no_three_ds",
"return_url": "https://duck.com",
"payment_method": "card",
"payment_method_type": "credit",
"payment_method_data": {
"card": {
"card_number": "4111111111111111",
"card_exp_month": "03",
"card_exp_year": "30",
"card_holder_name": "joseph Doe",
"card_cvc": "737"
}
},
"billing": {
"address": {
"line1": "1467",
"line2": "Harrison Street",
"line3": "Harrison Street",
"city": "San Fransico",
"state": "California",
"zip": "94122",
"country": "US",
"first_name": "joseph",
"last_name": "Doe"
},
"phone": {
"number": "9123456789",
"country_code": "+91"
}
},
"shipping": {
"address": {
"line1": "1467",
"line2": "Harrison Street",
"line3": "Harrison Street",
"city": "San Fransico",
"state": "California",
"zip": "94122",
"country": "US",
"first_name": "joseph",
"last_name": "Doe"
},
"phone": {
"number": "9123456789",
"country_code": "+91"
}
},
"statement_descriptor_name": "joseph",
"statement_descriptor_suffix": "JS",
"metadata": {
"udf1": "value1",
"new_customer": "true",
"login_date": "2019-09-10T10:11:12Z"
},
"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"
}
}'
-Response
{
"payment_id": "pay_nYvxwltgwLLkgoofWldv",
"merchant_id": "postman_merchant_GHAction_be0d276f-8177-4c23-9d78-e2590128391d",
"status": "succeeded",
"amount": 1000,
"net_amount": 1000,
"shipping_cost": null,
"amount_capturable": 0,
"amount_received": 1000,
"connector": "adyen",
"client_secret": "pay_nYvxwltgwLLkgoofWldv_secret_KWeea2KoCzZSKD6k0qow",
"created": "2025-06-06T12:13:18.720Z",
"currency": "USD",
"customer_id": "abcdef",
"customer": {
"id": "abcdef",
"name": "John Doe",
"email": "[email protected]",
"phone": "999999999",
"phone_country_code": "+65"
},
"description": "Its my first payment request",
"refunds": null,
"disputes": null,
"mandate_id": null,
"mandate_data": null,
"setup_future_usage": null,
"off_session": null,
"capture_on": null,
"capture_method": "automatic",
"payment_method": "card",
"payment_method_data": {
"card": {
"last4": "1111",
"card_type": null,
"card_network": null,
"card_issuer": null,
"card_issuing_country": null,
"card_isin": "411111",
"card_extended_bin": null,
"card_exp_month": "03",
"card_exp_year": "30",
"card_holder_name": "joseph Doe",
"payment_checks": null,
"authentication_data": null
},
"billing": null
},
"payment_token": null,
"shipping": {
"address": {
"city": "San Fransico",
"country": "US",
"line1": "1467",
"line2": "Harrison Street",
"line3": "Harrison Street",
"zip": "94122",
"state": "California",
"first_name": "joseph",
"last_name": "Doe"
},
"phone": {
"number": "9123456789",
"country_code": "+91"
},
"email": null
},
"billing": {
"address": {
"city": "San Fransico",
"country": "US",
"line1": "1467",
"line2": "Harrison Street",
"line3": "Harrison Street",
"zip": "94122",
"state": "California",
"first_name": "joseph",
"last_name": "Doe"
},
"phone": {
"number": "9123456789",
"country_code": "+91"
},
"email": null
},
"order_details": null,
"email": "[email protected]",
"name": "John Doe",
"phone": "999999999",
"return_url": "https://duck.com/",
"authentication_type": "no_three_ds",
"statement_descriptor_name": "joseph",
"statement_descriptor_suffix": "JS",
"next_action": null,
"cancellation_reason": null,
"error_code": null,
"error_message": null,
"unified_code": null,
"unified_message": null,
"payment_experience": null,
"payment_method_type": "credit",
"connector_label": null,
"business_country": null,
"business_label": "default",
"business_sub_label": null,
"allowed_payment_method_types": null,
"ephemeral_key": {
"customer_id": "abcdef",
"created_at": 1749211998,
"expires": 1749215598,
"secret": "epk_4ab0c2e897284f14962fc5f19c424092"
},
"manual_retry_allowed": false,
"connector_transaction_id": "L8T7XPGBM6XLLR65",
"frm_message": null,
"metadata": {
"udf1": "value1",
"login_date": "2019-09-10T10:11:12Z",
"new_customer": "true"
},
"connector_metadata": null,
"feature_metadata": null,
"reference_id": "pay_nYvxwltgwLLkgoofWldv_1",
"payment_link": null,
"profile_id": "pro_PAIDVbsAbyEWQDTK7fHD",
"surcharge_details": null,
"attempt_count": 1,
"merchant_decision": null,
"merchant_connector_id": "mca_aL03aMAluMPtmE5JHDEl",
"incremental_authorization_allowed": null,
"authorization_count": null,
"incremental_authorizations": null,
"external_authentication_details": null,
"external_3ds_authentication_attempted": false,
"expires_on": "2025-06-06T12:28:18.720Z",
"fingerprint": null,
"browser_info": {
"language": "nl-NL",
"time_zone": 0,
"ip_address": "125.0.0.1",
"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",
"color_depth": 24,
"java_enabled": true,
"screen_width": 1536,
"accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
"screen_height": 723,
"java_script_enabled": true
},
"payment_method_id": null,
"payment_method_status": null,
"updated": "2025-06-06T12:13:20.638Z",
"split_payments": null,
"frm_metadata": null,
"extended_authorization_applied": null,
"capture_before": null,
"merchant_order_reference_id": null,
"order_tax_amount": null,
"connector_mandate_id": null,
"card_discovery": "manual",
"force_3ds_challenge": false,
"force_3ds_challenge_trigger": false,
"issuer_error_code": null,
"issuer_error_message": null,
"is_iframe_redirection_enabled": null,
"whole_connector_response": null
}
Payment (Through Unified Connector Service)
-Request
curl --location 'http://localhost:8080/payments' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key: dev_7xsxWdU69lVRQZHPxhX3m4retRElSfYR5UPaVTwoOPvwrAmzLyqVCmmTCIU6bJ2p' \
--data-raw '{
"amount": 1000,
"currency": "USD",
"confirm": true,
"capture_method": "automatic",
"capture_on": "2022-09-10T10:11:12Z",
"amount_to_capture": 1000,
"customer_id": "abcdef",
"email": "[email protected]",
"name": "John Doe",
"phone": "999999999",
"phone_country_code": "+65",
"description": "Its my first payment request",
"authentication_type": "no_three_ds",
"return_url": "https://duck.com",
"payment_method": "card",
"payment_method_type": "credit",
"payment_method_data": {
"card": {
"card_number": "4111111111111111",
"card_exp_month": "03",
"card_exp_year": "30",
"card_holder_name": "joseph Doe",
"card_cvc": "737"
}
},
"billing": {
"address": {
"line1": "1467",
"line2": "Harrison Street",
"line3": "Harrison Street",
"city": "San Fransico",
"state": "California",
"zip": "94122",
"country": "US",
"first_name": "joseph",
"last_name": "Doe"
},
"phone": {
"number": "9123456789",
"country_code": "+91"
}
},
"shipping": {
"address": {
"line1": "1467",
"line2": "Harrison Street",
"line3": "Harrison Street",
"city": "San Fransico",
"state": "California",
"zip": "94122",
"country": "US",
"first_name": "joseph",
"last_name": "Doe"
},
"phone": {
"number": "9123456789",
"country_code": "+91"
}
},
"statement_descriptor_name": "joseph",
"statement_descriptor_suffix": "JS",
"metadata": {
"udf1": "value1",
"new_customer": "true",
"login_date": "2019-09-10T10:11:12Z"
},
"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"
}
}'
-Response
{
"payment_id": "pay_bkVrJMZvIAEiJmz2j5cR",
"merchant_id": "postman_merchant_GHAction_be0d276f-8177-4c23-9d78-e2590128391d",
"status": "succeeded",
"amount": 1000,
"net_amount": 1000,
"shipping_cost": null,
"amount_capturable": 0,
"amount_received": 1000,
"connector": "adyen",
"client_secret": "pay_bkVrJMZvIAEiJmz2j5cR_secret_JCjopg5BaNBEAJrOWp5I",
"created": "2025-06-06T12:09:30.018Z",
"currency": "USD",
"customer_id": "abcdef",
"customer": {
"id": "abcdef",
"name": "John Doe",
"email": "[email protected]",
"phone": "999999999",
"phone_country_code": "+65"
},
"description": "Its my first payment request",
"refunds": null,
"disputes": null,
"mandate_id": null,
"mandate_data": null,
"setup_future_usage": null,
"off_session": null,
"capture_on": null,
"capture_method": "automatic",
"payment_method": "card",
"payment_method_data": {
"card": {
"last4": "1111",
"card_type": null,
"card_network": null,
"card_issuer": null,
"card_issuing_country": null,
"card_isin": "411111",
"card_extended_bin": null,
"card_exp_month": "03",
"card_exp_year": "30",
"card_holder_name": "joseph Doe",
"payment_checks": null,
"authentication_data": null
},
"billing": null
},
"payment_token": null,
"shipping": {
"address": {
"city": "San Fransico",
"country": "US",
"line1": "1467",
"line2": "Harrison Street",
"line3": "Harrison Street",
"zip": "94122",
"state": "California",
"first_name": "joseph",
"last_name": "Doe"
},
"phone": {
"number": "9123456789",
"country_code": "+91"
},
"email": null
},
"billing": {
"address": {
"city": "San Fransico",
"country": "US",
"line1": "1467",
"line2": "Harrison Street",
"line3": "Harrison Street",
"zip": "94122",
"state": "California",
"first_name": "joseph",
"last_name": "Doe"
},
"phone": {
"number": "9123456789",
"country_code": "+91"
},
"email": null
},
"order_details": null,
"email": "[email protected]",
"name": "John Doe",
"phone": "999999999",
"return_url": "https://duck.com/",
"authentication_type": "no_three_ds",
"statement_descriptor_name": "joseph",
"statement_descriptor_suffix": "JS",
"next_action": null,
"cancellation_reason": null,
"error_code": null,
"error_message": null,
"unified_code": null,
"unified_message": null,
"payment_experience": null,
"payment_method_type": "credit",
"connector_label": null,
"business_country": null,
"business_label": "default",
"business_sub_label": null,
"allowed_payment_method_types": null,
"ephemeral_key": {
"customer_id": "abcdef",
"created_at": 1749211769,
"expires": 1749215369,
"secret": "epk_3217360d3a924cf991bde23c6155ad75"
},
"manual_retry_allowed": false,
"connector_transaction_id": "pay_bkVrJMZvIAEiJmz2j5cR_1",
"frm_message": null,
"metadata": {
"udf1": "value1",
"login_date": "2019-09-10T10:11:12Z",
"new_customer": "true"
},
"connector_metadata": null,
"feature_metadata": null,
"reference_id": "pay_bkVrJMZvIAEiJmz2j5cR_1",
"payment_link": null,
"profile_id": "pro_PAIDVbsAbyEWQDTK7fHD",
"surcharge_details": null,
"attempt_count": 1,
"merchant_decision": null,
"merchant_connector_id": "mca_aL03aMAluMPtmE5JHDEl",
"incremental_authorization_allowed": null,
"authorization_count": null,
"incremental_authorizations": null,
"external_authentication_details": null,
"external_3ds_authentication_attempted": false,
"expires_on": "2025-06-06T12:24:30.018Z",
"fingerprint": null,
"browser_info": {
"language": "nl-NL",
"time_zone": 0,
"ip_address": "125.0.0.1",
"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",
"color_depth": 24,
"java_enabled": true,
"screen_width": 1536,
"accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
"screen_height": 723,
"java_script_enabled": true
},
"payment_method_id": null,
"payment_method_status": null,
"updated": "2025-06-06T12:09:32.852Z",
"split_payments": null,
"frm_metadata": null,
"extended_authorization_applied": null,
"capture_before": null,
"merchant_order_reference_id": null,
"order_tax_amount": null,
"connector_mandate_id": null,
"card_discovery": "manual",
"force_3ds_challenge": false,
"force_3ds_challenge_trigger": false,
"issuer_error_code": null,
"issuer_error_message": null,
"is_iframe_redirection_enabled": null,
"whole_connector_response": null
}
Failure Case (Adyen)
Payment (Through Hyperswitch)
-Request
curl --location 'http://localhost:8080/payments' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key: dev_IyPRyeEZQVWdKHz40sZZNdJWhK9VzN2sj1I2pBroIt1nmHWM2O2qvtKo7wXDFjhf' \
--data-raw '{
"amount": 1000,
"currency": "USD",
"confirm": true,
"capture_method": "automatic",
"capture_on": "2022-09-10T10:11:12Z",
"amount_to_capture": 1000,
"customer_id": "abcdef",
"email": "[email protected]",
"name": "John Doe",
"phone": "999999999",
"phone_country_code": "+65",
"description": "Its my first payment request",
"authentication_type": "no_three_ds",
"return_url": "https://duck.com",
"payment_method": "card",
"payment_method_type": "credit",
"payment_method_data": {
"card": {
"card_number": "4111111111111111",
"card_exp_month": "03",
"card_exp_year": "30",
"card_holder_name": "joseph Doe",
"card_cvc": "739"
}
},
"billing": {
"address": {
"line1": "1467",
"line2": "Harrison Street",
"line3": "Harrison Street",
"city": "San Fransico",
"state": "California",
"zip": "94122",
"country": "US",
"first_name": "joseph",
"last_name": "Doe"
},
"phone": {
"number": "9123456789",
"country_code": "+91"
}
},
"shipping": {
"address": {
"line1": "1467",
"line2": "Harrison Street",
"line3": "Harrison Street",
"city": "San Fransico",
"state": "California",
"zip": "94122",
"country": "US",
"first_name": "joseph",
"last_name": "Doe"
},
"phone": {
"number": "9123456789",
"country_code": "+91"
}
},
"statement_descriptor_name": "joseph",
"statement_descriptor_suffix": "JS",
"metadata": {
"udf1": "value1",
"new_customer": "true",
"login_date": "2019-09-10T10:11:12Z"
},
"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"
}
}'
-Response
{
"payment_id": "pay_XxNJgnR11lsEdsN2dT9r",
"merchant_id": "postman_merchant_GHAction_43152e6c-e97e-47b9-859e-63f125c146cc",
"status": "failed",
"amount": 1000,
"net_amount": 1000,
"shipping_cost": null,
"amount_capturable": 0,
"amount_received": null,
"connector": "adyen",
"client_secret": "pay_XxNJgnR11lsEdsN2dT9r_secret_K1M26AfFNIHLYDpNrG1V",
"created": "2025-06-09T11:45:57.628Z",
"currency": "USD",
"customer_id": "abcdef",
"customer": {
"id": "abcdef",
"name": "John Doe",
"email": "[email protected]",
"phone": "999999999",
"phone_country_code": "+65"
},
"description": "Its my first payment request",
"refunds": null,
"disputes": null,
"mandate_id": null,
"mandate_data": null,
"setup_future_usage": null,
"off_session": null,
"capture_on": null,
"capture_method": "automatic",
"payment_method": "card",
"payment_method_data": {
"card": {
"last4": "1111",
"card_type": null,
"card_network": null,
"card_issuer": null,
"card_issuing_country": null,
"card_isin": "411111",
"card_extended_bin": null,
"card_exp_month": "03",
"card_exp_year": "30",
"card_holder_name": "joseph Doe",
"payment_checks": null,
"authentication_data": null
},
"billing": null
},
"payment_token": null,
"shipping": {
"address": {
"city": "San Fransico",
"country": "US",
"line1": "1467",
"line2": "Harrison Street",
"line3": "Harrison Street",
"zip": "94122",
"state": "California",
"first_name": "joseph",
"last_name": "Doe"
},
"phone": {
"number": "9123456789",
"country_code": "+91"
},
"email": null
},
"billing": {
"address": {
"city": "San Fransico",
"country": "US",
"line1": "1467",
"line2": "Harrison Street",
"line3": "Harrison Street",
"zip": "94122",
"state": "California",
"first_name": "joseph",
"last_name": "Doe"
},
"phone": {
"number": "9123456789",
"country_code": "+91"
},
"email": null
},
"order_details": null,
"email": "[email protected]",
"name": "John Doe",
"phone": "999999999",
"return_url": "https://duck.com/",
"authentication_type": "no_three_ds",
"statement_descriptor_name": "joseph",
"statement_descriptor_suffix": "JS",
"next_action": null,
"cancellation_reason": null,
"error_code": "24",
"error_message": "CVC Declined",
"unified_code": "UE_9000",
"unified_message": "Something went wrong",
"payment_experience": null,
"payment_method_type": "credit",
"connector_label": null,
"business_country": null,
"business_label": "default",
"business_sub_label": null,
"allowed_payment_method_types": null,
"ephemeral_key": {
"customer_id": "abcdef",
"created_at": 1749469557,
"expires": 1749473157,
"secret": "epk_d38fe6bfd1874be7beda3f1ce333dec2"
},
"manual_retry_allowed": true,
"connector_transaction_id": "G88K4K5FM6XLLR65",
"frm_message": null,
"metadata": {
"udf1": "value1",
"login_date": "2019-09-10T10:11:12Z",
"new_customer": "true"
},
"connector_metadata": null,
"feature_metadata": null,
"reference_id": null,
"payment_link": null,
"profile_id": "pro_lJyta4Kl5ASi3ssVgHiB",
"surcharge_details": null,
"attempt_count": 1,
"merchant_decision": null,
"merchant_connector_id": "mca_DO0Hlz6fvzvMUFoC7SaT",
"incremental_authorization_allowed": false,
"authorization_count": null,
"incremental_authorizations": null,
"external_authentication_details": null,
"external_3ds_authentication_attempted": false,
"expires_on": "2025-06-09T12:00:57.628Z",
"fingerprint": null,
"browser_info": {
"language": "nl-NL",
"time_zone": 0,
"ip_address": "125.0.0.1",
"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",
"color_depth": 24,
"java_enabled": true,
"screen_width": 1536,
"accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
"screen_height": 723,
"java_script_enabled": true
},
"payment_method_id": null,
"payment_method_status": null,
"updated": "2025-06-09T11:46:00.200Z",
"split_payments": null,
"frm_metadata": null,
"extended_authorization_applied": null,
"capture_before": null,
"merchant_order_reference_id": null,
"order_tax_amount": null,
"connector_mandate_id": null,
"card_discovery": "manual",
"force_3ds_challenge": false,
"force_3ds_challenge_trigger": false,
"issuer_error_code": null,
"issuer_error_message": "DECLINED CVC Incorrect",
"is_iframe_redirection_enabled": null,
"whole_connector_response": null
}
Payment (Through Unified Connector Service)
-Request
curl --location 'http://localhost:8080/payments' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key: dev_IyPRyeEZQVWdKHz40sZZNdJWhK9VzN2sj1I2pBroIt1nmHWM2O2qvtKo7wXDFjhf' \
--data-raw '{
"amount": 1000,
"currency": "USD",
"confirm": true,
"capture_method": "automatic",
"capture_on": "2022-09-10T10:11:12Z",
"amount_to_capture": 1000,
"customer_id": "abcdef",
"email": "[email protected]",
"name": "John Doe",
"phone": "999999999",
"phone_country_code": "+65",
"description": "Its my first payment request",
"authentication_type": "no_three_ds",
"return_url": "https://duck.com",
"payment_method": "card",
"payment_method_type": "credit",
"payment_method_data": {
"card": {
"card_number": "4111111111111111",
"card_exp_month": "03",
"card_exp_year": "30",
"card_holder_name": "joseph Doe",
"card_cvc": "739"
}
},
"billing": {
"address": {
"line1": "1467",
"line2": "Harrison Street",
"line3": "Harrison Street",
"city": "San Fransico",
"state": "California",
"zip": "94122",
"country": "US",
"first_name": "joseph",
"last_name": "Doe"
},
"phone": {
"number": "9123456789",
"country_code": "+91"
}
},
"shipping": {
"address": {
"line1": "1467",
"line2": "Harrison Street",
"line3": "Harrison Street",
"city": "San Fransico",
"state": "California",
"zip": "94122",
"country": "US",
"first_name": "joseph",
"last_name": "Doe"
},
"phone": {
"number": "9123456789",
"country_code": "+91"
}
},
"statement_descriptor_name": "joseph",
"statement_descriptor_suffix": "JS",
"metadata": {
"udf1": "value1",
"new_customer": "true",
"login_date": "2019-09-10T10:11:12Z"
},
"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"
}
}'
-Response
{
"payment_id": "pay_qA0AgXeMZeo0eRv7zttj",
"merchant_id": "postman_merchant_GHAction_43152e6c-e97e-47b9-859e-63f125c146cc",
"status": "failed",
"amount": 1000,
"net_amount": 1000,
"shipping_cost": null,
"amount_capturable": 0,
"amount_received": null,
"connector": "adyen",
"client_secret": "pay_qA0AgXeMZeo0eRv7zttj_secret_AvdqzELk9yZfJm603Mkj",
"created": "2025-06-09T12:20:15.206Z",
"currency": "USD",
"customer_id": "abcdef",
"customer": {
"id": "abcdef",
"name": "John Doe",
"email": "[email protected]",
"phone": "999999999",
"phone_country_code": "+65"
},
"description": "Its my first payment request",
"refunds": null,
"disputes": null,
"mandate_id": null,
"mandate_data": null,
"setup_future_usage": null,
"off_session": null,
"capture_on": null,
"capture_method": "automatic",
"payment_method": "card",
"payment_method_data": {
"card": {
"last4": "1111",
"card_type": null,
"card_network": null,
"card_issuer": null,
"card_issuing_country": null,
"card_isin": "411111",
"card_extended_bin": null,
"card_exp_month": "03",
"card_exp_year": "30",
"card_holder_name": "joseph Doe",
"payment_checks": null,
"authentication_data": null
},
"billing": null
},
"payment_token": null,
"shipping": {
"address": {
"city": "San Fransico",
"country": "US",
"line1": "1467",
"line2": "Harrison Street",
"line3": "Harrison Street",
"zip": "94122",
"state": "California",
"first_name": "joseph",
"last_name": "Doe"
},
"phone": {
"number": "9123456789",
"country_code": "+91"
},
"email": null
},
"billing": {
"address": {
"city": "San Fransico",
"country": "US",
"line1": "1467",
"line2": "Harrison Street",
"line3": "Harrison Street",
"zip": "94122",
"state": "California",
"first_name": "joseph",
"last_name": "Doe"
},
"phone": {
"number": "9123456789",
"country_code": "+91"
},
"email": null
},
"order_details": null,
"email": "[email protected]",
"name": "John Doe",
"phone": "999999999",
"return_url": "https://duck.com/",
"authentication_type": "no_three_ds",
"statement_descriptor_name": "joseph",
"statement_descriptor_suffix": "JS",
"next_action": null,
"cancellation_reason": null,
"error_code": "24",
"error_message": "CVC Declined",
"unified_code": "UE_9000",
"unified_message": "Something went wrong",
"payment_experience": null,
"payment_method_type": "credit",
"connector_label": null,
"business_country": null,
"business_label": "default",
"business_sub_label": null,
"allowed_payment_method_types": null,
"ephemeral_key": {
"customer_id": "abcdef",
"created_at": 1749471615,
"expires": 1749475215,
"secret": "epk_3e37b132c42a44ec95100ff1ebe10ecc"
},
"manual_retry_allowed": true,
"connector_transaction_id": "QQJHXJ8V8XTGLXT5",
"frm_message": null,
"metadata": {
"udf1": "value1",
"login_date": "2019-09-10T10:11:12Z",
"new_customer": "true"
},
"connector_metadata": null,
"feature_metadata": null,
"reference_id": null,
"payment_link": null,
"profile_id": "pro_lJyta4Kl5ASi3ssVgHiB",
"surcharge_details": null,
"attempt_count": 1,
"merchant_decision": null,
"merchant_connector_id": "mca_DO0Hlz6fvzvMUFoC7SaT",
"incremental_authorization_allowed": false,
"authorization_count": null,
"incremental_authorizations": null,
"external_authentication_details": null,
"external_3ds_authentication_attempted": false,
"expires_on": "2025-06-09T12:35:15.206Z",
"fingerprint": null,
"browser_info": {
"language": "nl-NL",
"time_zone": 0,
"ip_address": "125.0.0.1",
"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",
"color_depth": 24,
"java_enabled": true,
"screen_width": 1536,
"accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
"screen_height": 723,
"java_script_enabled": true
},
"payment_method_id": null,
"payment_method_status": null,
"updated": "2025-06-09T12:20:17.622Z",
"split_payments": null,
"frm_metadata": null,
"extended_authorization_applied": null,
"capture_before": null,
"merchant_order_reference_id": null,
"order_tax_amount": null,
"connector_mandate_id": null,
"card_discovery": "manual",
"force_3ds_challenge": false,
"force_3ds_challenge_trigger": false,
"issuer_error_code": null,
"issuer_error_message": null,
"is_iframe_redirection_enabled": null,
"whole_connector_response": null
}
Checklist
- [x] I formatted the code
cargo +nightly fmt --all - [x] I addressed lints thrown by
cargo clippy - [x] I reviewed the submitted code
- [ ] I added unit tests for my changes where possible
Summary by CodeRabbit
-
New Features
- Introduced integration with a unified connector service (UCS) for payment authorization, including rollout configuration and gRPC communication.
- Added new configuration options for the unified connector service.
- Enhanced payment flows to support UCS-based routing and response handling.
-
Refactor
- Modularized payment connector service logic for improved maintainability and preparation steps.
- Streamlined retry and connector invocation flows to accommodate UCS integration.
-
Chores
- Updated dependencies and workflow steps to support new UCS features and gRPC client requirements.
Review changes with 
Changed Files
![semanticdiff-com[bot] avatar](https://avatars.githubusercontent.com/in/343311?v=4 "Published by a pub.dev verified publisher"){kind=small}
[!IMPORTANT]
Review skipped
Auto incremental reviews are disabled on this repository.
Please check the settings in the CodeRabbit UI or the
.coderabbit.yamlfile in this repository. To trigger a single review, invoke the@coderabbitai reviewcommand.You can disable this status message by setting the
reviews.review_statustofalsein the CodeRabbit configuration file.
Walkthrough
This change introduces integration with a new Unified Connector Service (UCS) for payment authorization flows. It adds configuration for UCS, new dependencies for gRPC communication, and utility modules for UCS request/response handling. The payment flow is refactored to modularize connector preparation steps and conditionally invoke UCS based on rollout configuration, updating the core logic and trait interfaces accordingly.
Changes
| File(s) | Change Summary |
|---|---|
| .github/workflows/cypress-tests-runner.yml | Added Protoc installation step using arduino/setup-protoc@v3 to CI workflow. |
| config/development.toml | Added [unified_connector_service] section with base_url configuration. |
| crates/router/Cargo.toml | Added rust-grpc-client (git dependency) and tonic (v0.13.0) as new dependencies. |
| crates/router/src/configs/secrets_transformers.rs | Included unified_connector_service field in returned settings. |
| crates/router/src/configs/settings.rs | Added UnifiedConnectorService struct and new field to Settings. |
| crates/router/src/consts.rs | Added new public constant UCS_ROLLOUT_PERCENT_CONFIG_PREFIX. |
| crates/router/src/core.rs | Declared new public module unified_connector_service. |
| crates/router/src/core/unified_connector_service.rs | Declared public submodule utils for UCS. |
| crates/router/src/core/unified_connector_service/utils.rs | Introduced UCS utility module: rollout logic, metadata construction, gRPC conversions, response handling. |
| crates/router/src/core/payments/flows.rs | Extended Feature trait with async call_unified_connector_service method. |
| crates/router/src/core/payments/flows/authorize_flow.rs | Implemented UCS call logic for payment authorization in Feature for PaymentsAuthorizeRouterData. |
| crates/router/src/core/payments.rs | Refactored payment flow: added call_connector_service_prerequisites, updated connector service logic for UCS invocation. |
| crates/router/src/core/payments/retry.rs | Updated retry logic to use new connector service prerequisites and UCS-aware call. |
Sequence Diagram(s)
sequenceDiagram
participant Client
participant Router
participant UCS (Unified Connector Service)
participant Connector
Client->>Router: Initiate Payment
Router->>Router: call_connector_service_prerequisites
Router->>Router: should_call_unified_connector_service
alt UCS rollout applies
Router->>UCS: call_unified_connector_service (gRPC)
UCS-->>Router: UCS Response
Router->>Client: Return UCS-based Result
else
Router->>Connector: Standard Connector Flow
Connector-->>Router: Connector Response
Router->>Client: Return Connector-based Result
end
Poem
In the warren, code hops anew,
With gRPC and UCS in view.
A rollout config, a secret key,
Payment flows as smooth as can be.
Refactored hops, a modular dance—
Now rabbits process payments at a glance!
🐇💳✨
🪧 Tips
Chat
There are 3 ways to chat with CodeRabbit:
- Review comments: Directly reply to a review comment made by CodeRabbit. Example:
I pushed a fix in commit <commit_id>, please review it.Explain this complex logic.Open a follow-up GitHub issue for this discussion.
- Files and specific lines of code (under the "Files changed" tab): Tag
@coderabbitaiin a new review comment at the desired location with your query. Examples:@coderabbitai explain this code block.@coderabbitai modularize this function.
- PR comments: Tag
@coderabbitaiin a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:@coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.@coderabbitai read src/utils.ts and explain its main purpose.@coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.@coderabbitai help me debug CodeRabbit configuration file.
Support
Need help? Create a ticket on our support page for assistance with any issues or questions.
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.
CodeRabbit Commands (Invoked using PR comments)
@coderabbitai pauseto pause the reviews on a PR.@coderabbitai resumeto resume the paused reviews.@coderabbitai reviewto trigger an incremental review. This is useful when automatic reviews are disabled for the repository.@coderabbitai full reviewto do a full review from scratch and review all the files again.@coderabbitai summaryto regenerate the summary of the PR.@coderabbitai generate docstringsto generate docstrings for this PR.@coderabbitai generate sequence diagramto generate a sequence diagram of the changes in this PR.@coderabbitai resolveresolve all the CodeRabbit review comments.@coderabbitai configurationto show the current CodeRabbit configuration for the repository.@coderabbitai helpto get help.
Other keywords and placeholders
- Add
@coderabbitai ignoreanywhere in the PR description to prevent this PR from being reviewed. - Add
@coderabbitai summaryto generate the high-level summary at a specific location in the PR description. - Add
@coderabbitaianywhere in the PR title to generate the title automatically.
CodeRabbit Configuration File (.coderabbit.yaml)
- You can programmatically configure CodeRabbit by adding a
.coderabbit.yamlfile to the root of your repository. - Please see the configuration documentation for more information.
- If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation:
# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
Documentation and Community
- Visit our Documentation for detailed information on how to use CodeRabbit.
- Join our Discord Community to get help, request features, and share feedback.
- Follow us on X/Twitter for updates and announcements.
![coderabbitai[bot] avatar](https://avatars.githubusercontent.com/in/347564?v=4 "Published by a pub.dev verified publisher"){kind=small}