chore: update all transaction endpoints with examples and descriptions

Author: damilola-paystack

dist/paystack.yaml

@@ -9,9 +9,7 @@ properties:
     type: string
   amount:
     description: >
-      Amount should be in smallest denomination of the currency. For example if
-      currency is NGN, pesewas, if currency is GHS, and cents, if currency is
-      ZAR
+      Amount should be in smallest denomination of the currency.
     type: integer
   currency:
     $ref: ./Currency.yaml

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

@@ -140,6 +140,10 @@ tags:
 paths:
   /transaction/initialize:
     $ref: paths/transaction_initialize.yaml
+  /transaction/charge_authorization:
+    $ref: paths/transaction_charge_authorization.yaml
+  /transaction/partial_debit:
+    $ref: paths/transaction_partial_debit.yaml
   /transaction/verify/{reference}:
     $ref: paths/transaction_verify_{reference}.yaml
   /transaction:
@@ -152,14 +156,6 @@ paths:
     $ref: paths/transaction_totals.yaml
   /transaction/export:
     $ref: paths/transaction_export.yaml
-  /transaction/charge_authorization:
-    $ref: paths/transaction_charge_authorization.yaml
-  /transaction/partial_debit:
-    $ref: paths/transaction_partial_debit.yaml
-  /transaction/{id}/event:
-    $ref: paths/transaction_{id}_event.yaml
-  /transaction/{id}/session:
-    $ref: paths/transaction_{id}_session.yaml
   /split:
     $ref: paths/split.yaml
   /split/{id}:

src/assets/openapi/openapi.yaml

@@ -3,19 +3,14 @@ get:
     - Miscellaneous
   summary: List States (AVS)
   operationId: miscellaneous_avs
+  description: Get a list of states for a country for address verification
   parameters:
-    - in: query
-      name: type
-      schema:
-        type: string
     - in: query
       name: country
+      description: The country code of the states to list. It is gotten after the charge request
       schema:
         type: string
-    - in: query
-      name: currency
-      schema:
-        type: string
+        example: CA
   responses:
     '200':
       $ref: ../components/responses/MiscellaneousListStatesSuccess.yaml

src/assets/openapi/paths/address_verification_states.yaml

@@ -2,7 +2,10 @@ post:
   tags:
     - Apple Pay
   summary: Register Domain
-  description: Register a top-level domain or subdomain for your Apple Pay integration.
+  description: |
+    Register a top-level domain or subdomain for your Apple Pay integration.
+
+    > This endpoint can only be called with one domain or subdomain at a time.
   operationId: applePay_registerDomain
   requestBody:
     content:
@@ -23,7 +26,7 @@ get:
   tags:
     - Apple Pay
   summary: List Domains
-  description: Lists all registered domains on your integration
+  description: Lists all registered domains on your integration. Returns an empty array if no domains have been added.
   operationId: applePay_listDomain
   parameters:
     - name: use_cursor
@@ -51,7 +54,7 @@ delete:
   tags:
     - Apple Pay
   summary: Unregister Domain
-  description: >-
+  description: |
     Unregister a top-level domain or subdomain previously used for your Apple
     Pay integration.
   operationId: applePay_unregisterDomain

src/assets/openapi/paths/apple-pay_domain.yaml

@@ -6,8 +6,15 @@ get:
   parameters:
     - in: query
       name: country
+      description: | 
+        The country from which to obtain the list of supported banks.
       schema:
         type: string
+        enum:
+          - ghana
+          - kenya
+          - nigeria
+          - south africa
     - in: query
       name: pay_with_bank_transfer
       schema:

src/assets/openapi/paths/bank.yaml

@@ -10,6 +10,7 @@ get:
       description: A flag to indicate if cursor based pagination should be used
       schema:
         type: boolean
+      example: true
     - in: query
       name: next
       description: >

src/assets/openapi/paths/transaction.yaml

@@ -3,6 +3,7 @@ post:
     - Transaction
   summary: Charge Authorization
   operationId: transaction_chargeAuthorization
+  description: Charge all authorizations marked as reusable with this endpoint whenever you need to receive payments
   requestBody:
     content:
       application/json:

src/assets/openapi/paths/transaction_charge_authorization.yaml

@@ -4,6 +4,7 @@ get:
   summary: Export Transactions
   operationId: transaction_export
   x-operationId: transaction_exportTransaction
+  description: Download transactions that occurred on your integration for a specific timeframe
   parameters:
     - in: query
       name: from

src/assets/openapi/paths/transaction_export.yaml

@@ -3,6 +3,7 @@ post:
     - Transaction
   summary: Partial Debit
   operationId: transaction_partialDebit
+  description: Retrieve part of a payment from a customer
   requestBody:
     content:
       application/json: