Added Payment Method API descriptions

juspay · Nov 13, 2024 · 9e2c9c1 · 9e2c9c1
1 parent e6d5371
commit 9e2c9c1
Show file tree

Hide file tree

Showing 3 changed files with 91 additions and 108 deletions.
diff --git a/api-reference-v2/mint.json b/api-reference-v2/mint.json
@@ -48,14 +48,14 @@
     {
       "group": "Payment Methods",
       "pages": [
-        "api-reference/payment-methods/list-customer-saved-payment-methods-for-a-payment",
-        "api-reference/payment-methods/list-payment-methods-for-a-customer",
-        "api-reference/payment-methods/payment-method--confirm-intent",
-        "api-reference/payment-methods/payment-method--create-intent",
         "api-reference/payment-methods/payment-method--create",
-        "api-reference/payment-methods/payment-method--delete",
         "api-reference/payment-methods/payment-method--retrieve",
-        "api-reference/payment-methods/payment-method--update"
+        "api-reference/payment-methods/payment-method--update",
+        "api-reference/payment-methods/payment-method--delete",
+        "api-reference/payment-methods/payment-method--create-intent",
+        "api-reference/payment-methods/payment-method--confirm-intent",
+        "api-reference/payment-methods/list-customer-saved-payment-methods-for-a-payment",
+        "api-reference/payment-methods/list-payment-methods-for-a-customer"
       ]
     },
     {

diff --git a/api-reference-v2/openapi_spec.json b/api-reference-v2/openapi_spec.json
@@ -2022,7 +2022,7 @@
         "tags": [
           "Payment Methods"
         ],
-        "summary": "List payment methods for a Customer v2",
+        "summary": "List customer saved payment methods for a payment",
         "description": "To filter and list the applicable payment methods for a particular Customer ID, is to be associated with a payment",
         "operationId": "List all Payment Methods for a Customer",
         "requestBody": {
@@ -2065,7 +2065,7 @@
         "tags": [
           "Payment Methods"
         ],
-        "summary": "List payment methods for a Customer v2",
+        "summary": "List saved payment methods for a Customer",
         "description": "To filter and list the applicable payment methods for a particular Customer ID, to be used in a non-payments context",
         "operationId": "List all Payment Methods for a Customer",
         "requestBody": {
@@ -2108,8 +2108,8 @@
         "tags": [
           "Payment Methods"
         ],
-        "summary": "Create payment method v2",
-        "description": "TODO: Description Here",
+        "summary": "Payment Method - Create",
+        "description": "Creates and stores a payment method against a customer. In case of cards, this API should be used only by PCI compliant merchants.",
         "operationId": "Create Payment Method",
         "requestBody": {
           "content": {
@@ -2148,7 +2148,7 @@
         "tags": [
           "Payment Methods"
         ],
-        "summary": "Create payment method intent v2",
+        "summary": "Payment Method - Create Intent",
         "description": "TODO: Description Here",
         "operationId": "Create Payment Method Intent",
         "requestBody": {
@@ -2188,7 +2188,7 @@
         "tags": [
           "Payment Methods"
         ],
-        "summary": "Confirm payment method intent v2",
+        "summary": "Payment Method - Confirm Intent",
         "description": "TODO: Description Here",
         "operationId": "Confirm Payment Method Intent",
         "requestBody": {
@@ -2228,8 +2228,8 @@
         "tags": [
           "Payment Methods"
         ],
-        "summary": "Update payment method v2",
-        "description": "TODO: Description Here",
+        "summary": "Payment Method - Update",
+        "description": "Update an existing payment method of a customer. This API is useful for use cases such as updating the card number for expired cards to prevent discontinuity in recurring payments.",
         "operationId": "Update Payment Method",
         "requestBody": {
           "content": {
@@ -2268,8 +2268,8 @@
         "tags": [
           "Payment Methods"
         ],
-        "summary": "Retrieve payment method v2",
-        "description": "TODO: Description Here",
+        "summary": "Payment Method - Retrieve",
+        "description": "Retrieves a payment method of a customer.",
         "operationId": "Retrieve Payment Method",
         "parameters": [
           {
@@ -2307,8 +2307,8 @@
         "tags": [
           "Payment Methods"
         ],
-        "summary": "Delete payment method v2",
-        "description": "TODO: Description Here",
+        "summary": "Payment Method - Delete",
+        "description": "Deletes a payment method of a customer.",
         "operationId": "Delete Payment Method",
         "parameters": [
           {

diff --git a/crates/openapi/src/routes/payment_method.rs b/crates/openapi/src/routes/payment_method.rs
@@ -198,70 +198,51 @@ pub async fn payment_method_delete_api() {}
 )]
 pub async fn default_payment_method_set_api() {}
 
-/// List payment methods for a Customer v2
+/// Payment Method - Create Intent
 ///
-/// To filter and list the applicable payment methods for a particular Customer ID, is to be associated with a payment
+/// TODO: Description Here
 #[utoipa::path(
-    get,
-    path = "/v2/payments/{id}/saved-payment-methods",
+    post,
+    path = "/v2/payment-methods/create-intent",
     request_body(
-    content = PaymentMethodListRequest,
-    // TODO: Add examples and add param for customer_id
+    content = PaymentMethodIntentCreate,
+    // TODO: Add examples
     ),
-    // params (
-    //     ("client-secret" = String, Path, description = "A secret known only to your application and the authorization server"),
-    //     ("accepted_country" = Vec<String>, Query, description = "The two-letter ISO currency code"),
-    //     ("accepted_currency" = Vec<Currency>, Path, description = "The three-letter ISO currency code"),
-    //     ("minimum_amount" = i64, Query, description = "The minimum amount accepted for processing by the particular payment method."),
-    //     ("maximum_amount" = i64, Query, description = "The maximum amount amount accepted for processing by the particular payment method."),
-    //     ("recurring_payment_enabled" = bool, Query, description = "Indicates whether the payment method is eligible for recurring payments"),
-    //     ("installment_payment_enabled" = bool, Query, description = "Indicates whether the payment method is eligible for installment payments"),
-    // ),
     responses(
-        (status = 200, description = "Payment Methods retrieved for customer tied to its respective client-secret passed in the param", body = CustomerPaymentMethodsListResponse),
+        (status = 200, description = "Payment Method Intent Created", body = PaymentMethodResponse),
         (status = 400, description = "Invalid Data"),
-        (status = 404, description = "Payment Methods does not exist in records")
     ),
     tag = "Payment Methods",
-    operation_id = "List all Payment Methods for a Customer",
-    security(("publishable_key" = []))
+    operation_id = "Create Payment Method Intent",
+    security(("api_key" = []))
 )]
 #[cfg(feature = "v2")]
-pub async fn list_customer_payment_method_for_payment() {}
+pub async fn create_payment_method_intent_api() {}
 
-/// List payment methods for a Customer v2
+/// Payment Method - Confirm Intent
 ///
-/// To filter and list the applicable payment methods for a particular Customer ID, to be used in a non-payments context
+/// TODO: Description Here
 #[utoipa::path(
-    get,
-    path = "/v2/customers/{id}/saved-payment-methods",
+    post,
+    path = "/v2/payment-methods/{id}/confirm-intent",
     request_body(
-    content = PaymentMethodListRequest,
-    // TODO: Add examples and add param for customer_id
+    content = PaymentMethodIntentConfirm,
+    // TODO: Add examples
     ),
-    // params (
-    //     ("accepted_country" = Vec<String>, Query, description = "The two-letter ISO currency code"),
-    //     ("accepted_currency" = Vec<Currency>, Path, description = "The three-letter ISO currency code"),
-    //     ("minimum_amount" = i64, Query, description = "The minimum amount accepted for processing by the particular payment method."),
-    //     ("maximum_amount" = i64, Query, description = "The maximum amount amount accepted for processing by the particular payment method."),
-    //     ("recurring_payment_enabled" = bool, Query, description = "Indicates whether the payment method is eligible for recurring payments"),
-    //     ("installment_payment_enabled" = bool, Query, description = "Indicates whether the payment method is eligible for installment payments"),
-    // ),
     responses(
-        (status = 200, description = "Payment Methods retrieved", body = CustomerPaymentMethodsListResponse),
+        (status = 200, description = "Payment Method Intent Confirmed", body = PaymentMethodResponse),
         (status = 400, description = "Invalid Data"),
-        (status = 404, description = "Payment Methods does not exist in records")
     ),
     tag = "Payment Methods",
-    operation_id = "List all Payment Methods for a Customer",
+    operation_id = "Confirm Payment Method Intent",
     security(("api_key" = []))
 )]
 #[cfg(feature = "v2")]
-pub async fn list_customer_payment_method_api() {}
+pub async fn confirm_payment_method_intent_api() {}
 
-/// Create payment method v2
+/// Payment Method - Create
 ///
-/// TODO: Description Here
+/// Creates and stores a payment method against a customer. In case of cards, this API should be used only by PCI compliant merchants.
 #[utoipa::path(
     post,
     path = "/v2/payment-methods",
@@ -280,51 +261,29 @@ pub async fn list_customer_payment_method_api() {}
 #[cfg(feature = "v2")]
 pub async fn create_payment_method_api() {}
 
-/// Create payment method intent v2
-///
-/// TODO: Description Here
-#[utoipa::path(
-    post,
-    path = "/v2/payment-methods/create-intent",
-    request_body(
-    content = PaymentMethodIntentCreate,
-    // TODO: Add examples
-    ),
-    responses(
-        (status = 200, description = "Payment Method Intent Created", body = PaymentMethodResponse),
-        (status = 400, description = "Invalid Data"),
-    ),
-    tag = "Payment Methods",
-    operation_id = "Create Payment Method Intent",
-    security(("api_key" = []))
-)]
-#[cfg(feature = "v2")]
-pub async fn create_payment_method_intent_api() {}
-
-/// Confirm payment method intent v2
+/// Payment Method - Retrieve
 ///
-/// TODO: Description Here
+/// Retrieves a payment method of a customer.
 #[utoipa::path(
-    post,
-    path = "/v2/payment-methods/{id}/confirm-intent",
-    request_body(
-    content = PaymentMethodIntentConfirm,
-    // TODO: Add examples
+    get,
+    path = "/v2/payment-methods/{id}",
+    params (
+        ("id" = String, Path, description = "The unique identifier for the Payment Method"),
     ),
     responses(
-        (status = 200, description = "Payment Method Intent Confirmed", body = PaymentMethodResponse),
-        (status = 400, description = "Invalid Data"),
+        (status = 200, description = "Payment Method Retrieved", body = PaymentMethodResponse),
+        (status = 404, description = "Payment Method Not Found"),
     ),
     tag = "Payment Methods",
-    operation_id = "Confirm Payment Method Intent",
+    operation_id = "Retrieve Payment Method",
     security(("api_key" = []))
 )]
 #[cfg(feature = "v2")]
-pub async fn confirm_payment_method_intent_api() {}
+pub async fn payment_method_retrieve_api() {}
 
-/// Update payment method v2
+/// Payment Method - Update
 ///
-/// TODO: Description Here
+/// Update an existing payment method of a customer. This API is useful for use cases such as updating the card number for expired cards to prevent discontinuity in recurring payments.
 #[utoipa::path(
     patch,
     path = "/v2/payment-methods/{id}/update-saved-payment-method",
@@ -343,42 +302,66 @@ pub async fn confirm_payment_method_intent_api() {}
 #[cfg(feature = "v2")]
 pub async fn payment_method_update_api() {}
 
-/// Retrieve payment method v2
+/// Payment Method - Delete
 ///
-/// TODO: Description Here
+/// Deletes a payment method of a customer.
 #[utoipa::path(
-    get,
+    delete,
     path = "/v2/payment-methods/{id}",
     params (
         ("id" = String, Path, description = "The unique identifier for the Payment Method"),
     ),
     responses(
-        (status = 200, description = "Payment Method Retrieved", body = PaymentMethodResponse),
+        (status = 200, description = "Payment Method Retrieved", body = PaymentMethodDeleteResponse),
         (status = 404, description = "Payment Method Not Found"),
     ),
     tag = "Payment Methods",
-    operation_id = "Retrieve Payment Method",
+    operation_id = "Delete Payment Method",
     security(("api_key" = []))
 )]
 #[cfg(feature = "v2")]
-pub async fn payment_method_retrieve_api() {}
+pub async fn payment_method_delete_api() {}
 
-/// Delete payment method v2
+/// List customer saved payment methods for a payment
 ///
-/// TODO: Description Here
+/// To filter and list the applicable payment methods for a particular Customer ID, is to be associated with a payment
 #[utoipa::path(
-    delete,
-    path = "/v2/payment-methods/{id}",
-    params (
-        ("id" = String, Path, description = "The unique identifier for the Payment Method"),
+    get,
+    path = "/v2/payments/{id}/saved-payment-methods",
+    request_body(
+    content = PaymentMethodListRequest,
+    // TODO: Add examples and add param for customer_id
     ),
     responses(
-        (status = 200, description = "Payment Method Retrieved", body = PaymentMethodDeleteResponse),
-        (status = 404, description = "Payment Method Not Found"),
+        (status = 200, description = "Payment Methods retrieved for customer tied to its respective client-secret passed in the param", body = CustomerPaymentMethodsListResponse),
+        (status = 400, description = "Invalid Data"),
+        (status = 404, description = "Payment Methods does not exist in records")
     ),
     tag = "Payment Methods",
-    operation_id = "Delete Payment Method",
+    operation_id = "List all Payment Methods for a Customer",
+    security(("publishable_key" = []))
+)]
+#[cfg(feature = "v2")]
+pub async fn list_customer_payment_method_for_payment() {}
+
+/// List saved payment methods for a Customer
+///
+/// To filter and list the applicable payment methods for a particular Customer ID, to be used in a non-payments context
+#[utoipa::path(
+    get,
+    path = "/v2/customers/{id}/saved-payment-methods",
+    request_body(
+    content = PaymentMethodListRequest,
+    // TODO: Add examples and add param for customer_id
+    ),
+    responses(
+        (status = 200, description = "Payment Methods retrieved", body = CustomerPaymentMethodsListResponse),
+        (status = 400, description = "Invalid Data"),
+        (status = 404, description = "Payment Methods does not exist in records")
+    ),
+    tag = "Payment Methods",
+    operation_id = "List all Payment Methods for a Customer",
     security(("api_key" = []))
 )]
 #[cfg(feature = "v2")]
-pub async fn payment_method_delete_api() {}
+pub async fn list_customer_payment_method_api() {}