Callbacks service docs updated

interface/api/payments/bodies/payment.yaml

@@ -1,6 +1,7 @@
 components:
   requestBodies:
     QuotePaymentBody:
+      description: JSON payload used to request a quote for one payment intent.
       required: true
       content:
         application/json:
@@ -8,6 +9,7 @@ components:
             $ref: ../request/payment.yaml#/components/schemas/QuotePaymentRequest
 
     QuotePaymentsBody:
+      description: JSON payload used to request quotes for multiple payment intents.
       required: true
       content:
         application/json:
@@ -15,6 +17,7 @@ components:
             $ref: ../request/payment.yaml#/components/schemas/QuotePaymentsRequest
 
     InitiatePaymentBody:
+      description: JSON payload used to initiate a single payment.
       required: true
       content:
         application/json:
@@ -22,6 +25,7 @@ components:
             $ref: ../request/payment.yaml#/components/schemas/InitiatePaymentRequest
 
     InitiatePaymentsBody:
+      description: JSON payload used to initiate multiple payments from a quote reference.
       required: true
       content:
         application/json:

interface/api/payments/request/payment.yaml

@@ -1,33 +1,41 @@
 components:
   schemas:
     PaymentBase:
+      description: Base fields shared by payment initiation request payloads.
       type: object
       additionalProperties: false
       required:
         - idempotencyKey
       properties:
         idempotencyKey:
+          description: Client-supplied key used to safely deduplicate requests.
           type: string
         metadata:
+          description: Optional request metadata forwarded through payment processing.
           type: object
           additionalProperties:
             type: string
 
     QuotePaymentRequest:
+      description: Request payload to quote a single payment intent.
       type: object
       additionalProperties: false
       required:
         - intent
       properties:
         idempotencyKey:
+          description: Idempotency key used when persisting quote context.
           type: string
         metadata:
+          description: Optional metadata associated with the quote request.
           type: object
           additionalProperties:
             type: string
         intent:
+          description: Payment intent to be priced.
           $ref: ../../../models/payment/payment.yaml#/components/schemas/PaymentIntent
         previewOnly:
+          description: If true, returns a preview quote without requiring idempotency.
           type: boolean
       allOf:
         - if:
@@ -45,23 +53,28 @@ components:
               - idempotencyKey
 
     QuotePaymentsRequest:
+      description: Request payload to quote multiple payment intents in a single call.
       type: object
       additionalProperties: false
       required:
         - intents
       properties:
         idempotencyKey:
+          description: Idempotency key used when persisting batch quote context.
           type: string
         metadata:
+          description: Optional metadata associated with the quote request.
           type: object
           additionalProperties:
             type: string
         intents:
+          description: List of payment intents to be priced.
           type: array
           minItems: 1
           items:
             $ref: ../../../models/payment/payment.yaml#/components/schemas/PaymentIntent
         previewOnly:
+          description: If true, returns preview quotes without requiring idempotency.
           type: boolean
       allOf:
         - if:
@@ -79,6 +92,7 @@ components:
               - idempotencyKey
 
     InitiatePaymentRequest:
+      description: Request payload to initiate a single payment.
       allOf:
         - $ref: ./payment.yaml#/components/schemas/PaymentBase
         - type: object
@@ -88,11 +102,14 @@ components:
             - required: [quoteRef]
           properties:
             intent:
+              description: Payment intent to execute directly.
               $ref: ../../../models/payment/payment.yaml#/components/schemas/PaymentIntent
             quoteRef:
+              description: Reference to a previously generated quote to execute.
               type: string
 
     InitiatePaymentsRequest:
+      description: Request payload to initiate multiple payments from a multi-quote reference.
       allOf:
         - $ref: ./payment.yaml#/components/schemas/PaymentBase
         - type: object
@@ -101,4 +118,5 @@ components:
             - quoteRef
           properties:
             quoteRef:
+              description: Reference to a previously generated multi-quote.
               type: string

interface/api/payments/response/payment.yaml

@@ -1,6 +1,7 @@
 components:
   schemas:
     PaymentQuoteData:
+      description: Response payload for a single payment quote.
       type: object
       additionalProperties: false
       required:
@@ -8,13 +9,17 @@ components:
         - quote
       properties:
         accessToken:
+          description: Refreshed access token to be used in subsequent API calls.
           $ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
         idempotencyKey:
+          description: Idempotency key associated with the quote response.
           type: string
         quote:
+          description: Generated quote data for the requested payment intent.
           $ref: ../../../models/payment/payment.yaml#/components/schemas/PaymentQuote
 
     PaymentQuotesData:
+      description: Response payload for a batch quote request.
       type: object
       additionalProperties: false
       required:
@@ -22,21 +27,27 @@ components:
         - quote
       properties:
         accessToken:
+          description: Refreshed access token to be used in subsequent API calls.
           $ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
         quote:
+          description: Batch quote summary and quoted items.
           type: object
           additionalProperties: false
           properties:
             idempotencyKey:
+              description: Idempotency key associated with the batch quote response.
               type: string
             quoteRef:
+              description: Reference to the generated batch quote.
               type: string
             items:
+              description: Collection of quotes for each requested payment intent.
               type: array
               items:
                 $ref: ../../../models/payment/payment.yaml#/components/schemas/PaymentQuote
 
     PaymentsData:
+      description: Response payload containing a list of payments.
       type: object
       additionalProperties: false
       required:
@@ -44,15 +55,19 @@ components:
         - payments
       properties:
         accessToken:
+          description: Refreshed access token to be used in subsequent API calls.
           $ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
         payments:
+          description: Collection of payment records.
           type: array
           items:
             $ref: ../../../models/payment/payment.yaml#/components/schemas/Payment
         page:
+          description: Pagination cursor metadata for payment listing endpoints.
           $ref: ../../../models/common/pagination.yaml#/components/schemas/CursorPageResponse
 
     PaymentData:
+      description: Response payload containing a single payment record.
       type: object
       additionalProperties: false
       required:
@@ -60,6 +75,8 @@ components:
         - payment
       properties:
         accessToken:
+          description: Refreshed access token to be used in subsequent API calls.
           $ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
         payment:
+          description: Requested payment record.
           $ref: ../../../models/payment/payment.yaml#/components/schemas/Payment