Merge pull request #57 from PaystackOSS/patch-payment-requests

chore: update payment requests examples and descriptions

Author: damilola-paystack

dist/paystack.yaml

@@ -1,6 +1,7 @@
 type: object
 required:
   - customer
+  - amount
 properties:
   customer:
     description: Customer id or code
@@ -39,32 +40,25 @@ properties:
       Indicates whether Paystack sends an email notification to customer.
       Defaults to true
     type: boolean
-    items:
-      type: object
   draft:
     description: >-
       Indicate if request should be saved as draft. Defaults to false and
       overrides send_notification
     type: boolean
-    items:
-      type: object
   has_invoice:
     description: >-
       Set to true to create a draft invoice (adds an auto incrementing invoice
-      number if none is provided) 
-
-      even if there are no line_items or tax passed
+      number if none is provided) even if there are no line_items or tax passed
     type: boolean
-    items:
-      type: object
   invoice_number:
     description: >-
-      Numeric value of invoice. Invoice will start from 1 and auto increment
-      from there. This field is to help 
-
-      override whatever value Paystack decides. Auto increment for subsequent
-      invoices continue from this point.
+      Numeric value of invoice. Invoice will start from 1 and auto increment from there. 
+      This field is to help override whatever value Paystack decides. Auto increment for 
+      subsequent invoices continue from this point.
     type: integer
   split_code:
     description: The split code of the transaction split.
     type: string
+example:
+  customer: CUS_xqp6o5oja5cackf
+  amount: 10000

src/assets/openapi/components/schemas/PaymentRequestCreate.yaml

@@ -37,32 +37,26 @@ properties:
       Indicates whether Paystack sends an email notification to customer.
       Defaults to true
     type: boolean
-    items:
-      type: object
   draft:
     description: >-
       Indicate if request should be saved as draft. Defaults to false and
       overrides send_notification
     type: boolean
-    items:
-      type: object
   has_invoice:
     description: >-
       Set to true to create a draft invoice (adds an auto incrementing invoice
-      number if none is provided) 
-
-      even if there are no line_items or tax passed
+      number if none is provided) even if there are no line_items or tax passed
     type: boolean
     items:
       type: object
   invoice_number:
     description: >-
       Numeric value of invoice. Invoice will start from 1 and auto increment
-      from there. This field is to help 
-
-      override whatever value Paystack decides. Auto increment for subsequent
-      invoices continue from this point.
+      from there. This field is to help override whatever value Paystack decides. 
+      Auto increment for subsequent invoices continue from this point.
     type: integer
   split_code:
     description: The split code of the transaction split.
     type: string
+example:
+  amount: 15000

src/assets/openapi/components/schemas/PaymentRequestUpdate.yaml

@@ -89,6 +89,11 @@ tags:
       A collection of endpoints gaining insights into the amount on an
       integration
     x-product-name: Balance
+  - name: Payment Request
+    description: |
+      A collection of endpoints for managing invoices for the payment of goods
+      and services
+    x-product-name: Payment Requests  
   - name: Product
     description: |
       A collection of endpoints for creating and managing inventories
@@ -106,11 +111,6 @@ tags:
       A collection of endpoints for creating and managing links for the
       collection of payment for products
     x-product-name: Payment Pages
-  - name: Payment Request
-    description: |
-      A collection of endpoints for managing invoices for the payment of goods
-      and services
-    x-product-name: Payment Requests
   - name: Settlement
     description: |
       A collection of endpoints for gaining insights into payouts
@@ -302,6 +302,20 @@ paths:
     $ref: paths/balance.yaml
   /balance/ledger:
     $ref: paths/balance_ledger.yaml
+  /paymentrequest:
+    $ref: paths/paymentrequest.yaml
+  /paymentrequest/{id}:
+    $ref: paths/paymentrequest_{id}.yaml
+  /paymentrequest/verify/{id}:
+    $ref: paths/paymentrequest_verify_{id}.yaml
+  /paymentrequest/notify/{id}:
+    $ref: paths/paymentrequest_notify_{id}.yaml
+  /paymentrequest/totals:
+    $ref: paths/paymentrequest_totals.yaml
+  /paymentrequest/finalize/{id}:
+    $ref: paths/paymentrequest_finalize_{id}.yaml
+  /paymentrequest/archive/{id}:
+    $ref: paths/paymentrequest_archive_{id}.yaml
   /product:
     $ref: paths/product.yaml
   /product/{id}:
