mirror of
https://github.com/juspay/hyperswitch.git
synced 2025-10-28 04:04:55 +08:00
docs(subscription): add open api specs (#9884)
This commit is contained in:
Jagan
@ -1,10 +1,21 @@
|
||||
use common_enums::connector_enums::InvoiceStatus;
|
||||
use common_types::payments::CustomerAcceptance;
|
||||
use common_utils::{events::ApiEventMetric, types::MinorUnit};
|
||||
use common_utils::{
|
||||
events::ApiEventMetric,
|
||||
id_type::{
|
||||
CustomerId, InvoiceId, MerchantConnectorAccountId, MerchantId, PaymentId, ProfileId,
|
||||
SubscriptionId,
|
||||
},
|
||||
types::{MinorUnit, Url},
|
||||
};
|
||||
use masking::Secret;
|
||||
use utoipa::ToSchema;
|
||||
|
||||
use crate::{
|
||||
enums as api_enums,
|
||||
enums::{
|
||||
AuthenticationType, CaptureMethod, Currency, FutureUsage, IntentStatus, PaymentExperience,
|
||||
PaymentMethod, PaymentMethodType, PaymentType,
|
||||
},
|
||||
mandates::RecurringDetails,
|
||||
payments::{Address, NextActionData, PaymentMethodDataRequest},
|
||||
};
|
||||
@ -28,7 +39,7 @@ pub struct CreateSubscriptionRequest {
|
||||
pub coupon_code: Option<String>,
|
||||
|
||||
/// customer ID associated with this subscription.
|
||||
pub customer_id: common_utils::id_type::CustomerId,
|
||||
pub customer_id: CustomerId,
|
||||
|
||||
/// payment details for the subscription.
|
||||
pub payment_details: CreateSubscriptionPaymentDetails,
|
||||
@ -46,7 +57,7 @@ pub struct CreateSubscriptionRequest {
|
||||
#[derive(Debug, Clone, serde::Serialize, ToSchema)]
|
||||
pub struct SubscriptionResponse {
|
||||
/// Unique identifier for the subscription.
|
||||
pub id: common_utils::id_type::SubscriptionId,
|
||||
pub id: SubscriptionId,
|
||||
|
||||
/// Merchant specific Unique identifier.
|
||||
pub merchant_reference_id: Option<String>,
|
||||
@ -61,19 +72,20 @@ pub struct SubscriptionResponse {
|
||||
pub item_price_id: Option<String>,
|
||||
|
||||
/// Associated profile ID.
|
||||
pub profile_id: common_utils::id_type::ProfileId,
|
||||
pub profile_id: ProfileId,
|
||||
|
||||
/// Optional client secret used for secure client-side interactions.
|
||||
#[schema(value_type = Option<String>)]
|
||||
/// This is a token which expires after 15 minutes, used from the client to authenticate and create sessions from the SDK
|
||||
pub client_secret: Option<Secret<String>>,
|
||||
|
||||
/// Merchant identifier owning this subscription.
|
||||
pub merchant_id: common_utils::id_type::MerchantId,
|
||||
pub merchant_id: MerchantId,
|
||||
|
||||
/// Optional coupon code applied to this subscription.
|
||||
pub coupon_code: Option<String>,
|
||||
|
||||
/// Optional customer ID associated with this subscription.
|
||||
pub customer_id: common_utils::id_type::CustomerId,
|
||||
pub customer_id: CustomerId,
|
||||
|
||||
/// Payment details for the invoice.
|
||||
pub payment: Option<PaymentResponseData>,
|
||||
@ -125,15 +137,15 @@ impl SubscriptionResponse {
|
||||
/// By default, `client_secret`, `coupon_code`, and `customer` fields are `None`.
|
||||
#[allow(clippy::too_many_arguments)]
|
||||
pub fn new(
|
||||
id: common_utils::id_type::SubscriptionId,
|
||||
id: SubscriptionId,
|
||||
merchant_reference_id: Option<String>,
|
||||
status: SubscriptionStatus,
|
||||
plan_id: Option<String>,
|
||||
item_price_id: Option<String>,
|
||||
profile_id: common_utils::id_type::ProfileId,
|
||||
merchant_id: common_utils::id_type::MerchantId,
|
||||
profile_id: ProfileId,
|
||||
merchant_id: MerchantId,
|
||||
client_secret: Option<Secret<String>>,
|
||||
customer_id: common_utils::id_type::CustomerId,
|
||||
customer_id: CustomerId,
|
||||
payment: Option<PaymentResponseData>,
|
||||
invoice: Option<Invoice>,
|
||||
) -> Self {
|
||||
@ -154,7 +166,7 @@ impl SubscriptionResponse {
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, serde::Serialize)]
|
||||
#[derive(Debug, Clone, serde::Serialize, ToSchema)]
|
||||
pub struct GetPlansResponse {
|
||||
pub plan_id: String,
|
||||
pub name: String,
|
||||
@ -162,19 +174,19 @@ pub struct GetPlansResponse {
|
||||
pub price_id: Vec<SubscriptionPlanPrices>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, serde::Serialize)]
|
||||
#[derive(Debug, Clone, serde::Serialize, ToSchema)]
|
||||
pub struct SubscriptionPlanPrices {
|
||||
pub price_id: String,
|
||||
pub plan_id: Option<String>,
|
||||
pub amount: MinorUnit,
|
||||
pub currency: api_enums::Currency,
|
||||
pub currency: Currency,
|
||||
pub interval: PeriodUnit,
|
||||
pub interval_count: i64,
|
||||
pub trial_period: Option<i64>,
|
||||
pub trial_period_unit: Option<PeriodUnit>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, serde::Serialize)]
|
||||
#[derive(Debug, Clone, serde::Serialize, ToSchema)]
|
||||
pub enum PeriodUnit {
|
||||
Day,
|
||||
Week,
|
||||
@ -182,7 +194,8 @@ pub enum PeriodUnit {
|
||||
Year,
|
||||
}
|
||||
|
||||
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
|
||||
/// For Client based calls, SDK will use the client_secret\nin order to call /payment_methods\nClient secret will be generated whenever a new\npayment method is created
|
||||
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize, ToSchema)]
|
||||
pub struct ClientSecret(String);
|
||||
|
||||
impl ClientSecret {
|
||||
@ -199,8 +212,10 @@ impl ClientSecret {
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(serde::Deserialize, serde::Serialize, Debug)]
|
||||
#[derive(serde::Deserialize, serde::Serialize, Debug, ToSchema)]
|
||||
pub struct GetPlansQuery {
|
||||
#[schema(value_type = Option<String>)]
|
||||
/// This is a token which expires after 15 minutes, used from the client to authenticate and create sessions from the SDK
|
||||
pub client_secret: Option<ClientSecret>,
|
||||
pub limit: Option<u32>,
|
||||
pub offset: Option<u32>,
|
||||
@ -215,33 +230,37 @@ impl ApiEventMetric for GetPlansResponse {}
|
||||
pub struct ConfirmSubscriptionPaymentDetails {
|
||||
pub shipping: Option<Address>,
|
||||
pub billing: Option<Address>,
|
||||
pub payment_method: api_enums::PaymentMethod,
|
||||
pub payment_method_type: Option<api_enums::PaymentMethodType>,
|
||||
pub payment_method: PaymentMethod,
|
||||
pub payment_method_type: Option<PaymentMethodType>,
|
||||
pub payment_method_data: PaymentMethodDataRequest,
|
||||
pub customer_acceptance: Option<CustomerAcceptance>,
|
||||
pub payment_type: Option<api_enums::PaymentType>,
|
||||
pub payment_type: Option<PaymentType>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ToSchema)]
|
||||
pub struct CreateSubscriptionPaymentDetails {
|
||||
pub return_url: common_utils::types::Url,
|
||||
pub setup_future_usage: Option<api_enums::FutureUsage>,
|
||||
pub capture_method: Option<api_enums::CaptureMethod>,
|
||||
pub authentication_type: Option<api_enums::AuthenticationType>,
|
||||
pub payment_type: Option<api_enums::PaymentType>,
|
||||
/// The url to which user must be redirected to after completion of the purchase
|
||||
#[schema(value_type = String)]
|
||||
pub return_url: Url,
|
||||
pub setup_future_usage: Option<FutureUsage>,
|
||||
pub capture_method: Option<CaptureMethod>,
|
||||
pub authentication_type: Option<AuthenticationType>,
|
||||
pub payment_type: Option<PaymentType>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ToSchema)]
|
||||
pub struct PaymentDetails {
|
||||
pub payment_method: Option<api_enums::PaymentMethod>,
|
||||
pub payment_method_type: Option<api_enums::PaymentMethodType>,
|
||||
pub payment_method: Option<PaymentMethod>,
|
||||
pub payment_method_type: Option<PaymentMethodType>,
|
||||
pub payment_method_data: Option<PaymentMethodDataRequest>,
|
||||
pub setup_future_usage: Option<api_enums::FutureUsage>,
|
||||
pub setup_future_usage: Option<FutureUsage>,
|
||||
pub customer_acceptance: Option<CustomerAcceptance>,
|
||||
pub return_url: Option<common_utils::types::Url>,
|
||||
pub capture_method: Option<api_enums::CaptureMethod>,
|
||||
pub authentication_type: Option<api_enums::AuthenticationType>,
|
||||
pub payment_type: Option<api_enums::PaymentType>,
|
||||
/// The url to which user must be redirected to after completion of the purchase
|
||||
#[schema(value_type = Option<String>)]
|
||||
pub return_url: Option<Url>,
|
||||
pub capture_method: Option<CaptureMethod>,
|
||||
pub authentication_type: Option<AuthenticationType>,
|
||||
pub payment_type: Option<PaymentType>,
|
||||
}
|
||||
|
||||
// Creating new type for PaymentRequest API call as usage of api_models::PaymentsRequest will result in invalid payment request during serialization
|
||||
@ -249,84 +268,95 @@ pub struct PaymentDetails {
|
||||
#[derive(Debug, Clone, serde::Serialize, ToSchema)]
|
||||
pub struct CreatePaymentsRequestData {
|
||||
pub amount: MinorUnit,
|
||||
pub currency: api_enums::Currency,
|
||||
pub customer_id: Option<common_utils::id_type::CustomerId>,
|
||||
pub currency: Currency,
|
||||
pub customer_id: Option<CustomerId>,
|
||||
pub billing: Option<Address>,
|
||||
pub shipping: Option<Address>,
|
||||
pub profile_id: Option<common_utils::id_type::ProfileId>,
|
||||
pub setup_future_usage: Option<api_enums::FutureUsage>,
|
||||
pub return_url: Option<common_utils::types::Url>,
|
||||
pub capture_method: Option<api_enums::CaptureMethod>,
|
||||
pub authentication_type: Option<api_enums::AuthenticationType>,
|
||||
pub profile_id: Option<ProfileId>,
|
||||
pub setup_future_usage: Option<FutureUsage>,
|
||||
/// The url to which user must be redirected to after completion of the purchase
|
||||
#[schema(value_type = Option<String>)]
|
||||
pub return_url: Option<Url>,
|
||||
pub capture_method: Option<CaptureMethod>,
|
||||
pub authentication_type: Option<AuthenticationType>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, serde::Serialize, ToSchema)]
|
||||
pub struct ConfirmPaymentsRequestData {
|
||||
pub billing: Option<Address>,
|
||||
pub shipping: Option<Address>,
|
||||
pub profile_id: Option<common_utils::id_type::ProfileId>,
|
||||
pub payment_method: api_enums::PaymentMethod,
|
||||
pub payment_method_type: Option<api_enums::PaymentMethodType>,
|
||||
pub profile_id: Option<ProfileId>,
|
||||
pub payment_method: PaymentMethod,
|
||||
pub payment_method_type: Option<PaymentMethodType>,
|
||||
pub payment_method_data: PaymentMethodDataRequest,
|
||||
pub customer_acceptance: Option<CustomerAcceptance>,
|
||||
pub payment_type: Option<api_enums::PaymentType>,
|
||||
pub payment_type: Option<PaymentType>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, serde::Serialize, ToSchema)]
|
||||
pub struct CreateAndConfirmPaymentsRequestData {
|
||||
pub amount: MinorUnit,
|
||||
pub currency: api_enums::Currency,
|
||||
pub customer_id: Option<common_utils::id_type::CustomerId>,
|
||||
pub currency: Currency,
|
||||
pub customer_id: Option<CustomerId>,
|
||||
pub confirm: bool,
|
||||
pub billing: Option<Address>,
|
||||
pub shipping: Option<Address>,
|
||||
pub profile_id: Option<common_utils::id_type::ProfileId>,
|
||||
pub setup_future_usage: Option<api_enums::FutureUsage>,
|
||||
pub return_url: Option<common_utils::types::Url>,
|
||||
pub capture_method: Option<api_enums::CaptureMethod>,
|
||||
pub authentication_type: Option<api_enums::AuthenticationType>,
|
||||
pub payment_method: Option<api_enums::PaymentMethod>,
|
||||
pub payment_method_type: Option<api_enums::PaymentMethodType>,
|
||||
pub profile_id: Option<ProfileId>,
|
||||
pub setup_future_usage: Option<FutureUsage>,
|
||||
/// The url to which user must be redirected to after completion of the purchase
|
||||
#[schema(value_type = Option<String>)]
|
||||
pub return_url: Option<Url>,
|
||||
pub capture_method: Option<CaptureMethod>,
|
||||
pub authentication_type: Option<AuthenticationType>,
|
||||
pub payment_method: Option<PaymentMethod>,
|
||||
pub payment_method_type: Option<PaymentMethodType>,
|
||||
pub payment_method_data: Option<PaymentMethodDataRequest>,
|
||||
pub customer_acceptance: Option<CustomerAcceptance>,
|
||||
pub payment_type: Option<api_enums::PaymentType>,
|
||||
pub payment_type: Option<PaymentType>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ToSchema)]
|
||||
pub struct PaymentResponseData {
|
||||
pub payment_id: common_utils::id_type::PaymentId,
|
||||
pub status: api_enums::IntentStatus,
|
||||
pub payment_id: PaymentId,
|
||||
pub status: IntentStatus,
|
||||
pub amount: MinorUnit,
|
||||
pub currency: api_enums::Currency,
|
||||
pub profile_id: Option<common_utils::id_type::ProfileId>,
|
||||
pub currency: Currency,
|
||||
pub profile_id: Option<ProfileId>,
|
||||
pub connector: Option<String>,
|
||||
/// Identifier for Payment Method
|
||||
#[schema(value_type = Option<String>, example = "pm_01926c58bc6e77c09e809964e72af8c8")]
|
||||
pub payment_method_id: Option<Secret<String>>,
|
||||
pub return_url: Option<common_utils::types::Url>,
|
||||
/// The url to which user must be redirected to after completion of the purchase
|
||||
#[schema(value_type = Option<String>)]
|
||||
pub return_url: Option<Url>,
|
||||
pub next_action: Option<NextActionData>,
|
||||
pub payment_experience: Option<api_enums::PaymentExperience>,
|
||||
pub payment_experience: Option<PaymentExperience>,
|
||||
pub error_code: Option<String>,
|
||||
pub error_message: Option<String>,
|
||||
pub payment_method_type: Option<api_enums::PaymentMethodType>,
|
||||
pub payment_method_type: Option<PaymentMethodType>,
|
||||
#[schema(value_type = Option<String>)]
|
||||
/// This is a token which expires after 15 minutes, used from the client to authenticate and create sessions from the SDK
|
||||
pub client_secret: Option<Secret<String>>,
|
||||
pub billing: Option<Address>,
|
||||
pub shipping: Option<Address>,
|
||||
pub payment_type: Option<api_enums::PaymentType>,
|
||||
pub payment_type: Option<PaymentType>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ToSchema)]
|
||||
pub struct CreateMitPaymentRequestData {
|
||||
pub amount: MinorUnit,
|
||||
pub currency: api_enums::Currency,
|
||||
pub currency: Currency,
|
||||
pub confirm: bool,
|
||||
pub customer_id: Option<common_utils::id_type::CustomerId>,
|
||||
pub customer_id: Option<CustomerId>,
|
||||
pub recurring_details: Option<RecurringDetails>,
|
||||
pub off_session: Option<bool>,
|
||||
pub profile_id: Option<common_utils::id_type::ProfileId>,
|
||||
pub profile_id: Option<ProfileId>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ToSchema)]
|
||||
pub struct ConfirmSubscriptionRequest {
|
||||
/// Client secret for SDK based interaction.
|
||||
#[schema(value_type = Option<String>)]
|
||||
/// This is a token which expires after 15 minutes, used from the client to authenticate and create sessions from the SDK
|
||||
pub client_secret: Option<ClientSecret>,
|
||||
|
||||
/// Payment details for the invoice.
|
||||
@ -354,11 +384,11 @@ pub struct CreateAndConfirmSubscriptionRequest {
|
||||
/// Identifier for the associated item_price_id for the subscription.
|
||||
pub item_price_id: String,
|
||||
|
||||
/// Idenctifier for the coupon code for the subscription.
|
||||
/// Identifier for the coupon code for the subscription.
|
||||
pub coupon_code: Option<String>,
|
||||
|
||||
/// Identifier for customer.
|
||||
pub customer_id: common_utils::id_type::CustomerId,
|
||||
pub customer_id: CustomerId,
|
||||
|
||||
/// Billing address for the subscription.
|
||||
pub billing: Option<Address>,
|
||||
@ -388,7 +418,7 @@ impl ApiEventMetric for CreateAndConfirmSubscriptionRequest {}
|
||||
#[derive(Debug, Clone, serde::Serialize, ToSchema)]
|
||||
pub struct ConfirmSubscriptionResponse {
|
||||
/// Unique identifier for the subscription.
|
||||
pub id: common_utils::id_type::SubscriptionId,
|
||||
pub id: SubscriptionId,
|
||||
|
||||
/// Merchant specific Unique identifier.
|
||||
pub merchant_reference_id: Option<String>,
|
||||
@ -406,13 +436,13 @@ pub struct ConfirmSubscriptionResponse {
|
||||
pub coupon: Option<String>,
|
||||
|
||||
/// Associated profile ID.
|
||||
pub profile_id: common_utils::id_type::ProfileId,
|
||||
pub profile_id: ProfileId,
|
||||
|
||||
/// Payment details for the invoice.
|
||||
pub payment: Option<PaymentResponseData>,
|
||||
|
||||
/// Customer ID associated with this subscription.
|
||||
pub customer_id: Option<common_utils::id_type::CustomerId>,
|
||||
pub customer_id: Option<CustomerId>,
|
||||
|
||||
/// Invoice Details for the subscription.
|
||||
pub invoice: Option<Invoice>,
|
||||
@ -424,37 +454,38 @@ pub struct ConfirmSubscriptionResponse {
|
||||
#[derive(Debug, Clone, serde::Serialize, ToSchema)]
|
||||
pub struct Invoice {
|
||||
/// Unique identifier for the invoice.
|
||||
pub id: common_utils::id_type::InvoiceId,
|
||||
pub id: InvoiceId,
|
||||
|
||||
/// Unique identifier for the subscription.
|
||||
pub subscription_id: common_utils::id_type::SubscriptionId,
|
||||
pub subscription_id: SubscriptionId,
|
||||
|
||||
/// Identifier for the merchant.
|
||||
pub merchant_id: common_utils::id_type::MerchantId,
|
||||
pub merchant_id: MerchantId,
|
||||
|
||||
/// Identifier for the profile.
|
||||
pub profile_id: common_utils::id_type::ProfileId,
|
||||
pub profile_id: ProfileId,
|
||||
|
||||
/// Identifier for the merchant connector account.
|
||||
pub merchant_connector_id: common_utils::id_type::MerchantConnectorAccountId,
|
||||
pub merchant_connector_id: MerchantConnectorAccountId,
|
||||
|
||||
/// Identifier for the Payment.
|
||||
pub payment_intent_id: Option<common_utils::id_type::PaymentId>,
|
||||
pub payment_intent_id: Option<PaymentId>,
|
||||
|
||||
/// Identifier for the Payment method.
|
||||
/// Identifier for Payment Method
|
||||
#[schema(value_type = Option<String>, example = "pm_01926c58bc6e77c09e809964e72af8c8")]
|
||||
pub payment_method_id: Option<String>,
|
||||
|
||||
/// Identifier for the Customer.
|
||||
pub customer_id: common_utils::id_type::CustomerId,
|
||||
pub customer_id: CustomerId,
|
||||
|
||||
/// Invoice amount.
|
||||
pub amount: MinorUnit,
|
||||
|
||||
/// Currency for the invoice payment.
|
||||
pub currency: api_enums::Currency,
|
||||
pub currency: Currency,
|
||||
|
||||
/// Status of the invoice.
|
||||
pub status: common_enums::connector_enums::InvoiceStatus,
|
||||
pub status: InvoiceStatus,
|
||||
}
|
||||
|
||||
impl ApiEventMetric for ConfirmSubscriptionResponse {}
|
||||
@ -477,7 +508,7 @@ pub struct EstimateSubscriptionQuery {
|
||||
/// Identifier for the associated item_price_id for the subscription.
|
||||
pub item_price_id: String,
|
||||
|
||||
/// Idenctifier for the coupon code for the subscription.
|
||||
/// Identifier for the coupon code for the subscription.
|
||||
pub coupon_code: Option<String>,
|
||||
}
|
||||
|
||||
@ -488,15 +519,15 @@ pub struct EstimateSubscriptionResponse {
|
||||
/// Estimated amount to be charged for the invoice.
|
||||
pub amount: MinorUnit,
|
||||
/// Currency for the amount.
|
||||
pub currency: api_enums::Currency,
|
||||
pub currency: Currency,
|
||||
/// Identifier for the associated plan_id.
|
||||
pub plan_id: Option<String>,
|
||||
/// Identifier for the associated item_price_id for the subscription.
|
||||
pub item_price_id: Option<String>,
|
||||
/// Idenctifier for the coupon code for the subscription.
|
||||
/// Identifier for the coupon code for the subscription.
|
||||
pub coupon_code: Option<String>,
|
||||
/// Identifier for customer.
|
||||
pub customer_id: Option<common_utils::id_type::CustomerId>,
|
||||
pub customer_id: Option<CustomerId>,
|
||||
pub line_items: Vec<SubscriptionLineItem>,
|
||||
}
|
||||
|
||||
@ -511,7 +542,7 @@ pub struct SubscriptionLineItem {
|
||||
/// Amount for the line item.
|
||||
pub amount: MinorUnit,
|
||||
/// Currency for the line item
|
||||
pub currency: common_enums::Currency,
|
||||
pub currency: Currency,
|
||||
/// Quantity of the line item.
|
||||
pub quantity: i64,
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user