From 0851c6ece574ce961830c14d91e6e2040cb3b286 Mon Sep 17 00:00:00 2001 From: Sayak Bhattacharya Date: Fri, 20 Jun 2025 18:29:46 +0530 Subject: [PATCH] docs(connector): [STRIPE] Added CIT & MIT Examples for API Reference in Stripe Split Payments (#8311) Co-authored-by: Sayak Bhattacharya --- api-reference/v1/openapi_spec_v1.json | 205 +++++++++++++++++++++++--- crates/openapi/src/routes/payments.rs | 193 +++++++++++++++++++++--- 2 files changed, 360 insertions(+), 38 deletions(-) diff --git a/api-reference/v1/openapi_spec_v1.json b/api-reference/v1/openapi_spec_v1.json index 9eac412150..6045147a05 100644 --- a/api-reference/v1/openapi_spec_v1.json +++ b/api-reference/v1/openapi_spec_v1.json @@ -35,13 +35,13 @@ "$ref": "#/components/schemas/PaymentsCreateRequest" }, "examples": { - "1. Create a payment with minimal fields": { + "01. Create a payment with minimal fields": { "value": { "amount": 6540, "currency": "USD" } }, - "2. Create a payment with customer details and metadata": { + "02. Create a payment with customer details and metadata": { "value": { "amount": 6540, "currency": "USD", @@ -61,21 +61,21 @@ "statement_descriptor_suffix": "JS" } }, - "3. Create a 3DS payment": { + "03. Create a 3DS payment": { "value": { "amount": 6540, "authentication_type": "three_ds", "currency": "USD" } }, - "4. Create a manual capture payment (basic)": { + "04. Create a manual capture payment (basic)": { "value": { "amount": 6540, "capture_method": "manual", "currency": "USD" } }, - "5. Create a setup mandate payment": { + "05. Create a setup mandate payment": { "value": { "amount": 6540, "authentication_type": "no_three_ds", @@ -119,7 +119,7 @@ "setup_future_usage": "off_session" } }, - "6. Create a recurring payment with mandate_id": { + "06. Create a recurring payment with mandate_id": { "value": { "amount": 6540, "authentication_type": "no_three_ds", @@ -130,7 +130,7 @@ "off_session": true } }, - "7. Create a payment and save the card": { + "07. Create a payment and save the card": { "value": { "amount": 6540, "authentication_type": "no_three_ds", @@ -158,7 +158,7 @@ "setup_future_usage": "off_session" } }, - "8. Create a payment using an already saved card's token": { + "08. Create a payment using an already saved card's token": { "value": { "amount": 6540, "card_cvc": "123", @@ -169,7 +169,7 @@ "payment_token": "{{payment_token}}" } }, - "9. Create a payment with billing details": { + "09. Create a payment with billing details": { "value": { "amount": 6540, "billing": { @@ -194,6 +194,89 @@ "id": "cus_abcdefgh" } } + }, + "10. Create a Stripe Split Payments CIT call": { + "value": { + "amount": 200, + "amount_to_capture": 200, + "authentication_type": "no_three_ds", + "billing": { + "address": { + "city": "San Fransico", + "country": "US", + "first_name": "joseph", + "last_name": "Doe", + "line1": "1467", + "line2": "Harrison Street", + "line3": "Harrison Street", + "state": "California", + "zip": "94122" + }, + "phone": { + "country_code": "+91", + "number": "9999999999" + } + }, + "capture_method": "automatic", + "confirm": true, + "currency": "USD", + "customer_acceptance": { + "acceptance_type": "offline", + "accepted_at": "1963-05-03T04:07:52.723Z", + "online": { + "ip_address": "125.0.0.1", + "user_agent": "amet irure esse" + } + }, + "customer_id": "StripeCustomer123", + "description": "Its my first payment request", + "name": "John Doe", + "payment_method": "card", + "payment_method_data": { + "card": { + "card_cvc": "123", + "card_exp_month": "09", + "card_exp_year": "25", + "card_holder_name": "joseph Doe", + "card_number": "4242424242424242" + } + }, + "payment_method_type": "debit", + "phone": "999999999", + "phone_country_code": "+65", + "profile_id": "pro_abcdefghijklmnop", + "return_url": "https://hyperswitch.io", + "setup_future_usage": "off_session", + "split_payments": { + "stripe_split_payment": { + "application_fees": 100, + "charge_type": "direct", + "transfer_account_id": "acct_123456789" + } + } + } + }, + "11. Create a Stripe Split Payments MIT call": { + "value": { + "amount": 200, + "confirm": true, + "currency": "USD", + "customer_id": "StripeCustomer123", + "description": "Subsequent Mandate Test Payment (MIT from New CIT Demo)", + "off_session": true, + "profile_id": "pro_abcdefghijklmnop", + "recurring_details": { + "data": "pm_123456789", + "type": "payment_method_id" + }, + "split_payments": { + "stripe_split_payment": { + "application_fees": 11, + "charge_type": "direct", + "transfer_account_id": "acct_123456789" + } + } + } } } } @@ -209,7 +292,7 @@ "$ref": "#/components/schemas/PaymentsCreateResponseOpenApi" }, "examples": { - "1. Response for minimal payment creation (requires payment method)": { + "01. Response for minimal payment creation (requires payment method)": { "value": { "amount": 6540, "amount_capturable": 6540, @@ -224,7 +307,7 @@ "status": "requires_payment_method" } }, - "2. Response for payment with customer details (requires payment method)": { + "02. Response for payment with customer details (requires payment method)": { "value": { "amount": 6540, "attempt_count": 1, @@ -256,7 +339,7 @@ "status": "requires_payment_method" } }, - "3. Response for 3DS payment creation (requires payment method)": { + "03. Response for 3DS payment creation (requires payment method)": { "value": { "amount": 6540, "attempt_count": 1, @@ -271,7 +354,7 @@ "status": "requires_payment_method" } }, - "4. Response for basic manual capture payment (requires payment method)": { + "04. Response for basic manual capture payment (requires payment method)": { "value": { "amount": 6540, "attempt_count": 1, @@ -286,7 +369,7 @@ "status": "requires_payment_method" } }, - "5. Response for successful setup mandate payment": { + "05. Response for successful setup mandate payment": { "value": { "amount": 6540, "amount_capturable": 0, @@ -337,7 +420,7 @@ "status": "succeeded" } }, - "6. Response for successful recurring payment with mandate_id": { + "06. Response for successful recurring payment with mandate_id": { "value": { "amount": 6540, "amount_capturable": 0, @@ -360,7 +443,7 @@ "status": "succeeded" } }, - "7. Response for successful payment with card saved": { + "07. Response for successful payment with card saved": { "value": { "amount": 6540, "amount_capturable": 0, @@ -395,7 +478,7 @@ "status": "succeeded" } }, - "8. Response for successful payment using saved card token": { + "08. Response for successful payment using saved card token": { "value": { "amount": 6540, "amount_capturable": 0, @@ -415,7 +498,7 @@ "status": "succeeded" } }, - "9. Response for payment with billing details (requires payment method)": { + "09. Response for payment with billing details (requires payment method)": { "value": { "amount": 6540, "attempt_count": 1, @@ -455,6 +538,92 @@ "profile_id": "pro_pzzzzzzzzzzz", "status": "requires_payment_method" } + }, + "10. Response for the CIT call for Stripe Split Payments": { + "value": { + "amount": 200, + "attempt_count": 1, + "billing": { + "address": { + "city": "San Fransico", + "country": "US", + "first_name": "joseph", + "last_name": "Doe", + "line1": "1467", + "line2": "Harrison Street", + "state": "California", + "zip": "94122" + }, + "phone": { + "country_code": "+91", + "number": "9123456789" + } + }, + "client_secret": "pay_manualbill_xxxxxxxxxxxx_secret_szzzzzzzzzzz", + "connector_mandate_id": "pm_abcdefgh", + "created": "2023-10-26T10:30:00Z", + "currency": "USD", + "customer": { + "email": "john@example.com", + "id": "cus_abcdefgh", + "name": "John Dough", + "phone": "9123456789" + }, + "customer_id": "cus_abcdefgh", + "ephemeral_key": { + "customer_id": "cus_abcdefgh", + "secret": "epk_ephemeralxxxxxxxxxxxx" + }, + "expires_on": "2023-10-26T10:45:00Z", + "merchant_id": "merchant_myyyyyyyyyyyy", + "payment_id": "pay_manualbill_xxxxxxxxxxxx", + "payment_method_id": "pm_123456789", + "profile_id": "pro_pzzzzzzzzzzz", + "status": "succeeded" + } + }, + "11. Response for the MIT call for Stripe Split Payments": { + "value": { + "amount": 200, + "attempt_count": 1, + "billing": { + "address": { + "city": "San Fransico", + "country": "US", + "first_name": "joseph", + "last_name": "Doe", + "line1": "1467", + "line2": "Harrison Street", + "state": "California", + "zip": "94122" + }, + "phone": { + "country_code": "+91", + "number": "9123456789" + } + }, + "client_secret": "pay_manualbill_xxxxxxxxxxxx_secret_szzzzzzzzzzz", + "connector_mandate_id": "pm_abcdefgh", + "created": "2023-10-26T10:30:00Z", + "currency": "USD", + "customer": { + "email": "john@example.com", + "id": "cus_abcdefgh", + "name": "John Dough", + "phone": "9123456789" + }, + "customer_id": "cus_abcdefgh", + "ephemeral_key": { + "customer_id": "cus_abcdefgh", + "secret": "epk_ephemeralxxxxxxxxxxxx" + }, + "expires_on": "2023-10-26T10:45:00Z", + "merchant_id": "merchant_myyyyyyyyyyyy", + "payment_id": "pay_manualbill_xxxxxxxxxxxx", + "payment_method_id": "pm_123456789", + "profile_id": "pro_pzzzzzzzzzzz", + "status": "succeeded" + } } } } diff --git a/crates/openapi/src/routes/payments.rs b/crates/openapi/src/routes/payments.rs index cf2a61ac85..0f34b21435 100644 --- a/crates/openapi/src/routes/payments.rs +++ b/crates/openapi/src/routes/payments.rs @@ -10,12 +10,12 @@ content = PaymentsCreateRequest, examples( ( - "1. Create a payment with minimal fields" = ( + "01. Create a payment with minimal fields" = ( value = json!({"amount": 6540,"currency": "USD"}) ) ), ( - "2. Create a payment with customer details and metadata" = ( + "02. Create a payment with customer details and metadata" = ( value = json!({ "amount": 6540, "currency": "USD", @@ -37,7 +37,7 @@ ) ), ( - "3. Create a 3DS payment" = ( + "03. Create a 3DS payment" = ( value = json!({ "amount": 6540, "currency": "USD", @@ -46,7 +46,7 @@ ) ), ( - "4. Create a manual capture payment (basic)" = ( + "04. Create a manual capture payment (basic)" = ( value = json!({ "amount": 6540, "currency": "USD", @@ -55,7 +55,7 @@ ) ), ( - "5. Create a setup mandate payment" = ( + "05. Create a setup mandate payment" = ( value = json!({ "amount": 6540, "currency": "USD", @@ -101,7 +101,7 @@ ) ), ( - "6. Create a recurring payment with mandate_id" = ( + "06. Create a recurring payment with mandate_id" = ( value = json!({ "amount": 6540, "currency": "USD", @@ -114,7 +114,7 @@ ) ), ( - "7. Create a payment and save the card" = ( + "07. Create a payment and save the card" = ( value = json!({ "amount": 6540, "currency": "USD", @@ -144,7 +144,7 @@ ) ), ( - "8. Create a payment using an already saved card's token" = ( + "08. Create a payment using an already saved card's token" = ( value = json!({ "amount": 6540, "currency": "USD", @@ -157,7 +157,7 @@ ) ), ( - "9. Create a payment with billing details" = ( + "09. Create a payment with billing details" = ( value = json!({ "amount": 6540, "currency": "USD", @@ -183,13 +183,100 @@ } }) ) - ) + ), + ( + "10. Create a Stripe Split Payments CIT call" = ( + value = json!({ + "amount": 200, + "currency": "USD", + "profile_id": "pro_abcdefghijklmnop", + "confirm": true, + "capture_method": "automatic", + "amount_to_capture": 200, + "customer_id": "StripeCustomer123", + "setup_future_usage": "off_session", + "customer_acceptance": { + "acceptance_type": "offline", + "accepted_at": "1963-05-03T04:07:52.723Z", + "online": { + "ip_address": "125.0.0.1", + "user_agent": "amet irure esse" + } + }, + "authentication_type": "no_three_ds", + "return_url": "https://hyperswitch.io", + "name": "John Doe", + "phone": "999999999", + "phone_country_code": "+65", + "description": "Its my first payment request", + "payment_method": "card", + "payment_method_type": "debit", + "payment_method_data": { + "card": { + "card_number": "4242424242424242", + "card_exp_month": "09", + "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": "9999999999", + "country_code": "+91" + } + }, + "split_payments": { + "stripe_split_payment": { + "charge_type": "direct", + "application_fees": 100, + "transfer_account_id": "acct_123456789" + } + } + }) + ) + ), + ( + "11. Create a Stripe Split Payments MIT call" = ( + value = json!({ + "amount": 200, + "currency": "USD", + "profile_id": "pro_abcdefghijklmnop", + "customer_id": "StripeCustomer123", + "description": "Subsequent Mandate Test Payment (MIT from New CIT Demo)", + "confirm": true, + "off_session": true, + "recurring_details": { + "type": "payment_method_id", + "data": "pm_123456789" + }, + "split_payments": { + "stripe_split_payment": { + "charge_type": "direct", + "application_fees": 11, + "transfer_account_id": "acct_123456789" + } + } + }) + ) + ), ), ), responses( (status = 200, description = "Payment created", body = PaymentsCreateResponseOpenApi, examples( - ("1. Response for minimal payment creation (requires payment method)" = ( + ("01. Response for minimal payment creation (requires payment method)" = ( value = json!({ "payment_id": "pay_syxxxxxxxxxxxx", "merchant_id": "merchant_myyyyyyyyyyyy", @@ -204,7 +291,7 @@ "expires_on": "2023-10-26T10:15:00Z" }) )), - ("2. Response for payment with customer details (requires payment method)" = ( + ("02. Response for payment with customer details (requires payment method)" = ( value = json!({ "payment_id": "pay_custmeta_xxxxxxxxxxxx", "merchant_id": "merchant_myyyyyyyyyyyy", @@ -236,7 +323,7 @@ "expires_on": "2023-10-26T10:20:00Z" }) )), - ("3. Response for 3DS payment creation (requires payment method)" = ( + ("03. Response for 3DS payment creation (requires payment method)" = ( value = json!({ "payment_id": "pay_3ds_xxxxxxxxxxxx", "merchant_id": "merchant_myyyyyyyyyyyy", @@ -251,7 +338,7 @@ "expires_on": "2023-10-26T10:25:00Z" }) )), - ("4. Response for basic manual capture payment (requires payment method)" = ( + ("04. Response for basic manual capture payment (requires payment method)" = ( value = json!({ "payment_id": "pay_manualcap_xxxxxxxxxxxx", "merchant_id": "merchant_myyyyyyyyyyyy", @@ -266,7 +353,7 @@ "expires_on": "2023-10-26T10:30:00Z" }) )), - ("5. Response for successful setup mandate payment" = ( + ("05. Response for successful setup mandate payment" = ( value = json!({ "payment_id": "pay_mandatesetup_xxxxxxxxxxxx", "merchant_id": "merchant_myyyyyyyyyyyy", @@ -301,7 +388,7 @@ "connector_transaction_id": "txn_connectortransidxxxx" }) )), - ("6. Response for successful recurring payment with mandate_id" = ( + ("06. Response for successful recurring payment with mandate_id" = ( value = json!({ "payment_id": "pay_recurring_xxxxxxxxxxxx", "merchant_id": "merchant_myyyyyyyyyyyy", @@ -324,7 +411,7 @@ "connector_transaction_id": "txn_connectortransidxxxx" }) )), - ("7. Response for successful payment with card saved" = ( + ("07. Response for successful payment with card saved" = ( value = json!({ "payment_id": "pay_savecard_xxxxxxxxxxxx", "merchant_id": "merchant_myyyyyyyyyyyy", @@ -351,7 +438,7 @@ "payment_token": null // Assuming payment_token is for subsequent use, not in this response. }) )), - ("8. Response for successful payment using saved card token" = ( + ("08. Response for successful payment using saved card token" = ( value = json!({ "payment_id": "pay_token_xxxxxxxxxxxx", "merchant_id": "merchant_myyyyyyyyyyyy", @@ -371,7 +458,7 @@ "connector_transaction_id": "txn_connectortransidxxxx" }) )), - ("9. Response for payment with billing details (requires payment method)" = ( + ("09. Response for payment with billing details (requires payment method)" = ( value = json!({ "payment_id": "pay_manualbill_xxxxxxxxxxxx", "merchant_id": "merchant_myyyyyyyyyyyy", @@ -400,7 +487,73 @@ "attempt_count": 1, "expires_on": "2023-10-26T10:45:00Z" }) - )) + )), + + ("10. Response for the CIT call for Stripe Split Payments" = ( + value = json!({ + "payment_id": "pay_manualbill_xxxxxxxxxxxx", + "merchant_id": "merchant_myyyyyyyyyyyy", + "status": "succeeded", + "amount": 200, + "currency": "USD", + "customer_id": "cus_abcdefgh", + "payment_method_id": "pm_123456789", + "connector_mandate_id": "pm_abcdefgh", + "customer": { + "id": "cus_abcdefgh", + "name": "John Dough", + "email": "john@example.com", + "phone": "9123456789" + }, + "billing": { + "address": { + "line1": "1467", "line2": "Harrison Street", "city": "San Fransico", + "state": "California", "zip": "94122", "country": "US", + "first_name": "joseph", "last_name": "Doe" + }, + "phone": { "number": "9123456789", "country_code": "+91" } + }, + "client_secret": "pay_manualbill_xxxxxxxxxxxx_secret_szzzzzzzzzzz", + "created": "2023-10-26T10:30:00Z", + "ephemeral_key": { "customer_id": "cus_abcdefgh", "secret": "epk_ephemeralxxxxxxxxxxxx" }, + "profile_id": "pro_pzzzzzzzzzzz", + "attempt_count": 1, + "expires_on": "2023-10-26T10:45:00Z" + }) + )), + + ("11. Response for the MIT call for Stripe Split Payments" = ( + value = json!({ + "payment_id": "pay_manualbill_xxxxxxxxxxxx", + "merchant_id": "merchant_myyyyyyyyyyyy", + "status": "succeeded", + "amount": 200, + "currency": "USD", + "customer_id": "cus_abcdefgh", + "payment_method_id": "pm_123456789", + "connector_mandate_id": "pm_abcdefgh", + "customer": { + "id": "cus_abcdefgh", + "name": "John Dough", + "email": "john@example.com", + "phone": "9123456789" + }, + "billing": { + "address": { + "line1": "1467", "line2": "Harrison Street", "city": "San Fransico", + "state": "California", "zip": "94122", "country": "US", + "first_name": "joseph", "last_name": "Doe" + }, + "phone": { "number": "9123456789", "country_code": "+91" } + }, + "client_secret": "pay_manualbill_xxxxxxxxxxxx_secret_szzzzzzzzzzz", + "created": "2023-10-26T10:30:00Z", + "ephemeral_key": { "customer_id": "cus_abcdefgh", "secret": "epk_ephemeralxxxxxxxxxxxx" }, + "profile_id": "pro_pzzzzzzzzzzz", + "attempt_count": 1, + "expires_on": "2023-10-26T10:45:00Z" + }) + )) ) ), (status = 400, description = "Missing Mandatory fields")