hyperswitch
hyperswitch copied to clipboard
juspay
feat(core): payments overcapture support for V1
Note: This feature is supported only via manual capture
Type of Change
- [ ] Bugfix
- [x] New feature
- [x] Enhancement
- [ ] Refactoring
- [ ] Dependency updates
- [ ] Documentation
- [ ] CI/CD
Description
Overcapture allows you to capture with an amount that’s higher than the authorised amount for a card payment. Unlike incremental authorisations, overcapture doesn’t result in additional authorisations with the card networks.
In this PR, Overcapture is implemented for stripe card payments.
Additional Changes
- [x] This PR modifies the API contract
- [x] This PR modifies the database schema
- [ ] This PR modifies application configuration/environment variables
API contract changes:
a) /payments create request to include request_overcapture boolean
b) /payments response to include
overcapture_status (applicable/ not_applicable)
amount_capturable will be updated
c) Profile create request and response to include always_request_overcapture (boolean)
d) Profile update request and response to include always_request_overcapture (boolean)
DB changes:
a) request_overcapture enum(Enable/Skip) field to be introduced in payment_intent
b)ovecapture_status enum(Applicable/NotApplicable) to be introduced in payment_attempt
d) always_request_overcapture boolean field to be introduced in business_profiles table
Not Handled (phase 2 )
a) Error is not thrown, when overcapture is not supported by the connector
b) List of supported connector and payment method not maintained.
c) Extend this feature for multiple manual capture and incremental authorization
-> Cypress test not added because it cannot be tested, via stripe. As this functionality has to be enabled by stripe. -> Supported only for stripe card flow
How did you test it?
- Create/ Update a business_profile with
"always_request_overcapture": true
curl --location 'http://localhost:8080/account/postman_merchant_GHAction_358cf835-2879-4d90-8475-ef0e1a246611/business_profile/pro_bzfd1zHHxs30uUyc2TQg' \
--header 'Content-Type: application/json' \
--header 'api-key: test_admin' \
--data '{
"profile_name": "US_default",
"always_request_overcapture": true
}'
Response
{
"merchant_id": "postman_merchant_GHAction_358cf835-2879-4d90-8475-ef0e1a246611",
"profile_id": "pro_bzfd1zHHxs30uUyc2TQg",
"profile_name": "US_default",
"return_url": "https://duck.com/success",
"enable_payment_response_hash": true,
"payment_response_hash_key": "83d4dikvQDLVgKR2jQDWYODswS1Tw6R2IP40rBatKGBEJwX6LhNeuNQbLzQIrX7T",
"redirect_to_merchant_with_http_post": false,
"webhook_details": {
"webhook_version": "1.0.1",
"webhook_username": "ekart_retail",
"webhook_password": "password_ekart@123",
"webhook_url": null,
"payment_created_enabled": true,
"payment_succeeded_enabled": true,
"payment_failed_enabled": true
},
"metadata": null,
"routing_algorithm": null,
"intent_fulfillment_time": 900,
"frm_routing_algorithm": null,
"payout_routing_algorithm": null,
"applepay_verified_domains": null,
"session_expiry": 900,
"payment_link_config": null,
"authentication_connector_details": null,
"use_billing_as_payment_method_billing": true,
"extended_card_info_config": null,
"collect_shipping_details_from_wallet_connector": false,
"collect_billing_details_from_wallet_connector": false,
"always_collect_shipping_details_from_wallet_connector": false,
"always_collect_billing_details_from_wallet_connector": false,
"is_connector_agnostic_mit_enabled": false,
"payout_link_config": null,
"outgoing_webhook_custom_http_headers": null,
"tax_connector_id": null,
"is_tax_connector_enabled": false,
"is_network_tokenization_enabled": false,
"is_auto_retries_enabled": false,
"max_auto_retries_enabled": null,
"is_click_to_pay_enabled": false,
"authentication_product_ids": null,
"always_request_overcapture": true
}
DB - business_profile will have a field called always_request_overcapture , marked as true
- Do a payment via stripe, without sending
request_overcapturein the payment request
curl --location 'http://localhost:8080/payments' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key: dev_oqtfJBx4JGn0Pmr3ZLtDMyUEzRZQ0IBeqnvImk4W1lbRHnh07rqLSXNTv8JKYk9L' \
--data-raw '{
"amount": 6540,
"currency": "USD",
"confirm": true,
"capture_method": "manual",
"capture_on": "2022-09-10T10:11:12Z",
"amount_to_capture": 6540,
"customer_id": "StripeCustomer",
"email": "[email protected]",
"name": "John Doe",
"phone": "999999999",
"phone_country_code": "+1",
"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": "4242424242424242",
"card_exp_month": "10",
"card_exp_year": "25",
"card_holder_name": "joseph Doe",
"card_cvc": "123"
}
},
"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"
},
"email": "[email protected]"
},
"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"
},
"routing": {
"type": "single",
"data": {
"connector": "stripe",
"merchant_connector_id": "mca_5SMXtr84AcZ8zhBefG8d"
}
}
}'
Cannot be tested because, this feature needs to be enabled at stripe
{"payment_id":"pay_l4MFxlOyZzF4XYXnKOqQ","merchant_id":"postman_merchant_GHAction_4f79729e-d004-4479-8bca-7201b2b231cf","status":"failed","amount":100000,"net_amount":100000,"shipping_cost":null,"amount_capturable":100000,"amount_received":null,"connector":"stripe","client_secret":"pay_l4MFxlOyZzF4XYXnKOqQ_secret_yYm9SUp6zsKMck6bp6IS","created":"2025-04-10T06:47:21.826Z","currency":"USD","customer_id":"cust_no_pm","customer":{"id":"cust_no_pm","name":null,"email":"[email protected]","phone":null,"phone_country_code":null},"description":null,"refunds":null,"disputes":null,"mandate_id":null,"mandate_data":null,"setup_future_usage":null,"off_session":null,"capture_on":null,"capture_method":"manual","payment_method":"card","payment_method_data":{"card":{"last4":"4242","card_type":null,"card_network":null,"card_issuer":null,"card_issuing_country":null,"card_isin":"424242","card_extended_bin":null,"card_exp_month":"12","card_exp_year":"27","card_holder_name":"joseph Doe","payment_checks":null,"authentication_data":null},"billing":null},"payment_token":null,"shipping":null,"billing":null,"order_details":null,"email":"[email protected]","name":null,"phone":null,"return_url":null,"authentication_type":"no_three_ds","statement_descriptor_name":null,"statement_descriptor_suffix":null,"next_action":null,"cancellation_reason":null,"error_code":"payment_intent_invalid_parameter","error_message":"This account is not eligible for the requested card features. See https://stripe.com/docs/payments/flexible-payments for more details.","unified_code":"UE_9000","unified_message":"Something went wrong","payment_experience":null,"payment_method_type":null,"connector_label":null,"business_country":null,"business_label":"default","business_sub_label":null,"allowed_payment_method_types":null,"ephemeral_key":{"customer_id":"cust_no_pm","created_at":1744267641,"expires":1744271241,"secret":"epk_699f09d11e474ce8a94b966a92e7103d"},"manual_retry_allowed":true,"connector_transaction_id":"pi_3RCEtTD5R7gDAGff025s2bBV","frm_message":null,"metadata":null,"connector_metadata":null,"feature_metadata":null,"reference_id":null,"payment_link":null,"profile_id":"pro_n9tKKY8IdEgvz80VpbRO","surcharge_details":null,"attempt_count":1,"merchant_decision":null,"merchant_connector_id":"mca_rW9zxYm57HLxSUWytHok","incremental_authorization_allowed":false,"authorization_count":null,"incremental_authorizations":null,"external_authentication_details":null,"external_3ds_authentication_attempted":false,"expires_on":"2025-04-10T07:02:21.826Z","fingerprint":null,"browser_info":{"language":"nl-NL","time_zone":0,"ip_address":"13.232.74.226","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-04-10T06:47:23.510Z","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,"overcapture_status":"applicable"}
Response
{"payment_id":"pay_l4MFxlOyZzF4XYXnKOqQ","merchant_id":"postman_merchant_GHAction_4f79729e-d004-4479-8bca-7201b2b231cf","status":"failed","amount":100000,"net_amount":100000,"shipping_cost":null,"amount_capturable":100000,"amount_received":null,"connector":"stripe","client_secret":"pay_l4MFxlOyZzF4XYXnKOqQ_secret_yYm9SUp6zsKMck6bp6IS","created":"2025-04-10T06:47:21.826Z","currency":"USD","customer_id":"cust_no_pm","customer":{"id":"cust_no_pm","name":null,"email":"[email protected]","phone":null,"phone_country_code":null},"description":null,"refunds":null,"disputes":null,"mandate_id":null,"mandate_data":null,"setup_future_usage":null,"off_session":null,"capture_on":null,"capture_method":"manual","payment_method":"card","payment_method_data":{"card":{"last4":"4242","card_type":null,"card_network":null,"card_issuer":null,"card_issuing_country":null,"card_isin":"424242","card_extended_bin":null,"card_exp_month":"12","card_exp_year":"27","card_holder_name":"joseph Doe","payment_checks":null,"authentication_data":null},"billing":null},"payment_token":null,"shipping":null,"billing":null,"order_details":null,"email":"[email protected]","name":null,"phone":null,"return_url":null,"authentication_type":"no_three_ds","statement_descriptor_name":null,"statement_descriptor_suffix":null,"next_action":null,"cancellation_reason":null,"error_code":"payment_intent_invalid_parameter","error_message":"This account is not eligible for the requested card features. See https://stripe.com/docs/payments/flexible-payments for more details.","unified_code":"UE_9000","unified_message":"Something went wrong","payment_experience":null,"payment_method_type":null,"connector_label":null,"business_country":null,"business_label":"default","business_sub_label":null,"allowed_payment_method_types":null,"ephemeral_key":{"customer_id":"cust_no_pm","created_at":1744267641,"expires":1744271241,"secret":"epk_699f09d11e474ce8a94b966a92e7103d"},"manual_retry_allowed":true,"connector_transaction_id":"pi_3RCEtTD5R7gDAGff025s2bBV","frm_message":null,"metadata":null,"connector_metadata":null,"feature_metadata":null,"reference_id":null,"payment_link":null,"profile_id":"pro_n9tKKY8IdEgvz80VpbRO","surcharge_details":null,"attempt_count":1,"merchant_decision":null,"merchant_connector_id":"mca_rW9zxYm57HLxSUWytHok","incremental_authorization_allowed":false,"authorization_count":null,"incremental_authorizations":null,"external_authentication_details":null,"external_3ds_authentication_attempted":false,"expires_on":"2025-04-10T07:02:21.826Z","fingerprint":null,"browser_info":{"language":"nl-NL","time_zone":0,"ip_address":"13.232.74.226","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-04-10T06:47:23.510Z","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,"overcapture_status":"applicable"}
- Create a update the business account
"always_request_overcapture": false
curl --location 'http://localhost:8080/account/postman_merchant_GHAction_77b1a97f-001b-458d-b185-67998995c880/business_profile/pro_ZzurAEZrSqx46L8gNMk5' \
--header 'Content-Type: application/json' \
--header 'api-key: test_admin' \
--data '{
"profile_name": "US_default",
"always_request_overcapture": false
}'
Response
{
"merchant_id": "postman_merchant_GHAction_77b1a97f-001b-458d-b185-67998995c880",
"profile_id": "pro_ZzurAEZrSqx46L8gNMk5",
"profile_name": "US_default",
"return_url": "https://duck.com/success",
"enable_payment_response_hash": true,
"payment_response_hash_key": "iJLfkEZljBCu2mNKSoAp2fOOh84X4WJPBAtkAJE4s4Tqjne78DrKkJUjWcv01PEG",
"redirect_to_merchant_with_http_post": false,
"webhook_details": {
"webhook_version": "1.0.1",
"webhook_username": "ekart_retail",
"webhook_password": "password_ekart@123",
"webhook_url": null,
"payment_created_enabled": true,
"payment_succeeded_enabled": true,
"payment_failed_enabled": true
},
"metadata": null,
"routing_algorithm": null,
"intent_fulfillment_time": 900,
"frm_routing_algorithm": null,
"payout_routing_algorithm": null,
"applepay_verified_domains": null,
"session_expiry": 900,
"payment_link_config": null,
"authentication_connector_details": null,
"use_billing_as_payment_method_billing": true,
"extended_card_info_config": null,
"collect_shipping_details_from_wallet_connector": false,
"collect_billing_details_from_wallet_connector": false,
"always_collect_shipping_details_from_wallet_connector": false,
"always_collect_billing_details_from_wallet_connector": false,
"is_connector_agnostic_mit_enabled": false,
"payout_link_config": null,
"outgoing_webhook_custom_http_headers": null,
"tax_connector_id": null,
"is_tax_connector_enabled": false,
"is_network_tokenization_enabled": false,
"is_auto_retries_enabled": false,
"max_auto_retries_enabled": null,
"is_click_to_pay_enabled": false,
"authentication_product_ids": null,
"always_request_overcapture": false
}
- Create an overcapture payment with stripe
curl --location 'http://localhost:8080/payments' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key: dev_oqtfJBx4JGn0Pmr3ZLtDMyUEzRZQ0IBeqnvImk4W1lbRHnh07rqLSXNTv8JKYk9L' \
--data-raw '{
"amount": 6540,
"currency": "USD",
"confirm": true,
"capture_method": "manual",
"capture_on": "2022-09-10T10:11:12Z",
"amount_to_capture": 6540,
"customer_id": "StripeCustomer",
"email": "[email protected]",
"name": "John Doe",
"phone": "999999999",
"phone_country_code": "+1",
"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": "4242424242424242",
"card_exp_month": "10",
"card_exp_year": "25",
"card_holder_name": "joseph Doe",
"card_cvc": "123"
}
},
"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"
},
"email": "[email protected]"
},
"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"
},
"routing": {
"type": "single",
"data": {
"connector": "stripe",
"merchant_connector_id": "mca_5SMXtr84AcZ8zhBefG8d"
}
}
"overcapture_status": "not_applicable"
}'
Response
{
"payment_id": "pay_FKzjYUzqpSigIfzoXolG",
"merchant_id": "postman_merchant_GHAction_77b1a97f-001b-458d-b185-67998995c880",
"status": "requires_capture",
"amount": 6540,
"net_amount": 6540,
"shipping_cost": null,
"amount_capturable": 6540,
"amount_received": 0,
"connector": "stripe",
"client_secret": "pay_FKzjYUzqpSigIfzoXolG_secret_sB7pumP3GJcc4ZnSvCxX",
"created": "2024-12-23T09:57:04.620Z",
"currency": "USD",
"customer_id": "StripeCustomer",
"customer": {
"id": "StripeCustomer",
"name": "John Doe",
"email": "[email protected]",
"phone": "999999999",
"phone_country_code": "+1"
},
"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": "manual",
"payment_method": "card",
"payment_method_data": {
"card": {
"last4": "4242",
"card_type": null,
"card_network": null,
"card_issuer": null,
"card_issuing_country": null,
"card_isin": "424242",
"card_extended_bin": null,
"card_exp_month": "10",
"card_exp_year": "25",
"card_holder_name": "joseph Doe",
"payment_checks": {
"cvc_check": "pass",
"address_line1_check": "pass",
"address_postal_code_check": "pass"
},
"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": "[email protected]"
},
"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": "StripeCustomer",
"created_at": 1734947824,
"expires": 1734951424,
"secret": "epk_54c122be30324503a3199e33d42fff0f"
},
"manual_retry_allowed": false,
"connector_transaction_id": "pi_3QZ8NpIVaesDjvMP1f6ANdO7",
"frm_message": null,
"metadata": {
"udf1": "value1",
"login_date": "2019-09-10T10:11:12Z",
"new_customer": "true"
},
"connector_metadata": null,
"feature_metadata": null,
"reference_id": "pi_3QZ8NpIVaesDjvMP1f6ANdO7",
"payment_link": null,
"profile_id": "pro_ZzurAEZrSqx46L8gNMk5",
"surcharge_details": null,
"attempt_count": 1,
"merchant_decision": null,
"merchant_connector_id": "mca_5SMXtr84AcZ8zhBefG8d",
"incremental_authorization_allowed": null,
"authorization_count": null,
"incremental_authorizations": null,
"external_authentication_details": null,
"external_3ds_authentication_attempted": false,
"expires_on": "2024-12-23T10:12:04.620Z",
"fingerprint": null,
"browser_info": null,
"payment_method_id": null,
"payment_method_status": null,
"updated": "2024-12-23T09:57:06.130Z",
"split_payments": null,
"frm_metadata": null,
"merchant_order_reference_id": null,
"order_tax_amount": null,
"connector_mandate_id": null,
"overcapture_status": "not_applicable"
}
Hardcoded testcases - cannot be tested in integ/sandbox/prod. These are tests triggered after hardcoding the amount values.
curl --location 'http://localhost:8080/payments' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key: dev_3p8fPUv04vz8PLxkCUOq8UrLy5DPodzOfCPaiCdjl2VWDewZ3L5s3IxXhoGJeBh2' \
--data '{
"amount": 2000,
"currency": "USD",
"confirm": true,
"capture_method": "manual",
"customer_id": "cust_no_pm",
"authentication_type": "no_three_ds",
"payment_method": "card",
"payment_method_type": "debit",
"payment_method_data": {
"card": {
"card_number": "4242424242424242",
"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": "8056594427",
"country_code": "+91"
}
},
"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": "13.232.74.226"
}
,"request_overcapture": "enable"
}'
Response
{
"payment_id": "pay_J8MKhjr4saG0eyjUAaGg",
"merchant_id": "postman_merchant_GHAction_b8c5a022-d24d-4739-879d-718ed959825e",
"status": "requires_capture",
"amount": 2000,
"net_amount": 2000,
"shipping_cost": null,
"amount_capturable": 7000,
"amount_received": 0,
"connector": "stripe",
"client_secret": "pay_J8MKhjr4saG0eyjUAaGg_secret_FGxWJr0vgQ2RGeAZqtOP",
"created": "2025-01-17T08:04:53.891Z",
"currency": "USD",
"customer_id": "cust_no_pm",
"customer": {
"id": "cust_no_pm",
"name": null,
"email": null,
"phone": null,
"phone_country_code": null
},
"description": null,
"refunds": null,
"disputes": null,
"mandate_id": null,
"mandate_data": null,
"setup_future_usage": null,
"off_session": null,
"capture_on": null,
"capture_method": "manual",
"payment_method": "card",
"payment_method_data": {
"card": {
"last4": "4242",
"card_type": null,
"card_network": null,
"card_issuer": null,
"card_issuing_country": null,
"card_isin": "424242",
"card_extended_bin": null,
"card_exp_month": "03",
"card_exp_year": "30",
"card_holder_name": "joseph Doe",
"payment_checks": {
"cvc_check": "pass",
"address_line1_check": "pass",
"address_postal_code_check": "pass"
},
"authentication_data": null
},
"billing": null
},
"payment_token": null,
"shipping": 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": "8056594427",
"country_code": "+91"
},
"email": null
},
"order_details": null,
"email": null,
"name": null,
"phone": null,
"return_url": null,
"authentication_type": "no_three_ds",
"statement_descriptor_name": null,
"statement_descriptor_suffix": null,
"next_action": null,
"cancellation_reason": null,
"error_code": null,
"error_message": null,
"unified_code": null,
"unified_message": null,
"payment_experience": null,
"payment_method_type": "debit",
"connector_label": null,
"business_country": null,
"business_label": "default",
"business_sub_label": null,
"allowed_payment_method_types": null,
"ephemeral_key": {
"customer_id": "cust_no_pm",
"created_at": 1737101093,
"expires": 1737104693,
"secret": "epk_589715ba256940348209ca91c674dbf1"
},
"manual_retry_allowed": false,
"connector_transaction_id": "pi_3QiAXyIVaesDjvMP2VPJ4ZG7",
"frm_message": null,
"metadata": null,
"connector_metadata": null,
"feature_metadata": null,
"reference_id": "pi_3QiAXyIVaesDjvMP2VPJ4ZG7",
"payment_link": null,
"profile_id": "pro_2h3e1fc0m7QCfwBdDyAT",
"surcharge_details": null,
"attempt_count": 1,
"merchant_decision": null,
"merchant_connector_id": "mca_VwsDtrjWEltcLycDi5iP",
"incremental_authorization_allowed": null,
"authorization_count": null,
"incremental_authorizations": null,
"external_authentication_details": null,
"external_3ds_authentication_attempted": false,
"expires_on": "2025-01-17T08:19:53.891Z",
"fingerprint": null,
"browser_info": {
"language": "nl-NL",
"time_zone": 0,
"ip_address": "13.232.74.226",
"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-01-17T08:04:55.587Z",
"split_payments": null,
"frm_metadata": null,
"merchant_order_reference_id": null,
"order_tax_amount": null,
"connector_mandate_id": null,
"overcapture_status": "applicable"
}
Overcapture the authorized amount
{
"payment_id": "pay_J8MKhjr4saG0eyjUAaGg",
"merchant_id": "postman_merchant_GHAction_b8c5a022-d24d-4739-879d-718ed959825e",
"status": "succeeded",
"amount": 2000,
"net_amount": 2000,
"shipping_cost": null,
"amount_capturable": 0,
"amount_received": 7000,
"connector": "stripe",
"client_secret": "pay_J8MKhjr4saG0eyjUAaGg_secret_FGxWJr0vgQ2RGeAZqtOP",
"created": "2025-01-17T08:04:53.891Z",
"currency": "USD",
"customer_id": "cust_no_pm",
"customer": {
"id": "cust_no_pm",
"name": null,
"email": null,
"phone": null,
"phone_country_code": null
},
"description": null,
"refunds": null,
"disputes": null,
"mandate_id": null,
"mandate_data": null,
"setup_future_usage": null,
"off_session": null,
"capture_on": null,
"capture_method": "manual",
"payment_method": "card",
"payment_method_data": {
"card": {
"last4": "4242",
"card_type": null,
"card_network": null,
"card_issuer": null,
"card_issuing_country": null,
"card_isin": "424242",
"card_extended_bin": null,
"card_exp_month": "03",
"card_exp_year": "30",
"card_holder_name": "joseph Doe",
"payment_checks": {
"cvc_check": "pass",
"address_line1_check": "pass",
"address_postal_code_check": "pass"
},
"authentication_data": null
},
"billing": null
},
"payment_token": null,
"shipping": 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": "8056594427",
"country_code": "+91"
},
"email": null
},
"order_details": null,
"email": null,
"name": null,
"phone": null,
"return_url": null,
"authentication_type": "no_three_ds",
"statement_descriptor_name": null,
"statement_descriptor_suffix": null,
"next_action": null,
"cancellation_reason": null,
"error_code": null,
"error_message": null,
"unified_code": null,
"unified_message": null,
"payment_experience": null,
"payment_method_type": "debit",
"connector_label": null,
"business_country": null,
"business_label": "default",
"business_sub_label": null,
"allowed_payment_method_types": null,
"ephemeral_key": null,
"manual_retry_allowed": false,
"connector_transaction_id": "pi_3QiAXyIVaesDjvMP2VPJ4ZG7",
"frm_message": null,
"metadata": null,
"connector_metadata": null,
"feature_metadata": null,
"reference_id": "pi_3QiAXyIVaesDjvMP2VPJ4ZG7",
"payment_link": null,
"profile_id": "pro_2h3e1fc0m7QCfwBdDyAT",
"surcharge_details": null,
"attempt_count": 1,
"merchant_decision": null,
"merchant_connector_id": "mca_VwsDtrjWEltcLycDi5iP",
"incremental_authorization_allowed": null,
"authorization_count": null,
"incremental_authorizations": null,
"external_authentication_details": null,
"external_3ds_authentication_attempted": false,
"expires_on": "2025-01-17T08:19:53.891Z",
"fingerprint": null,
"browser_info": {
"language": "nl-NL",
"time_zone": 0,
"ip_address": "13.232.74.226",
"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-01-17T08:06:06.296Z",
"split_payments": null,
"frm_metadata": null,
"merchant_order_reference_id": null,
"order_tax_amount": null,
"connector_mandate_id": null,
"overcapture_status": "not_applicable"
}
Response
{
"payment_id": "pay_J8MKhjr4saG0eyjUAaGg",
"merchant_id": "postman_merchant_GHAction_b8c5a022-d24d-4739-879d-718ed959825e",
"status": "succeeded",
"amount": 2000,
"net_amount": 2000,
"shipping_cost": null,
"amount_capturable": 0,
"amount_received": 7000,
"connector": "stripe",
"client_secret": "pay_J8MKhjr4saG0eyjUAaGg_secret_FGxWJr0vgQ2RGeAZqtOP",
"created": "2025-01-17T08:04:53.891Z",
"currency": "USD",
"customer_id": "cust_no_pm",
"customer": {
"id": "cust_no_pm",
"name": null,
"email": null,
"phone": null,
"phone_country_code": null
},
"description": null,
"refunds": null,
"disputes": null,
"mandate_id": null,
"mandate_data": null,
"setup_future_usage": null,
"off_session": null,
"capture_on": null,
"capture_method": "manual",
"payment_method": "card",
"payment_method_data": {
"card": {
"last4": "4242",
"card_type": null,
"card_network": null,
"card_issuer": null,
"card_issuing_country": null,
"card_isin": "424242",
"card_extended_bin": null,
"card_exp_month": "03",
"card_exp_year": "30",
"card_holder_name": "joseph Doe",
"payment_checks": {
"cvc_check": "pass",
"address_line1_check": "pass",
"address_postal_code_check": "pass"
},
"authentication_data": null
},
"billing": null
},
"payment_token": null,
"shipping": 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": "8056594427",
"country_code": "+91"
},
"email": null
},
"order_details": null,
"email": null,
"name": null,
"phone": null,
"return_url": null,
"authentication_type": "no_three_ds",
"statement_descriptor_name": null,
"statement_descriptor_suffix": null,
"next_action": null,
"cancellation_reason": null,
"error_code": null,
"error_message": null,
"unified_code": null,
"unified_message": null,
"payment_experience": null,
"payment_method_type": "debit",
"connector_label": null,
"business_country": null,
"business_label": "default",
"business_sub_label": null,
"allowed_payment_method_types": null,
"ephemeral_key": null,
"manual_retry_allowed": false,
"connector_transaction_id": "pi_3QiAXyIVaesDjvMP2VPJ4ZG7",
"frm_message": null,
"metadata": null,
"connector_metadata": null,
"feature_metadata": null,
"reference_id": "pi_3QiAXyIVaesDjvMP2VPJ4ZG7",
"payment_link": null,
"profile_id": "pro_2h3e1fc0m7QCfwBdDyAT",
"surcharge_details": null,
"attempt_count": 1,
"merchant_decision": null,
"merchant_connector_id": "mca_VwsDtrjWEltcLycDi5iP",
"incremental_authorization_allowed": null,
"authorization_count": null,
"incremental_authorizations": null,
"external_authentication_details": null,
"external_3ds_authentication_attempted": false,
"expires_on": "2025-01-17T08:19:53.891Z",
"fingerprint": null,
"browser_info": {
"language": "nl-NL",
"time_zone": 0,
"ip_address": "13.232.74.226",
"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-01-17T08:06:06.296Z",
"split_payments": null,
"frm_metadata": null,
"merchant_order_reference_id": null,
"order_tax_amount": null,
"connector_mandate_id": null,
"overcapture_status": "applicable"
}
Refund
curl --location 'http://localhost:8080/refunds' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key: dev_3p8fPUv04vz8PLxkCUOq8UrLy5DPodzOfCPaiCdjl2VWDewZ3L5s3IxXhoGJeBh2' \
--data '{
"payment_id": "pay_J8MKhjr4saG0eyjUAaGg",
"amount": 6000,
"reason": "Customer returned product",
"refund_type": "instant",
"metadata": {
"udf1": "value1",
"new_customer": "true",
"login_date": "2019-09-10T10:11:12Z"
}
}'
Response
{
"refund_id": "ref_s5sciZjzMcno0invyl2P",
"payment_id": "pay_J8MKhjr4saG0eyjUAaGg",
"amount": 6000,
"currency": "USD",
"status": "succeeded",
"reason": "Customer returned product",
"metadata": {
"udf1": "value1",
"new_customer": "true",
"login_date": "2019-09-10T10:11:12Z"
},
"error_message": null,
"error_code": null,
"unified_code": null,
"unified_message": null,
"created_at": "2025-01-17T08:08:03.680Z",
"updated_at": "2025-01-17T08:08:05.197Z",
"connector": "stripe",
"profile_id": "pro_2h3e1fc0m7QCfwBdDyAT",
"merchant_connector_id": "mca_VwsDtrjWEltcLycDi5iP",
"split_refunds": null
}
Checklist
- [x] I formatted the code
cargo +nightly fmt --all - [x] I addressed lints thrown by
cargo clippy - [ ] I reviewed the submitted code
- [ ] I added unit tests for my changes where possible
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}
PR Reviewer Guide 🔍
(Review updated until commit https://github.com/juspay/hyperswitch/commit/38f0791c7ca6f491f1aa05c2c33de7fce6b3b057)
Here are some key observations to aid the review process:
| ⏱️ Estimated effort to review: 5 🔵🔵🔵🔵🔵 |
| 🧪 No relevant tests |
| 🔒 No security concerns identified |
⚡ Recommended focus areas for reviewMapping Logic
Option<bool> to StripeOvercaptureRequest maps both Some(false) and None to None, but the enum offers an explicit Never variant. Consider whether Some(false) should map to Some(StripeOvercaptureRequest::Never) instead of None to clearly differentiate a skip request from absence of the field. |
Persistent review updated to latest commit https://github.com/juspay/hyperswitch/commit/38f0791c7ca6f491f1aa05c2c33de7fce6b3b057