chore: update transfers and balance examples and descriptions

damilola-paystack · damilola-paystack · commit 61ae53a95a4c · 2025-09-12T13:50:58.000+01:00
diff --git a/dist/paystack.yaml b/dist/paystack.yaml
diff --git a/src/assets/openapi/components/schemas/TransferBase.yaml b/src/assets/openapi/components/schemas/TransferBase.yaml
@@ -22,3 +22,7 @@ properties:
   reason:
     description: The reason or narration for the transfer.
     type: string
+example: 
+  amount: 120000
+  recipient: RCP_gd9vgag7n5lr5ix
+  reference: acv_9ee55786-2323-4760-98e2-6380c9cb3f68
diff --git a/src/assets/openapi/components/schemas/TransferBulk.yaml b/src/assets/openapi/components/schemas/TransferBulk.yaml
@@ -4,8 +4,9 @@ required:
   - transfers
 properties:
   source:
-    description: Where should we transfer from? Only balance is allowed for now
+    description: The source of funds for the transfer.
     type: string
+    default: balance
   currency:
     description: Specify the currency of the transfer.
     type: string
@@ -20,3 +21,9 @@ properties:
     type: array
     items:
       $ref: ./TransferBase.yaml
+example:
+  source: balance
+  transfers:
+    - amount: 120000
+      recipient: RCP_gd9vgag7n5lr5ix
+      reference: acv_9ee55786-2323-4760-98e2-6380c9cb3f68
diff --git a/src/assets/openapi/components/schemas/TransferFinalize.yaml b/src/assets/openapi/components/schemas/TransferFinalize.yaml
@@ -9,3 +9,6 @@ properties:
   otp:
     description: OTP sent to business phone to verify transfer
     type: string
+example: 
+  transfer_code: TRF_vsyqdmlzble3uii
+  otp: "928783"
diff --git a/src/assets/openapi/components/schemas/TransferFinalizeDisableOTP.yaml b/src/assets/openapi/components/schemas/TransferFinalizeDisableOTP.yaml
@@ -5,3 +5,5 @@ properties:
   otp:
     description: OTP sent to business phone to verify disabling OTP requirement
     type: string
+example: 
+  otp: "928783"
diff --git a/src/assets/openapi/components/schemas/TransferInitiate.yaml b/src/assets/openapi/components/schemas/TransferInitiate.yaml
@@ -4,12 +4,9 @@ allOf:
   - type: object
     required:
       - source
-      - amount
-      - recipient
-      - reference
     properties:
       source:
-        description: The origin of the funds to send from
+        description: The source of funds to send from
         type: string
         default: balance
       currency:
@@ -21,3 +18,5 @@ allOf:
           - ZAR
           - KES
           - GHS
+    example:
+      source: balance
diff --git a/src/assets/openapi/components/schemas/TransferResendOTP.yaml b/src/assets/openapi/components/schemas/TransferResendOTP.yaml
@@ -12,4 +12,8 @@ properties:
     default: transfer
     enum:
       - disable_otp
+      - resend_otp
       - transfer
+example:
+  transfer_code: TRF_vsyqdmlzble3uii
+  reason: resend_otp
diff --git a/src/assets/openapi/openapi.yaml b/src/assets/openapi/openapi.yaml
@@ -84,6 +84,11 @@ tags:
     description: |
       A collection of endpoints for automating sending money to beneficiaries
     x-product-name: Transfers
+  - name: Balance
+    description: >
+      A collection of endpoints gaining insights into the amount on an
+      integration
+    x-product-name: Balance
   - name: Product
     description: |
       A collection of endpoints for creating and managing inventories
@@ -110,11 +115,6 @@ tags:
     description: |
       A collection of endpoints for gaining insights into payouts
     x-product-name: Settlements
-  - name: Balance
-    description: >
-      A collection of endpoints gaining insights into the amount on an
-      integration
-    x-product-name: Balance
   - name: Integration
     description: |
       A collection of endpoints for managing some settings on an integration
@@ -298,6 +298,10 @@ paths:
     $ref: paths/transfer_disable_otp_finalize.yaml
   /transfer/enable_otp:
     $ref: paths/transfer_enable_otp.yaml
+  /balance:
+    $ref: paths/balance.yaml
+  /balance/ledger:
+    $ref: paths/balance_ledger.yaml
   /product:
     $ref: paths/product.yaml
   /product/{id}:
@@ -350,10 +354,6 @@ paths:
     $ref: paths/settlement.yaml
   /settlement/{id}/transaction:
     $ref: paths/settlement_{id}_transaction.yaml
-  /balance:
-    $ref: paths/balance.yaml
-  /balance/ledger:
-    $ref: paths/balance_ledger.yaml
   /integration/payment_session_timeout:
     $ref: paths/integration_payment_session_timeout.yaml
   /refund:
diff --git a/src/assets/openapi/paths/balance.yaml b/src/assets/openapi/paths/balance.yaml
@@ -3,7 +3,7 @@ get:
     - Balance
   summary: Fetch Balance
   operationId: balance_fetch
-  description: You can only transfer from what you have
+  description: Fetch the available balance on your integration
   responses:
     '200':
       description: ''
diff --git a/src/assets/openapi/paths/balance_ledger.yaml b/src/assets/openapi/paths/balance_ledger.yaml
@@ -2,6 +2,7 @@ get:
   tags:
     - Balance
   summary: Balance Ledger
+  description: Fetch all pay-ins and pay-outs that occured on your integration
   operationId: balance_ledger
   parameters:
     - in: query
diff --git a/src/assets/openapi/paths/transfer.yaml b/src/assets/openapi/paths/transfer.yaml
@@ -2,6 +2,7 @@ post:
   tags:
     - Transfer
   summary: Initiate Transfer
