rust/hyperswitch
1
0
Fork 0
mirror of https://github.com/juspay/hyperswitch.git synced 2025-10-29 00:49:42 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: Improving API Reference (#8194)

Browse Source 
Co-authored-by: hyperswitch-bot[bot] <148525504+hyperswitch-bot[bot]@users.noreply.github.com>
This commit is contained in:
GORAKHNATH YADAV
2025-06-11 15:24:45 +05:30
committed by GitHub
parent ff5b2e8e95
commit 5ce2ab2d05
9 changed files with 1399 additions and 673 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
crates/api_models/src/payments.rs
View File

@ -73,7 +73,6 @@ pub struct ConnectorCode {
pub connector: api_enums::Connector,
pub code: String,
}
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ToSchema, PartialEq, Eq)]
pub struct BankCodeResponse {
#[schema(value_type = Vec<BankNames>)]
@ -852,23 +851,23 @@ impl AmountDetailsUpdate {
#[generate_schemas(PaymentsCreateRequest, PaymentsUpdateRequest, PaymentsConfirmRequest)]
#[serde(deny_unknown_fields)]
pub struct PaymentsRequest {
/// The payment amount. Amount for the payment in the lowest denomination of the currency, (i.e) in cents for USD denomination, in yen for JPY denomination etc. E.g., Pass 100 to charge $1.00 and 1 for 1¥ since ¥ is a zero-decimal currency. Read more about [the Decimal and Non-Decimal Currencies](https://github.com/juspay/hyperswitch/wiki/Decimal-and-Non%E2%80%90Decimal-Currencies)
/// The primary amount for the payment, provided in the lowest denomination of the specified currency (e.g., 6540 for $65.40 USD). This field is mandatory for creating a payment.
#[schema(value_type = Option<u64>, example = 6540)]
#[serde(default, deserialize_with = "amount::deserialize_option")]
#[mandatory_in(PaymentsCreateRequest = u64)]
// Makes the field mandatory in PaymentsCreateRequest
pub amount: Option<Amount>,
/// Total tax amount applicable to the order
/// Total tax amount applicable to the order, in the lowest denomination of the currency.
#[schema(value_type = Option<i64>, example = 6540)]
pub order_tax_amount: Option<MinorUnit>,
/// The three letter ISO currency code in uppercase. Eg: 'USD' to charge US Dollars
/// The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the payment amount. This field is mandatory for creating a payment.
#[schema(example = "USD", value_type = Option<Currency>)]
#[mandatory_in(PaymentsCreateRequest = Currency)]
pub currency: Option<api_enums::Currency>,
/// The Amount to be captured / debited from the users payment method. It shall be in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc., If not provided, the default amount_to_capture will be the payment amount. Also, it must be less than or equal to the original payment account.
/// The amount to be captured from the user's payment method, in the lowest denomination. If not provided, and `capture_method` is `automatic`, the full payment `amount` will be captured. If `capture_method` is `manual`, this can be specified in the `/capture` call. Must be less than or equal to the authorized amount.
#[schema(value_type = Option<i64>, example = 6540)]
pub amount_to_capture: Option<MinorUnit>,
@ -876,8 +875,7 @@ pub struct PaymentsRequest {
#[schema(value_type = Option<i64>, example = 6540)]
pub shipping_cost: Option<MinorUnit>,
/// Unique identifier for the payment. This ensures idempotency for multiple payments
/// that have been done by a single merchant. The value for this field can be specified in the request, it will be auto generated otherwise and returned in the API response.
/// Optional. A merchant-provided unique identifier for the payment, contains 30 characters long (e.g., "pay_mbabizu24mvu3mela5njyhpit4"). If provided, it ensures idempotency for the payment creation request. If omitted, Hyperswitch generates a unique ID for the payment.
#[schema(
value_type = Option<String>,
min_length = 30,
@ -920,7 +918,7 @@ pub struct PaymentsRequest {
#[remove_in(PaymentsUpdateRequest, PaymentsCreateRequest, PaymentsConfirmRequest)]
pub capture_on: Option<PrimitiveDateTime>,
/// Whether to confirm the payment (if applicable). It can be used to completely process a payment by attaching a payment method, setting `confirm=true` and `capture_method = automatic` in the *Payments/Create API* request itself.
/// If set to `true`, Hyperswitch attempts to confirm and authorize the payment immediately after creation, provided sufficient payment method details are included. If `false` or omitted (default is `false`), the payment is created with a status such as `requires_payment_method` or `requires_confirmation`, and a separate `POST /payments/{payment_id}/confirm` call is necessary to proceed with authorization.
#[schema(default = false, example = true)]
pub confirm: Option<bool>,
@ -959,11 +957,11 @@ pub struct PaymentsRequest {
#[schema(example = true)]
pub off_session: Option<bool>,
/// A description for the payment
/// An arbitrary string attached to the payment. Often useful for displaying to users or for your own internal record-keeping.
#[schema(example = "It's my first payment request")]
pub description: Option<String>,
/// The URL to which you want the user to be redirected after the completion of the payment operation
/// The URL to redirect the customer to after they complete the payment process or authentication. This is crucial for flows that involve off-site redirection (e.g., 3DS, some bank redirects, wallet payments).
#[schema(value_type = Option<String>, example = "https://hyperswitch.io", max_length = 2048)]
pub return_url: Option<Url>,
@ -1136,9 +1134,7 @@ pub struct PaymentsRequest {
#[schema(value_type = Option<bool>, default = false)]
pub request_extended_authorization: Option<RequestExtendedAuthorizationBool>,
/// Merchant's identifier for the payment/invoice. This will be sent to the connector
/// if the connector provides support to accept multiple reference ids.
/// In case the connector supports only one reference id, Hyperswitch's Payment ID will be sent as reference.
/// Your unique identifier for this payment or order. This ID helps you reconcile payments on your system. If provided, it is passed to the connector if supported.
#[schema(
value_type = Option<String>,
max_length = 255,
@ -1472,7 +1468,7 @@ impl RequestSurchargeDetails {
#[cfg(feature = "v1")]
#[derive(Debug, serde::Serialize, Clone, PartialEq, ToSchema, router_derive::PolymorphicSchema)]
pub struct PaymentAttemptResponse {
/// Unique identifier for the attempt
/// A unique identifier for this specific payment attempt.
pub attempt_id: String,
/// The status of the attempt
#[schema(value_type = AttemptStatus, example = "charged")]
@ -1486,9 +1482,9 @@ pub struct PaymentAttemptResponse {
/// The currency of the amount of the payment attempt
#[schema(value_type = Option<Currency>, example = "USD")]
pub currency: Option<enums::Currency>,
/// The connector used for the payment
/// The name of the payment connector (e.g., 'stripe', 'adyen') used for this attempt.
pub connector: Option<String>,
/// If there was an error while calling the connector, the error message is received here
/// A human-readable message from the connector explaining the error, if one occurred during this payment attempt.
pub error_message: Option<String>,
/// The payment method that is to be used
#[schema(value_type = Option<PaymentMethod>, example = "bank_transfer")]
@ -1511,11 +1507,11 @@ pub struct PaymentAttemptResponse {
pub modified_at: PrimitiveDateTime,
/// If the payment was cancelled the reason will be provided here
pub cancellation_reason: Option<String>,
/// A unique identifier to link the payment to a mandate, can be use instead of payment_method_data
/// If this payment attempt is associated with a mandate (e.g., for a recurring or subsequent payment), this field will contain the ID of that mandate.
pub mandate_id: Option<String>,
/// If there was an error while calling the connectors the error code is received here
/// The error code returned by the connector if this payment attempt failed. This code is specific to the connector.
pub error_code: Option<String>,
/// Provide a reference to a stored payment method
/// If a tokenized (saved) payment method was used for this attempt, this field contains the payment token representing that payment method.
pub payment_token: Option<String>,
/// Additional data related to some connectors
pub connector_metadata: Option<serde_json::Value>,
@ -1525,7 +1521,7 @@ pub struct PaymentAttemptResponse {
/// Payment Method Type
#[schema(value_type = Option<PaymentMethodType>, example = "google_pay")]
pub payment_method_type: Option<enums::PaymentMethodType>,
/// Reference to the payment at connector side
/// The connector's own reference or transaction ID for this specific payment attempt. Useful for reconciliation with the connector.
#[schema(value_type = Option<String>, example = "993672945374576J")]
pub reference_id: Option<String>,
/// (This field is not live yet)Error code unified across the connectors is received here if there was an error while calling connector
@ -1647,7 +1643,7 @@ pub struct PaymentAttemptRevenueRecoveryData {
Default, Debug, serde::Serialize, Clone, PartialEq, ToSchema, router_derive::PolymorphicSchema,
)]
pub struct CaptureResponse {
/// Unique identifier for the capture
/// A unique identifier for this specific capture operation.
pub capture_id: String,
/// The status of the capture
#[schema(value_type = CaptureStatus, example = "charged")]
@ -1658,21 +1654,21 @@ pub struct CaptureResponse {
/// The currency of the amount of the capture
#[schema(value_type = Option<Currency>, example = "USD")]
pub currency: Option<enums::Currency>,
/// The connector used for the payment
/// The name of the payment connector that processed this capture.
pub connector: String,
/// Unique identifier for the parent attempt on which this capture is made
/// The ID of the payment attempt that was successfully authorized and subsequently captured by this operation.
pub authorized_attempt_id: String,
/// A unique identifier for this capture provided by the connector
pub connector_capture_id: Option<String>,
/// Sequence number of this capture, in the series of captures made for the parent attempt
pub capture_sequence: i16,
/// If there was an error while calling the connector the error message is received here
/// A human-readable message from the connector explaining why this capture operation failed, if applicable.
pub error_message: Option<String>,
/// If there was an error while calling the connectors the code is received here
/// The error code returned by the connector if this capture operation failed. This code is connector-specific.
pub error_code: Option<String>,
/// If there was an error while calling the connectors the reason is received here
/// A more detailed reason from the connector explaining the capture failure, if available.
pub error_reason: Option<String>,
/// Reference to the capture at connector side
/// The connector's own reference or transaction ID for this specific capture operation. Useful for reconciliation.
pub reference_id: Option<String>,
}
@ -4314,23 +4310,23 @@ impl Address {
#[derive(Clone, Default, Debug, Eq, serde::Deserialize, serde::Serialize, PartialEq, ToSchema)]
#[serde(deny_unknown_fields)]
pub struct AddressDetails {
/// The address city
/// The city, district, suburb, town, or village of the address.
#[schema(max_length = 50, example = "New York")]
pub city: Option<String>,
/// The two-letter ISO country code for the address
/// The two-letter ISO 3166-1 alpha-2 country code (e.g., US, GB).
#[schema(value_type = Option<CountryAlpha2>, example = "US")]
pub country: Option<api_enums::CountryAlpha2>,
/// The first line of the address
/// The first line of the street address or P.O. Box.
#[schema(value_type = Option<String>, max_length = 200, example = "123, King Street")]
pub line1: Option<Secret<String>>,
/// The second line of the address
/// The second line of the street address or P.O. Box (e.g., apartment, suite, unit, or building).
#[schema(value_type = Option<String>, max_length = 50, example = "Powelson Avenue")]
pub line2: Option<Secret<String>>,
/// The third line of the address
/// The third line of the street address, if applicable.
#[schema(value_type = Option<String>, max_length = 50, example = "Bridgewater")]
pub line3: Option<Secret<String>>,
@ -4424,22 +4420,22 @@ pub struct PhoneDetails {
#[cfg(feature = "v1")]
#[derive(Debug, Clone, Default, Eq, PartialEq, serde::Deserialize, serde::Serialize, ToSchema)]
pub struct PaymentsCaptureRequest {
/// The unique identifier for the payment
/// The unique identifier for the payment being captured. This is taken from the path parameter.
#[serde(skip_deserializing)]
pub payment_id: id_type::PaymentId,
/// The unique identifier for the merchant
/// The unique identifier for the merchant. This is usually inferred from the API key.
#[schema(value_type = Option<String>)]
pub merchant_id: Option<id_type::MerchantId>,
/// The Amount to be captured/ debited from the user's payment method. If not passed the full amount will be captured.
#[schema(value_type = i64, example = 6540)]
/// The amount to capture, in the lowest denomination of the currency. If omitted, the entire `amount_capturable` of the payment will be captured. Must be less than or equal to the current `amount_capturable`.
#[schema(value_type = Option<i64>, example = 6540)]
pub amount_to_capture: Option<MinorUnit>,
/// Decider to refund the uncaptured amount
/// Decider to refund the uncaptured amount. (Currently not fully supported or behavior may vary by connector).
pub refund_uncaptured_amount: Option<bool>,
/// Provides information about a card payment that customers see on their statements.
/// A dynamic suffix that appears on your customer's credit card statement. This is concatenated with the (shortened) descriptor prefix set on your account to form the complete statement descriptor. The combined length should not exceed connector-specific limits (typically 22 characters).
pub statement_descriptor_suffix: Option<String>,
/// Concatenated with the statement descriptor suffix that’s set on the account to form the complete statement descriptor.
/// An optional prefix for the statement descriptor that appears on your customer's credit card statement. This can override the default prefix set on your merchant account. The combined length of prefix and suffix should not exceed connector-specific limits (typically 22 characters).
pub statement_descriptor_prefix: Option<String>,
/// Merchant connector details used to make payments.
/// Merchant connector details used to make payments. (Deprecated)
#[schema(value_type = Option<MerchantConnectorDetailsWrap>, deprecated)]
pub merchant_connector_details: Option<admin::MerchantConnectorDetailsWrap>,
}
@ -4824,28 +4820,28 @@ pub struct PaymentsResponse {
#[schema(value_type = Option<i64>, example = 6540)]
pub shipping_cost: Option<MinorUnit>,
/// The maximum amount that could be captured from the payment
/// The amount (in minor units) that can still be captured for this payment. This is relevant when `capture_method` is `manual`. Once fully captured, or if `capture_method` is `automatic` and payment succeeded, this will be 0.
#[schema(value_type = i64, minimum = 100, example = 6540)]
pub amount_capturable: MinorUnit,
/// The amount which is already captured from the payment, this helps in the cases where merchants can't capture all capturable amount at once.
/// The total amount (in minor units) that has been captured for this payment. For `fauxpay` sandbox connector, this might reflect the authorized amount if `status` is `succeeded` even if `capture_method` was `manual`.
#[schema(value_type = Option<i64>, example = 6540)]
pub amount_received: Option<MinorUnit>,
/// The connector used for the payment
/// The name of the payment connector (e.g., 'stripe', 'adyen') that processed or is processing this payment.
#[schema(example = "stripe")]
pub connector: Option<String>,
/// It's a token used for client side verification.
/// A secret token unique to this payment intent. It is primarily used by client-side applications (e.g., Hyperswitch SDKs) to authenticate actions like confirming the payment or handling next actions. This secret should be handled carefully and not exposed publicly beyond its intended client-side use.
#[schema(value_type = Option<String>, example = "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo")]
pub client_secret: Option<Secret<String>>,
/// Time when the payment was created
/// Timestamp indicating when this payment intent was created, in ISO 8601 format.
#[schema(example = "2022-09-10T10:11:12Z")]
#[serde(with = "common_utils::custom_serde::iso8601::option")]
pub created: Option<PrimitiveDateTime>,
/// The currency of the amount of the payment
/// Three-letter ISO currency code (e.g., USD, EUR) for the payment amount.
#[schema(value_type = Currency, example = "USD")]
pub currency: String,
@ -4862,11 +4858,11 @@ pub struct PaymentsResponse {
pub customer: Option<CustomerDetailsResponse>,
/// A description of the payment
/// An arbitrary string providing a description for the payment, often useful for display or internal record-keeping.
#[schema(example = "It's my first payment request")]
pub description: Option<String>,
/// List of refunds that happened on this intent, as same payment intent can have multiple refund requests depending on the nature of order
/// An array of refund objects associated with this payment. Empty or null if no refunds have been processed.
#[schema(value_type = Option<Vec<RefundResponse>>)]
pub refunds: Option<Vec<refunds::RefundResponse>>,
@ -4968,17 +4964,17 @@ pub struct PaymentsResponse {
#[schema(max_length = 255, example = "Payment for shoes purchase")]
pub statement_descriptor_suffix: Option<String>,
/// Additional information required for redirection
/// If the payment requires further action from the customer (e.g., 3DS authentication, redirect to a bank page), this object will contain the necessary information for the client to proceed. Null if no further action is needed from the customer at this stage.
pub next_action: Option<NextActionData>,
/// If the payment was cancelled the reason will be provided here
/// If the payment intent was cancelled, this field provides a textual reason for the cancellation (e.g., "requested_by_customer", "abandoned").
pub cancellation_reason: Option<String>,
/// If there was an error while calling the connectors the code is received here
/// The connector-specific error code from the last failed payment attempt associated with this payment intent.
#[schema(example = "E0001")]
pub error_code: Option<String>,
/// If there was an error while calling the connector the error message is received here
/// A human-readable error message from the last failed payment attempt associated with this payment intent.
#[schema(example = "Failed while verifying the card")]
pub error_message: Option<String>,
@ -4990,26 +4986,26 @@ pub struct PaymentsResponse {
#[remove_in(PaymentsCreateResponseOpenApi)]
pub unified_message: Option<String>,
/// Payment Experience for the current payment
/// Describes the type of payment flow experienced by the customer (e.g., 'redirect_to_url', 'invoke_sdk', 'display_qr_code').
#[schema(value_type = Option<PaymentExperience>, example = "redirect_to_url")]
pub payment_experience: Option<api_enums::PaymentExperience>,
/// Can be used to specify the Payment Method Type
/// The specific payment method subtype used for this payment (e.g., 'credit_card', 'klarna', 'gpay'). This provides more granularity than the 'payment_method' field.
#[schema(value_type = Option<PaymentMethodType>, example = "gpay")]
pub payment_method_type: Option<api_enums::PaymentMethodType>,
/// The connector used for this payment along with the country and business details
/// A label identifying the specific merchant connector account (MCA) used for this payment. This often combines the connector name, business country, and a custom label (e.g., "stripe_US_primary").
#[schema(example = "stripe_US_food")]
pub connector_label: Option<String>,
/// The business country of merchant for this payment
/// The two-letter ISO country code (e.g., US, GB) of the business unit or profile under which this payment was processed.
#[schema(value_type = Option<CountryAlpha2>, example = "US")]
pub business_country: Option<api_enums::CountryAlpha2>,
/// The business label of merchant for this payment
/// The label identifying the specific business unit or profile under which this payment was processed by the merchant.
pub business_label: Option<String>,
/// The business_sub_label for this payment
/// An optional sub-label for further categorization of the business unit or profile used for this payment.
pub business_sub_label: Option<String>,
/// Allowed Payment Method Types for a given PaymentIntent
@ -5092,7 +5088,7 @@ pub struct PaymentsResponse {
/// The browser information used for this payment
pub browser_info: Option<serde_json::Value>,
/// Identifier for Payment Method used for the payment
/// A unique identifier for the payment method used in this payment. If the payment method was saved or tokenized, this ID can be used to reference it for future transactions or recurring payments.
pub payment_method_id: Option<String>,
/// Payment Method Status, refers to the status of the payment method used for this payment.
@ -5330,7 +5326,6 @@ pub struct PaymentsConfirmIntentRequest {
#[schema(value_type = Option<String>)]
pub payment_method_id: Option<id_type::GlobalPaymentMethodId>,
/// Provide a reference to a stored payment method
#[schema(example = "187282ab-40ef-47a9-9206-5099ba31e432")]
pub payment_token: Option<String>,
}
@ -6414,9 +6409,9 @@ pub struct PaymentsRetrieveRequest {
pub merchant_id: Option<id_type::MerchantId>,
/// Decider to enable or disable the connector call for retrieve request
pub force_sync: bool,
/// The parameters passed to a retrieve request
/// Optional query parameters that might be specific to a connector or flow, passed through during the retrieve operation. Use with caution and refer to specific connector documentation if applicable.
pub param: Option<String>,
/// The name of the connector
/// Optionally specifies the connector to be used for a 'force_sync' retrieve operation. If provided, Hyperswitch will attempt to sync the payment status from this specific connector.
pub connector: Option<String>,
/// Merchant connector details used to make payments.
#[schema(value_type = Option<MerchantConnectorDetailsWrap>)]
@ -7563,6 +7558,7 @@ pub struct PaymentsManualUpdateResponse {
}
#[derive(Debug, serde::Serialize, serde::Deserialize, Clone, ToSchema)]
/// Indicates if 3DS method data was successfully completed or not
pub enum ThreeDsCompletionIndicator {
/// 3DS method successfully completed
#[serde(rename = "Y")]