mirror of
https://github.com/juspay/hyperswitch.git
synced 2025-10-30 01:27:31 +08:00
docs: Improving API Reference (#8194)
Co-authored-by: hyperswitch-bot[bot] <148525504+hyperswitch-bot[bot]@users.noreply.github.com>
This commit is contained in:
GORAKHNATH YADAV
@ -1,24 +1,8 @@
|
||||
/// Payments - Create
|
||||
///
|
||||
/// **Creates a payment object when amount and currency are passed.**
|
||||
/// Creates a payment resource, which represents a customer's intent to pay.
|
||||
/// This endpoint is the starting point for various payment flows:
|
||||
///
|
||||
/// This API is also used to create a mandate by passing the `mandate_object`.
|
||||
///
|
||||
/// Depending on the user journey you wish to achieve, you may opt to complete all the steps in a single request **by attaching a payment method, setting `confirm=true` and `capture_method = automatic`** in the *Payments/Create API* request.
|
||||
///
|
||||
/// Otherwise, To completely process a payment you will have to **create a payment, attach a payment method, confirm and capture funds**. For that you could use the following sequence of API requests -
|
||||
///
|
||||
/// 1. Payments - Create
|
||||
///
|
||||
/// 2. Payments - Update
|
||||
///
|
||||
/// 3. Payments - Confirm
|
||||
///
|
||||
/// 4. Payments - Capture.
|
||||
///
|
||||
/// You will require the 'API - Key' from the Hyperswitch dashboard to make the first call, and use the 'client secret' returned in this API along with your 'publishable key' to make subsequent API calls from your client.
|
||||
///
|
||||
/// This page lists the various combinations in which the Payments - Create API can be used and the details about the various fields in the requests and responses.
|
||||
#[utoipa::path(
|
||||
post,
|
||||
path = "/payments",
|
||||
@ -26,12 +10,12 @@
|
||||
content = PaymentsCreateRequest,
|
||||
examples(
|
||||
(
|
||||
"Create a payment with minimal fields" = (
|
||||
"1. Create a payment with minimal fields" = (
|
||||
value = json!({"amount": 6540,"currency": "USD"})
|
||||
)
|
||||
),
|
||||
(
|
||||
"Create a payment with customer details and metadata" = (
|
||||
"2. Create a payment with customer details and metadata" = (
|
||||
value = json!({
|
||||
"amount": 6540,
|
||||
"currency": "USD",
|
||||
@ -53,7 +37,7 @@
|
||||
)
|
||||
),
|
||||
(
|
||||
"Create a 3DS payment" = (
|
||||
"3. Create a 3DS payment" = (
|
||||
value = json!({
|
||||
"amount": 6540,
|
||||
"currency": "USD",
|
||||
@ -62,7 +46,7 @@
|
||||
)
|
||||
),
|
||||
(
|
||||
"Create a manual capture payment" = (
|
||||
"4. Create a manual capture payment (basic)" = (
|
||||
value = json!({
|
||||
"amount": 6540,
|
||||
"currency": "USD",
|
||||
@ -71,7 +55,7 @@
|
||||
)
|
||||
),
|
||||
(
|
||||
"Create a setup mandate payment" = (
|
||||
"5. Create a setup mandate payment" = (
|
||||
value = json!({
|
||||
"amount": 6540,
|
||||
"currency": "USD",
|
||||
@ -117,7 +101,7 @@
|
||||
)
|
||||
),
|
||||
(
|
||||
"Create a recurring payment with mandate_id" = (
|
||||
"6. Create a recurring payment with mandate_id" = (
|
||||
value = json!({
|
||||
"amount": 6540,
|
||||
"currency": "USD",
|
||||
@ -130,7 +114,7 @@
|
||||
)
|
||||
),
|
||||
(
|
||||
"Create a payment and save the card" = (
|
||||
"7. Create a payment and save the card" = (
|
||||
value = json!({
|
||||
"amount": 6540,
|
||||
"currency": "USD",
|
||||
@ -160,7 +144,7 @@
|
||||
)
|
||||
),
|
||||
(
|
||||
"Create a payment using an already saved card's token" = (
|
||||
"8. Create a payment using an already saved card's token" = (
|
||||
value = json!({
|
||||
"amount": 6540,
|
||||
"currency": "USD",
|
||||
@ -173,7 +157,7 @@
|
||||
)
|
||||
),
|
||||
(
|
||||
"Create a manual capture payment" = (
|
||||
"9. Create a payment with billing details" = (
|
||||
value = json!({
|
||||
"amount": 6540,
|
||||
"currency": "USD",
|
||||
@ -203,7 +187,222 @@
|
||||
),
|
||||
),
|
||||
responses(
|
||||
(status = 200, description = "Payment created", body = PaymentsCreateResponseOpenApi),
|
||||
(status = 200, description = "Payment created", body = PaymentsCreateResponseOpenApi,
|
||||
examples(
|
||||
("1. Response for minimal payment creation (requires payment method)" = (
|
||||
value = json!({
|
||||
"payment_id": "pay_syxxxxxxxxxxxx",
|
||||
"merchant_id": "merchant_myyyyyyyyyyyy",
|
||||
"status": "requires_payment_method",
|
||||
"amount": 6540,
|
||||
"currency": "USD",
|
||||
"client_secret": "pay_syxxxxxxxxxxxx_secret_szzzzzzzzzzz",
|
||||
"created": "2023-10-26T10:00:00Z",
|
||||
"amount_capturable": 6540,
|
||||
"profile_id": "pro_pzzzzzzzzzzz",
|
||||
"attempt_count": 1,
|
||||
"expires_on": "2023-10-26T10:15:00Z"
|
||||
})
|
||||
)),
|
||||
("2. Response for payment with customer details (requires payment method)" = (
|
||||
value = json!({
|
||||
"payment_id": "pay_custmeta_xxxxxxxxxxxx",
|
||||
"merchant_id": "merchant_myyyyyyyyyyyy",
|
||||
"status": "requires_payment_method",
|
||||
"amount": 6540,
|
||||
"currency": "USD",
|
||||
"customer_id": "cus_abcdefgh",
|
||||
"customer": {
|
||||
"id": "cus_abcdefgh",
|
||||
"name": "John Dough",
|
||||
"email": "john@example.com",
|
||||
"phone": "9123456789"
|
||||
},
|
||||
"description": "Its my first payment request",
|
||||
"statement_descriptor_name": "joseph",
|
||||
"statement_descriptor_suffix": "JS",
|
||||
"metadata": {
|
||||
"udf1": "some-value",
|
||||
"udf2": "some-value"
|
||||
},
|
||||
"client_secret": "pay_custmeta_xxxxxxxxxxxx_secret_szzzzzzzzzzz",
|
||||
"created": "2023-10-26T10:05:00Z",
|
||||
"ephemeral_key": {
|
||||
"customer_id": "cus_abcdefgh",
|
||||
"secret": "epk_ephemeralxxxxxxxxxxxx"
|
||||
},
|
||||
"profile_id": "pro_pzzzzzzzzzzz",
|
||||
"attempt_count": 1,
|
||||
"expires_on": "2023-10-26T10:20:00Z"
|
||||
})
|
||||
)),
|
||||
("3. Response for 3DS payment creation (requires payment method)" = (
|
||||
value = json!({
|
||||
"payment_id": "pay_3ds_xxxxxxxxxxxx",
|
||||
"merchant_id": "merchant_myyyyyyyyyyyy",
|
||||
"status": "requires_payment_method",
|
||||
"amount": 6540,
|
||||
"currency": "USD",
|
||||
"authentication_type": "three_ds",
|
||||
"client_secret": "pay_3ds_xxxxxxxxxxxx_secret_szzzzzzzzzzz",
|
||||
"created": "2023-10-26T10:10:00Z",
|
||||
"profile_id": "pro_pzzzzzzzzzzz",
|
||||
"attempt_count": 1,
|
||||
"expires_on": "2023-10-26T10:25:00Z"
|
||||
})
|
||||
)),
|
||||
("4. Response for basic manual capture payment (requires payment method)" = (
|
||||
value = json!({
|
||||
"payment_id": "pay_manualcap_xxxxxxxxxxxx",
|
||||
"merchant_id": "merchant_myyyyyyyyyyyy",
|
||||
"status": "requires_payment_method",
|
||||
"amount": 6540,
|
||||
"currency": "USD",
|
||||
"capture_method": "manual",
|
||||
"client_secret": "pay_manualcap_xxxxxxxxxxxx_secret_szzzzzzzzzzz",
|
||||
"created": "2023-10-26T10:15:00Z",
|
||||
"profile_id": "pro_pzzzzzzzzzzz",
|
||||
"attempt_count": 1,
|
||||
"expires_on": "2023-10-26T10:30:00Z"
|
||||
})
|
||||
)),
|
||||
("5. Response for successful setup mandate payment" = (
|
||||
value = json!({
|
||||
"payment_id": "pay_mandatesetup_xxxxxxxxxxxx",
|
||||
"merchant_id": "merchant_myyyyyyyyyyyy",
|
||||
"status": "succeeded",
|
||||
"amount": 6540,
|
||||
"currency": "USD",
|
||||
"amount_capturable": 0,
|
||||
"amount_received": 6540,
|
||||
"connector": "fauxpay",
|
||||
"customer_id": "StripeCustomer123",
|
||||
"mandate_id": "man_xxxxxxxxxxxx",
|
||||
"mandate_data": {
|
||||
"customer_acceptance": {
|
||||
"acceptance_type": "online",
|
||||
"accepted_at": "1963-05-03T04:07:52.723Z",
|
||||
"online": { "ip_address": "127.0.0.1", "user_agent": "amet irure esse" }
|
||||
},
|
||||
"mandate_type": { "single_use": { "amount": 6540, "currency": "USD" } }
|
||||
},
|
||||
"setup_future_usage": "on_session",
|
||||
"payment_method": "card",
|
||||
"payment_method_data": {
|
||||
"card": { "last4": "4242", "card_exp_month": "10", "card_exp_year": "25", "card_holder_name": "joseph Doe" }
|
||||
},
|
||||
"authentication_type": "no_three_ds",
|
||||
"client_secret": "pay_mandatesetup_xxxxxxxxxxxx_secret_szzzzzzzzzzz",
|
||||
"created": "2023-10-26T10:20:00Z",
|
||||
"ephemeral_key": { "customer_id": "StripeCustomer123", "secret": "epk_ephemeralxxxxxxxxxxxx" },
|
||||
"profile_id": "pro_pzzzzzzzzzzz",
|
||||
"attempt_count": 1,
|
||||
"merchant_connector_id": "mca_mcaconnectorxxxx",
|
||||
"connector_transaction_id": "txn_connectortransidxxxx"
|
||||
})
|
||||
)),
|
||||
("6. Response for successful recurring payment with mandate_id" = (
|
||||
value = json!({
|
||||
"payment_id": "pay_recurring_xxxxxxxxxxxx",
|
||||
"merchant_id": "merchant_myyyyyyyyyyyy",
|
||||
"status": "succeeded",
|
||||
"amount": 6540,
|
||||
"currency": "USD",
|
||||
"amount_capturable": 0,
|
||||
"amount_received": 6540,
|
||||
"connector": "fauxpay",
|
||||
"customer_id": "StripeCustomer",
|
||||
"mandate_id": "{{mandate_id}}",
|
||||
"off_session": true,
|
||||
"payment_method": "card",
|
||||
"authentication_type": "no_three_ds",
|
||||
"client_secret": "pay_recurring_xxxxxxxxxxxx_secret_szzzzzzzzzzz",
|
||||
"created": "2023-10-26T10:22:00Z",
|
||||
"profile_id": "pro_pzzzzzzzzzzz",
|
||||
"attempt_count": 1,
|
||||
"merchant_connector_id": "mca_mcaconnectorxxxx",
|
||||
"connector_transaction_id": "txn_connectortransidxxxx"
|
||||
})
|
||||
)),
|
||||
("7. Response for successful payment with card saved" = (
|
||||
value = json!({
|
||||
"payment_id": "pay_savecard_xxxxxxxxxxxx",
|
||||
"merchant_id": "merchant_myyyyyyyyyyyy",
|
||||
"status": "succeeded",
|
||||
"amount": 6540,
|
||||
"currency": "USD",
|
||||
"amount_capturable": 0,
|
||||
"amount_received": 6540,
|
||||
"connector": "fauxpay",
|
||||
"customer_id": "StripeCustomer123",
|
||||
"setup_future_usage": "on_session",
|
||||
"payment_method": "card",
|
||||
"payment_method_data": {
|
||||
"card": { "last4": "4242", "card_exp_month": "10", "card_exp_year": "25", "card_holder_name": "joseph Doe" }
|
||||
},
|
||||
"authentication_type": "no_three_ds",
|
||||
"client_secret": "pay_savecard_xxxxxxxxxxxx_secret_szzzzzzzzzzz",
|
||||
"created": "2023-10-26T10:25:00Z",
|
||||
"ephemeral_key": { "customer_id": "StripeCustomer123", "secret": "epk_ephemeralxxxxxxxxxxxx" },
|
||||
"profile_id": "pro_pzzzzzzzzzzz",
|
||||
"attempt_count": 1,
|
||||
"merchant_connector_id": "mca_mcaconnectorxxxx",
|
||||
"connector_transaction_id": "txn_connectortransidxxxx",
|
||||
"payment_token": null // Assuming payment_token is for subsequent use, not in this response.
|
||||
})
|
||||
)),
|
||||
("8. Response for successful payment using saved card token" = (
|
||||
value = json!({
|
||||
"payment_id": "pay_token_xxxxxxxxxxxx",
|
||||
"merchant_id": "merchant_myyyyyyyyyyyy",
|
||||
"status": "succeeded",
|
||||
"amount": 6540,
|
||||
"currency": "USD",
|
||||
"amount_capturable": 0,
|
||||
"amount_received": 6540,
|
||||
"connector": "fauxpay",
|
||||
"payment_method": "card",
|
||||
"payment_token": "{{payment_token}}",
|
||||
"client_secret": "pay_token_xxxxxxxxxxxx_secret_szzzzzzzzzzz",
|
||||
"created": "2023-10-26T10:27:00Z",
|
||||
"profile_id": "pro_pzzzzzzzzzzz",
|
||||
"attempt_count": 1,
|
||||
"merchant_connector_id": "mca_mcaconnectorxxxx",
|
||||
"connector_transaction_id": "txn_connectortransidxxxx"
|
||||
})
|
||||
)),
|
||||
("9. Response for payment with billing details (requires payment method)" = (
|
||||
value = json!({
|
||||
"payment_id": "pay_manualbill_xxxxxxxxxxxx",
|
||||
"merchant_id": "merchant_myyyyyyyyyyyy",
|
||||
"status": "requires_payment_method",
|
||||
"amount": 6540,
|
||||
"currency": "USD",
|
||||
"customer_id": "cus_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")
|
||||
),
|
||||
tag = "Payments",
|
||||
@ -294,15 +493,12 @@ pub fn payments_update() {}
|
||||
|
||||
/// Payments - Confirm
|
||||
///
|
||||
/// **Use this API to confirm the payment and forward the payment to the payment processor.**
|
||||
/// Confirms a payment intent that was previously created with `confirm: false`. This action attempts to authorize the payment with the payment processor.
|
||||
///
|
||||
/// Alternatively you can confirm the payment within the *Payments/Create* API by setting `confirm=true`. After confirmation, the payment could either:
|
||||
///
|
||||
/// 1. fail with `failed` status or
|
||||
///
|
||||
/// 2. transition to a `requires_customer_action` status with a `next_action` block or
|
||||
///
|
||||
/// 3. succeed with either `succeeded` in case of automatic capture or `requires_capture` in case of manual capture
|
||||
/// Expected status transitions after confirmation:
|
||||
/// - `succeeded`: If authorization is successful and `capture_method` is `automatic`.
|
||||
/// - `requires_capture`: If authorization is successful and `capture_method` is `manual`.
|
||||
/// - `failed`: If authorization fails.
|
||||
#[utoipa::path(
|
||||
post,
|
||||
path = "/payments/{payment_id}/confirm",
|
||||
@ -352,7 +548,13 @@ pub fn payments_confirm() {}
|
||||
|
||||
/// Payments - Capture
|
||||
///
|
||||
/// To capture the funds for an uncaptured payment
|
||||
/// Captures the funds for a previously authorized payment intent where `capture_method` was set to `manual` and the payment is in a `requires_capture` state.
|
||||
///
|
||||
/// Upon successful capture, the payment status usually transitions to `succeeded`.
|
||||
/// The `amount_to_capture` can be specified in the request body; it must be less than or equal to the payment's `amount_capturable`. If omitted, the full capturable amount is captured.
|
||||
///
|
||||
/// A payment must be in a capturable state (e.g., `requires_capture`). Attempting to capture an already `succeeded` (and fully captured) payment or one in an invalid state will lead to an error.
|
||||
///
|
||||
#[utoipa::path(
|
||||
post,
|
||||
path = "/payments/{payment_id}/capture",
|
||||
|
||||
Reference in New Issue
Block a user