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

refactor(payouts): openAPI schemas and mintlify docs (#5284)

Browse Source 
Co-authored-by: hyperswitch-bot[bot] <148525504+hyperswitch-bot[bot]@users.noreply.github.com>
Co-authored-by: Narayan Bhat <48803246+Narayanbhat166@users.noreply.github.com>
Co-authored-by: Vrishab Srivatsa <136090360+vsrivatsa-juspay@users.noreply.github.com>
Co-authored-by: Prajjwal Kumar <prajjwal.kumar@juspay.in>
This commit is contained in:
Kashif
2024-08-09 18:18:43 +05:30
committed by GitHub
parent 3183a86ecd
commit 942e63d9cd
31 changed files with 1781 additions and 915 deletions
Download Patch File Download Diff File Expand all files Collapse all files

168
crates/api_models/src/payouts.rs
View File

@ -18,7 +18,10 @@ pub enum PayoutRequest {
PayoutRetrieveRequest(PayoutRetrieveRequest),
}
#[derive(Default, Debug, Deserialize, Serialize, Clone, ToSchema)]
#[derive(
Default, Debug, Deserialize, Serialize, Clone, ToSchema, router_derive::PolymorphicSchema,
)]
#[generate_schemas(PayoutsCreateRequest, PayoutUpdateRequest, PayoutConfirmRequest)]
#[serde(deny_unknown_fields)]
pub struct PayoutCreateRequest {
/// Unique identifier for the payout. This ensures idempotency for multiple payouts that have been done by a single merchant. This field is auto generated and is returned in the API response, **not required to be included in the Payout Create/Update Request.**
@ -26,21 +29,27 @@ pub struct PayoutCreateRequest {
value_type = Option<String>,
min_length = 30,
max_length = 30,
example = "payout_mbabizu24mvu3mela5njyhpit4"
example = "187282ab-40ef-47a9-9206-5099ba31e432"
)]
#[remove_in(PayoutsCreateRequest, PayoutUpdateRequest, PayoutConfirmRequest)]
pub payout_id: Option<String>, // TODO: #1321 https://github.com/juspay/hyperswitch/issues/1321
/// This is an identifier for the merchant account. This is inferred from the API key provided during the request, **not required to be included in the Payout Create/Update Request.**
#[schema(max_length = 255, value_type = Option<String>, example = "merchant_1668273825")]
#[remove_in(PayoutsCreateRequest, PayoutUpdateRequest, PayoutConfirmRequest)]
pub merchant_id: Option<id_type::MerchantId>,
/// The payout amount. Amount for the payout in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc.,
#[schema(value_type = i64, example = 1000)]
#[schema(value_type = Option<u64>, example = 1000)]
#[mandatory_in(PayoutsCreateRequest = u64)]
#[remove_in(PayoutsConfirmRequest)]
#[serde(default, deserialize_with = "payments::amount::deserialize_option")]
pub amount: Option<payments::Amount>,
/// The currency of the payout request can be specified here
#[schema(value_type = Currency, example = "USD")]
#[schema(value_type = Option<Currency>, example = "USD")]
#[mandatory_in(PayoutsCreateRequest = Currency)]
#[remove_in(PayoutsConfirmRequest)]
pub currency: Option<api_enums::Currency>,
/// Specifies routing algorithm for selecting a connector
@ -55,11 +64,12 @@ pub struct PayoutCreateRequest {
pub connector: Option<Vec<api_enums::PayoutConnectors>>,
/// This field is used when merchant wants to confirm the payout, thus useful for the payout _Confirm_ request. Ideally merchants should _Create_ a payout, _Update_ it (if required), then _Confirm_ it.
#[schema(value_type = bool, example = true, default = false)]
#[schema(value_type = Option<bool>, example = true, default = false)]
#[remove_in(PayoutConfirmRequest)]
pub confirm: Option<bool>,
/// The payout_type of the payout request can be specified here, this is a mandatory field to _Confirm_ the payout, i.e., should be passed in _Create_ request, if not then should be updated in the payout _Update_ request, then only it can be confirmed.
#[schema(value_type = PayoutType, example = "card")]
#[schema(value_type = Option<PayoutType>, example = "card")]
pub payout_type: Option<api_enums::PayoutType>,
/// The payout method information required for carrying out a payout
@ -67,7 +77,7 @@ pub struct PayoutCreateRequest {
pub payout_method_data: Option<PayoutMethodData>,
/// The billing address for the payout
#[schema(value_type = Option<Object>, example = json!(r#"{
#[schema(value_type = Option<Address>, example = json!(r#"{
"address": {
"line1": "1467",
"line2": "Harrison Street",
@ -83,52 +93,42 @@ pub struct PayoutCreateRequest {
}"#))]
pub billing: Option<payments::Address>,
/// The identifier for the customer object. If not provided the customer ID will be autogenerated.
#[schema(value_type = Option<String>, max_length = 255, example = "cus_y3oqhf46pyzuxjbcn2giaqnb44")]
pub customer_id: Option<id_type::CustomerId>,
/// Set to true to confirm the payout without review, no further action required
#[schema(value_type = bool, example = true, default = false)]
#[schema(value_type = Option<bool>, example = true, default = false)]
pub auto_fulfill: Option<bool>,
/// description: The customer's email address
#[schema(max_length = 255, value_type = Option<String>, example = "johntest@test.com")]
pub email: Option<Email>,
/// The identifier for the customer object. If not provided the customer ID will be autogenerated. _Deprecated: Use customer_id instead._
#[schema(deprecated, value_type = Option<String>, max_length = 255, example = "cus_y3oqhf46pyzuxjbcn2giaqnb44")]
pub customer_id: Option<id_type::CustomerId>,
/// description: The customer's name
#[schema(value_type = Option<String>, max_length = 255, example = "John Test")]
pub name: Option<Secret<String>>,
/// The customer's phone number
#[schema(value_type = Option<String>, max_length = 255, example = "9123456789")]
pub phone: Option<Secret<String>>,
/// The country code for the customer phone number
#[schema(max_length = 255, example = "+1")]
pub phone_country_code: Option<String>,
/// Passing this object creates a new customer or attaches an existing customer to the payout
#[schema(value_type = Option<CustomerDetails>)]
pub customer: Option<payments::CustomerDetails>,
/// It's a token used for client side verification.
#[schema(value_type = String, example = "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo")]
#[schema(value_type = Option<String>, example = "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo")]
#[remove_in(PayoutsCreateRequest)]
#[mandatory_in(PayoutConfirmRequest = String)]
pub client_secret: Option<String>,
/// The URL to redirect after the completion of the operation
#[schema(value_type = String, example = "https://hyperswitch.io")]
#[schema(value_type = Option<String>, example = "https://hyperswitch.io")]
pub return_url: Option<String>,
/// Business country of the merchant for this payout
#[schema(example = "US", value_type = CountryAlpha2)]
/// Business country of the merchant for this payout. _Deprecated: Use profile_id instead._
#[schema(deprecated, example = "US", value_type = Option<CountryAlpha2>)]
pub business_country: Option<api_enums::CountryAlpha2>,
/// Business label of the merchant for this payout
#[schema(example = "food", value_type = Option<String>)]
/// Business label of the merchant for this payout. _Deprecated: Use profile_id instead._
#[schema(deprecated, example = "food", value_type = Option<String>)]
pub business_label: Option<String>,
/// A description of the payout
#[schema(example = "It's my first payout request", value_type = String)]
#[schema(example = "It's my first payout request", value_type = Option<String>)]
pub description: Option<String>,
/// Type of entity to whom the payout is being carried out to, select from the given list of options
#[schema(value_type = PayoutEntityType, example = "Individual")]
#[schema(value_type = Option<PayoutEntityType>, example = "Individual")]
pub entity_type: Option<api_enums::PayoutEntityType>,
/// Specifies whether or not the payout request is recurring
@ -140,18 +140,18 @@ pub struct PayoutCreateRequest {
pub metadata: Option<pii::SecretSerdeValue>,
/// Provide a reference to a stored payout method, used to process the payout.
#[schema(example = "187282ab-40ef-47a9-9206-5099ba31e432")]
#[schema(example = "187282ab-40ef-47a9-9206-5099ba31e432", value_type = Option<String>)]
pub payout_token: Option<String>,
/// The business profile to use for this payout, especially if there are multiple business profiles associated with the account, otherwise default business profile associated with the merchant account will be used.
pub profile_id: Option<String>,
/// The send method which will be required for processing payouts, check options for better understanding.
#[schema(value_type = PayoutSendPriority, example = "instant")]
#[schema(value_type = Option<PayoutSendPriority>, example = "instant")]
pub priority: Option<api_enums::PayoutSendPriority>,
/// Whether to get the payout link (if applicable). Merchant need to specify this during the Payout _Create_, this field can not be updated during Payout _Update_.
#[schema(default = false, example = true)]
#[schema(default = false, example = true, value_type = Option<bool>)]
pub payout_link: Option<bool>,
/// Custom payout link config for the particular payout, if payout link is to be generated.
@ -162,6 +162,30 @@ pub struct PayoutCreateRequest {
/// (900) for 15 mins
#[schema(value_type = Option<u32>, example = 900)]
pub session_expiry: Option<u32>,
/// Customer's email. _Deprecated: Use customer object instead._
#[schema(deprecated, max_length = 255, value_type = Option<String>, example = "johntest@test.com")]
pub email: Option<Email>,
/// Customer's name. _Deprecated: Use customer object instead._
#[schema(deprecated, value_type = Option<String>, max_length = 255, example = "John Test")]
pub name: Option<Secret<String>>,
/// Customer's phone. _Deprecated: Use customer object instead._
#[schema(deprecated, value_type = Option<String>, max_length = 255, example = "9123456789")]
pub phone: Option<Secret<String>>,
/// Customer's phone country code. _Deprecated: Use customer object instead._
#[schema(deprecated, max_length = 255, example = "+1")]
pub phone_country_code: Option<String>,
}
impl PayoutCreateRequest {
pub fn get_customer_id(&self) -> Option<&id_type::CustomerId> {
self.customer_id
.as_ref()
.or(self.customer.as_ref().map(|customer| &customer.id))
}
}
/// Custom payout link config for the particular payout, if payout link is to be generated.
@ -354,7 +378,7 @@ pub struct PayoutCreateResponse {
value_type = String,
min_length = 30,
max_length = 30,
example = "payout_mbabizu24mvu3mela5njyhpit4"
example = "187282ab-40ef-47a9-9206-5099ba31e432"
)]
pub payout_id: String, // TODO: Update this to PayoutIdType similar to PaymentIdType
@ -396,29 +420,17 @@ pub struct PayoutCreateResponse {
}"#))]
pub billing: Option<payments::Address>,
/// The identifier for the customer object. If not provided the customer ID will be autogenerated.
#[schema(value_type = String, max_length = 255, example = "cus_y3oqhf46pyzuxjbcn2giaqnb44")]
pub customer_id: id_type::CustomerId,
/// Set to true to confirm the payout without review, no further action required
#[schema(value_type = bool, example = true, default = false)]
pub auto_fulfill: bool,
/// description: The customer's email address
#[schema(max_length = 255, value_type = Option<String>, example = "johntest@test.com")]
pub email: crypto::OptionalEncryptableEmail,
/// The identifier for the customer object. If not provided the customer ID will be autogenerated.
#[schema(value_type = String, max_length = 255, example = "cus_y3oqhf46pyzuxjbcn2giaqnb44")]
pub customer_id: Option<id_type::CustomerId>,
/// description: The customer's name
#[schema(value_type = Option<String>, max_length = 255, example = "John Test")]
pub name: crypto::OptionalEncryptableName,
/// The customer's phone number
#[schema(value_type = Option<String>, max_length = 255, example = "9123456789")]
pub phone: crypto::OptionalEncryptablePhone,
/// The country code for the customer phone number
#[schema(max_length = 255, example = "+1")]
pub phone_country_code: Option<String>,
/// Passing this object creates a new customer or attaches an existing customer to the payout
#[schema(value_type = Option<CustomerDetailsResponse>)]
pub customer: Option<payments::CustomerDetailsResponse>,
/// It's a token used for client side verification.
#[schema(value_type = String, example = "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo")]
@ -437,7 +449,7 @@ pub struct PayoutCreateResponse {
pub business_label: Option<String>,
/// A description of the payout
#[schema(example = "It's my first payout request", value_type = String)]
#[schema(example = "It's my first payout request", value_type = Option<String>)]
pub description: Option<String>,
/// Type of entity to whom the payout is being carried out to
@ -445,7 +457,7 @@ pub struct PayoutCreateResponse {
pub entity_type: api_enums::PayoutEntityType,
/// Specifies whether or not the payout request is recurring
#[schema(value_type = Option<bool>, default = false)]
#[schema(value_type = bool, default = false)]
pub recurring: bool,
/// You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object.
@ -453,15 +465,15 @@ pub struct PayoutCreateResponse {
pub metadata: Option<pii::SecretSerdeValue>,
/// Current status of the Payout
#[schema(value_type = PayoutStatus, example = Pending)]
#[schema(value_type = PayoutStatus, example = RequiresConfirmation)]
pub status: api_enums::PayoutStatus,
/// If there was an error while calling the connector the error message is received here
#[schema(value_type = String, example = "Failed while verifying the card")]
#[schema(value_type = Option<String>, example = "Failed while verifying the card")]
pub error_message: Option<String>,
/// If there was an error while calling the connectors the code is received here
#[schema(value_type = String, example = "E0001")]
#[schema(value_type = Option<String>, example = "E0001")]
pub error_code: Option<String>,
/// The business profile that is associated with this payout
@ -488,6 +500,22 @@ pub struct PayoutCreateResponse {
/// If payout link was requested, this contains the link's ID and the URL to render the payout widget
#[schema(value_type = Option<PayoutLinkResponse>)]
pub payout_link: Option<PayoutLinkResponse>,
/// Customer's email. _Deprecated: Use customer object instead._
#[schema(deprecated, max_length = 255, value_type = Option<String>, example = "johntest@test.com")]
pub email: crypto::OptionalEncryptableEmail,
/// Customer's name. _Deprecated: Use customer object instead._
#[schema(deprecated, value_type = Option<String>, max_length = 255, example = "John Test")]
pub name: crypto::OptionalEncryptableName,
/// Customer's phone. _Deprecated: Use customer object instead._
#[schema(deprecated, value_type = Option<String>, max_length = 255, example = "9123456789")]
pub phone: crypto::OptionalEncryptablePhone,
/// Customer's phone country code. _Deprecated: Use customer object instead._
#[schema(deprecated, max_length = 255, example = "+1")]
pub phone_country_code: Option<String>,
}
#[derive(
@ -542,7 +570,7 @@ pub struct PayoutRetrieveRequest {
value_type = String,
min_length = 30,
max_length = 30,
example = "payout_mbabizu24mvu3mela5njyhpit4"
example = "187282ab-40ef-47a9-9206-5099ba31e432"
)]
pub payout_id: String,
@ -556,7 +584,10 @@ pub struct PayoutRetrieveRequest {
pub merchant_id: Option<id_type::MerchantId>,
}
#[derive(Default, Debug, Serialize, ToSchema, Clone, Deserialize)]
#[derive(
Default, Debug, Deserialize, Serialize, Clone, ToSchema, router_derive::PolymorphicSchema,
)]
#[generate_schemas(PayoutCancelRequest, PayoutFulfillRequest)]
pub struct PayoutActionRequest {
/// Unique identifier for the payout. This ensures idempotency for multiple payouts
/// that have been done by a single merchant. This field is auto generated and is returned in the API response.
@ -564,8 +595,9 @@ pub struct PayoutActionRequest {
value_type = String,
min_length = 30,
max_length = 30,
example = "payout_mbabizu24mvu3mela5njyhpit4"
example = "187282ab-40ef-47a9-9206-5099ba31e432"
)]
#[serde(skip_deserializing)]
pub payout_id: String,
}
@ -645,7 +677,7 @@ pub struct PayoutListFilterConstraints {
value_type = Option<String>,
min_length = 30,
max_length = 30,
example = "payout_mbabizu24mvu3mela5njyhpit4"
example = "187282ab-40ef-47a9-9206-5099ba31e432"
)]
pub payout_id: Option<String>,
/// The identifier for business profile
@ -687,15 +719,19 @@ pub struct PayoutListResponse {
pub data: Vec<PayoutCreateResponse>,
}
#[derive(Clone, Debug, serde::Serialize)]
#[derive(Clone, Debug, serde::Serialize, ToSchema)]
pub struct PayoutListFilters {
/// The list of available connector filters
#[schema(value_type = Vec<PayoutConnectors>)]
pub connector: Vec<api_enums::PayoutConnectors>,
/// The list of available currency filters
#[schema(value_type = Vec<Currency>)]
pub currency: Vec<common_enums::Currency>,
/// The list of available payout status filters
#[schema(value_type = Vec<PayoutStatus>)]
pub status: Vec<common_enums::PayoutStatus>,
/// The list of available payout method filters
#[schema(value_type = Vec<PayoutType>)]
pub payout_method: Vec<common_enums::PayoutType>,
}