@@ -336,20 +350,6 @@ paths:
     $ref: paths/page_check_slug_availability_{slug}.yaml
   /page/{id}/product:
     $ref: paths/page_{id}_product.yaml
-  /paymentrequest:
-    $ref: paths/paymentrequest.yaml
-  /paymentrequest/{id}:
-    $ref: paths/paymentrequest_{id}.yaml
-  /paymentrequest/verify/{id}:
-    $ref: paths/paymentrequest_verify_{id}.yaml
-  /paymentrequest/notify/{id}:
-    $ref: paths/paymentrequest_notify_{id}.yaml
-  /paymentrequest/totals:
-    $ref: paths/paymentrequest_totals.yaml
-  /paymentrequest/finalize/{id}:
-    $ref: paths/paymentrequest_finalize_{id}.yaml
-  /paymentrequest/archive/{id}:
-    $ref: paths/paymentrequest_archive_{id}.yaml
   /settlement:
     $ref: paths/settlement.yaml
   /settlement/{id}/transaction:

src/assets/openapi/openapi.yaml

@@ -2,6 +2,7 @@ post:
   tags:
     - Payment Request
   summary: Create Payment Request
+  description: Create a new payment request by issuing an invoice to a customer
   operationId: paymentRequest_create
   requestBody:
     content:
@@ -22,6 +23,7 @@ get:
   tags:
     - Payment Request
   summary: List Payment Request
+  description: List all previously created payment requests to your customers
   operationId: paymentRequest_list
   parameters:
     - in: query
@@ -43,6 +45,12 @@ get:
       name: status
       schema:
         type: string
+        enum: 
+          - draft
+          - pending
+          - success
+          - failed
+      example: success
       description: Invoice status to filter
     - in: query
       name: currency

src/assets/openapi/paths/paymentrequest.yaml

@@ -1,13 +1,18 @@
 parameters:
   - name: id
+    description: The unique identifier of a previously created payment request
     in: path
     required: true
     schema:
-      type: string
+      type: integer
+    example: 18823736
 post:
   tags:
     - Payment Request
   summary: Archive Payment Request
+  description: | 
+    Archive a payment request to clean up your records. An archived payment request cannot be verified and will not 
+    be returned when listing all previously created payment requests.
   operationId: paymentRequest_archive
   responses:
     '200':

src/assets/openapi/paths/paymentrequest_archive_{id}.yaml

@@ -1,13 +1,16 @@
 parameters:
   - name: id
+    description: The unique identifier of a draft payment request
     in: path
     required: true
     schema:
-      type: string
+      type: integer
+    example: 18823736
 post:
   tags:
     - Payment Request
   summary: Finalize Payment Request
+  description: Finalise the creation of a draft payment request for a customer
   operationId: paymentRequest_finalize
   responses:
     '200':

src/assets/openapi/paths/paymentrequest_finalize_{id}.yaml

@@ -1,13 +1,16 @@
 parameters:
   - name: id
+    description: The unique identifier of a previously created payment request
     in: path
     required: true
     schema:
-      type: string
+      type: integer
+    example: 18823736
 post:
   tags:
     - Payment Request
   summary: Send Notification
+  description: Trigger an email reminder to a customer for a previously created payment request
   operationId: paymentRequest_notify
   responses:
     '200':

src/assets/openapi/paths/paymentrequest_notify_{id}.yaml

@@ -2,6 +2,7 @@ get:
   tags:
     - Payment Request
   summary: Payment Request Total
+  description: Get the metric of all pending and successful payment requests
   operationId: paymentRequest_totals
   responses:
     '200':

src/assets/openapi/paths/paymentrequest_totals.yaml

@@ -1,13 +1,16 @@
 parameters:
   - name: id
+    description: The unique identifier of a previously created payment request
     in: path
     required: true
     schema:
-      type: string
+      type: integer
+    example: 18823736
 get:
   tags:
     - Payment Request
   summary: Verify Payment Request
+  description: Verify the status of a previously created payment request
   operationId: paymentRequest_verify
   responses:
     '200':