+  description: Send money to your customers
   operationId: transfer_initiate
   requestBody:
     content:
@@ -13,7 +14,7 @@ post:
           $ref: ../components/schemas/TransferInitiate.yaml
   responses:
     '200':
-      description: ''
+      description: 'Successful operation'
       content:
         application/json:
           schema:
@@ -26,13 +27,15 @@ get:
   tags:
     - Transfer
   summary: List Transfers
+  description: List the transfers made on your integration
   operationId: transfer_list
   parameters:
     - in: query
       name: use_cursor
       description: A flag to indicate if cursor based pagination should be used
       schema:
         type: boolean
+      example: true
     - in: query
       name: next
       description: >
diff --git a/src/assets/openapi/paths/transfer_bulk.yaml b/src/assets/openapi/paths/transfer_bulk.yaml
@@ -2,6 +2,10 @@ post:
   tags:
     - Transfer
   summary: Initiate Bulk Transfer
+  description: | 
+    Batch multiple transfers in a single request.
+
+    You need to disable the Transfers OTP requirement to use this endpoint.
   operationId: transfer_bulk
   requestBody:
     content:
diff --git a/src/assets/openapi/paths/transfer_disable_otp.yaml b/src/assets/openapi/paths/transfer_disable_otp.yaml
@@ -2,10 +2,13 @@ post:
   tags:
     - Transfer
   summary: Disable OTP for Transfers
+  description: | 
+    This is used in the event that you want to be able to complete transfers programmatically without use of OTPs. 
+    No arguments required. You will get an OTP to complete the request.
   operationId: transfer_disableOtp
   responses:
     '200':
-      description: ''
+      description: 'Successful response'
       content:
         application/json:
           schema:
diff --git a/src/assets/openapi/paths/transfer_disable_otp_finalize.yaml b/src/assets/openapi/paths/transfer_disable_otp_finalize.yaml
@@ -2,6 +2,7 @@ post:
   tags:
     - Transfer
   summary: Finalize Disabling OTP for Transfers
+  description: Finalize the request to disable OTP on your transfers
   operationId: transfer_disableOtpFinalize
   requestBody:
     content:
@@ -13,7 +14,7 @@ post:
           $ref: ../components/schemas/TransferFinalizeDisableOTP.yaml
   responses:
     '200':
-      description: ''
+      description: 'Successful response'
       content:
         application/json:
           schema:
diff --git a/src/assets/openapi/paths/transfer_enable_otp.yaml b/src/assets/openapi/paths/transfer_enable_otp.yaml
@@ -2,10 +2,13 @@ post:
   tags:
     - Transfer
   summary: Enable OTP requirement for Transfers
+  description: | 
+    In the event that a customer wants to stop being able to complete transfers programmatically, this endpoint helps turn OTP requirement back on. 
+    No arguments required.
   operationId: transfer_enableOtp
   responses:
     '200':
-      description: ''
+      description: 'Successful response'
       content:
         application/json:
           schema:
diff --git a/src/assets/openapi/paths/transfer_export.yaml b/src/assets/openapi/paths/transfer_export.yaml
@@ -2,6 +2,7 @@ get:
   tags:
     - Transfer
   summary: Export Transfers
+  description: Export a list of transfers carried out on your integration
   operationId: transfer_exportTransfer
   parameters:
     - in: query
@@ -25,6 +26,7 @@ get:
           - blocked
           - rejected
           - received
+      example: success
     - in: query
       name: from
       schema:
diff --git a/src/assets/openapi/paths/transfer_finalize_transfer.yaml b/src/assets/openapi/paths/transfer_finalize_transfer.yaml
@@ -2,6 +2,7 @@ post:
   tags:
     - Transfer
   summary: Finalize Transfer
+  description: Finalize an initiated transfer
   operationId: transfer_finalize
   requestBody:
     content:
diff --git a/src/assets/openapi/paths/transfer_resend_otp.yaml b/src/assets/openapi/paths/transfer_resend_otp.yaml
@@ -2,6 +2,7 @@ post:
   tags:
     - Transfer
   summary: Resend OTP for Transfer
+  description: Generates and send a new OTP to customer in the event they are having trouble receiving one.
   operationId: transfer_resendOtp
   requestBody:
     content:
diff --git a/src/assets/openapi/paths/transfer_verify_{reference}.yaml b/src/assets/openapi/paths/transfer_verify_{reference}.yaml
@@ -2,13 +2,16 @@ get:
   tags:
     - Transfer
   summary: Verify Transfer
+  description: Verify the status of a transfer on your integration
   operationId: transfer_verify
   parameters:
     - name: reference
+      description: Transfer reference
       in: path
       required: true
       schema:
         type: string
+      example: acv_9ee55786-2323-4760-98e2-6380c9cb3f67
   responses:
     '200':
       description: ''
diff --git a/src/assets/openapi/paths/transfer_{code}.yaml b/src/assets/openapi/paths/transfer_{code}.yaml
@@ -5,14 +5,16 @@ parameters:
     required: true
     schema:
       type: string
+    example: TRF_1ptvuv321ahaa7q
 get:
   tags:
     - Transfer
   summary: Fetch Transfer
+  description: Get details of a transfer on your integration
   operationId: transfer_fetch
   responses:
     '200':
-      description: ''
+      description: 'Succesful operation'
       content:
         application/json:
           schema:
diff --git a/src/index.js b/src/index.js
@@ -5,7 +5,7 @@ import path from 'path'
 import open from 'open';
 
 const app = express()
-const port = 3031
+const port = 7070
 
 const __dirname = new URL('.', import.meta.url).pathname;
 const file = fs.readFileSync(path.join(__dirname, '../dist/paystack.yaml'), 'utf8')
