Merge pull request #520 from bbiggerr/payment-methods-4-104-0

[Update] Payment Method Add and Payment Make endpoints

Author: bbiggerr

openapi.yaml

@@ -1632,7 +1632,7 @@ paths:
               --data-binary "/path/to/image"
               https://api.linode.com/v4/account/oauth-clients/edc6790ea9db4d224c5c/thumbnail
   /account/payment-methods:
-    x-linode-cli-command: account
+    x-linode-cli-command: payment-methods
     get:
       servers:
         - url: https://api.linode.com/v4
@@ -1647,7 +1647,7 @@ paths:
       description: |
         Returns a paginated list of Payment Methods for this Account.
       operationId: getPaymentMethods
-      x-linode-cli-action: payment-methods-list
+      x-linode-cli-action: list
       security:
         - personalAccessToken: []
         - oauth:
@@ -1679,7 +1679,7 @@ paths:
                 https://api.linode.com/v4/account/payment-methods
         - lang: CLI
           source: >
-            linode-cli account payment-methods-list
+            linode-cli payment-methods list
     post:
       servers:
         - url: https://api.linode.com/v4
@@ -1688,16 +1688,18 @@ paths:
         - Account
       summary: Payment Method Add
       description: |
-        Adds a Payment Method to your Account with the option to set it as the default method. Adding a default
-        Payment Method removes the default status from any other Payment Method.
+        Adds a Payment Method to your Account with the option to set it as the default method.
 
-        An Account can have up to 6 active Payment Methods.
+        * Adding a default Payment Method removes the default status from any other Payment Method.
 
-        Prior to adding a Payment Method, ensure that your billing address information is up-to-date
+        * An Account can have up to 6 active Payment Methods.
+
+        * Prior to adding a Payment Method, ensure that your billing address information is up-to-date
         with a valid `zip` by using the Account Update ([PUT /account](/docs/api/account/#account-update)) endpoint.
+
+        * A `payment_method_add` event is generated when a payment is successfully submitted.
       operationId: createPaymentMethod
-      x-linode-cli-action: payment-method-add
-      x-linode-cli-skip: true
+      x-linode-cli-action: add
       security:
         - personalAccessToken: []
         - oauth:
@@ -1720,7 +1722,16 @@ paths:
                 - cvv
               properties:
                 type:
-                  $ref: '#/components/schemas/PaymentMethod/properties/type'
+                  type: string
+                  enum:
+                    - credit_card
+                  description: |
+                    The type of Payment Method.
+
+                    Alternative Payment Methods including Google Pay can be added using Linode Cloud Manager. See our
+                    guide on [Managing Billing in the Cloud Manager](/docs/guides/manage-billing-in-cloud-manager/)
+                    for details and instructions.
+                  example: 'credit_card'
                 is_default:
                   $ref: '#/components/schemas/PaymentMethod/properties/is_default'
                 data:
@@ -1759,8 +1770,17 @@ paths:
                   }
                 }' \
                 https://api.linode.com/v4/account/payment-methods
+        - lang: CLI
+          source: >
+            linode-cli payment-methods add \
+              --type credit_card \
+              --is_default true \
+              --data.card_number 4111111111111111 \
+              --data.expiry_month 11 \
+              --data.expiry_year 2020 \
+              --data.cvv 111
   /account/payment-methods/{paymentMethodId}:
-    x-linode-cli-command: account
+    x-linode-cli-command: payment-methods
     parameters:
     - name: paymentMethodId
       in: path
@@ -1778,7 +1798,7 @@ paths:
       description: |
         View the details of the specified Payment Method.
       operationId: getPaymentMethod
-      x-linode-cli-action: payment-method-view
+      x-linode-cli-action: view
       security:
         - personalAccessToken: []
         - oauth:
@@ -1799,7 +1819,7 @@ paths:
                 https://api.linode.com/v4/account/payment-methods/123
         - lang: CLI
           source: >
-            linode-cli account payment-method-view 123
+            linode-cli payment-methods view 123
     delete:
       x-linode-grant: read_write
       tags:
@@ -1814,7 +1834,7 @@ paths:
         ([POST /account/payment-methods/{paymentMethodId}/make-default](/docs/api/account/#payment-method-make-default))
         endpoint.
       operationId: deletePaymentMethod
-      x-linode-cli-action: payment-method-delete
+      x-linode-cli-action: delete
       security:
         - personalAccessToken: []
         - oauth:
@@ -1836,9 +1856,9 @@ paths:
                 https://api.linode.com/v4/account/payment-methods/123
         - lang: CLI
           source: >
-            linode-cli account payment-method-delete 123
+            linode-cli payment-methods delete 123
   /account/payment-methods/{paymentMethodId}/make-default:
-    x-linode-cli-command: account
+    x-linode-cli-command: payment-methods
     parameters:
     - name: paymentMethodId
       in: path
@@ -1858,7 +1878,7 @@ paths:
 
         Removes the default status from any other Payment Method.
       operationId: makePaymentMethodDefault
-      x-linode-cli-action: payment-method-make-default
+      x-linode-cli-action: default
       security:
         - personalAccessToken: []
         - oauth:
@@ -1880,7 +1900,7 @@ paths:
                 https://api.linode.com/v4/account/payment-methods/123/make-default
         - lang: CLI
           source: >
-            linode-cli account payment-method-make-default 123
+            linode-cli payment-methods default 123
   /account/payments:
     x-linode-cli-command: account
     get:
@@ -1932,9 +1952,12 @@ paths:
       tags:
       - Account
       summary: Payment Make
-      description: >
-        Makes a Payment to your Account via credit card. This will charge your
-        credit card the requested amount.
+      description: |
+        Makes a Payment to your Account.
+
+        * The requested amount is charged to the default Payment Method if no `payment_method_id` is specified.
+
+        * A `payment_submitted` event is generated when a payment is successfully submitted.
       operationId: createPayment
       x-linode-cli-action: payment-create
       security:
@@ -1950,11 +1973,11 @@ paths:
               $ref: '#/components/schemas/PaymentRequest'
       responses:
         '200':
-          description: Payment made.
+          description: Payment submitted successfully.
           content:
             application/json:
               schema:
-                  $ref: '#/components/schemas/Payment'
+                $ref: '#/components/schemas/Payment'
         '202':
           $ref: '#/components/responses/WarningResponse'
         default:
@@ -1966,14 +1989,16 @@ paths:
                 -H "Authorization: Bearer $TOKEN" \
                 -X POST -d '{
                     "cvv": "123",
-                    "usd": "120.50"
+                    "usd": "120.50",
+                    "payment_method_id": 123
                 }' \
                 https://api.linode.com/v4/account/payments
         - lang: CLI
           source: >
             linode-cli account payment-create \
               --cvv 123 \
-              --usd 120.50
+              --usd 120.50 \
+              --payment_method_id 123
   /account/payments/{paymentId}:
     x-linode-cli-command: account
     parameters:
@@ -17003,6 +17028,7 @@ components:
           - oauth_client_secret_reset
           - oauth_client_update
           - password_reset
+          - payment_method_add
           - payment_submitted
           - profile_update
           - stackscript_create
@@ -21070,6 +21096,11 @@ components:
             The amount in US Dollars of the Payment. The maximum credit card
             payment that can be made is $50,000 dollars.
           example: '120.50'
+        payment_method_id:
+          type: integer
+          description: >
+            The ID of the Payment Method to apply to the Payment.
+          example: 123
     PayPal:
       type: object
       required: