refund_proposal_and_payment_aligment

code/API_definitions/carrier_billing.yaml

@@ -26,7 +26,7 @@ info:
 
     This API allows to third party clients to request the payment of a (set of) digital good(s)/service(s), as well as to retrieve information about a specific payment or a list of payments.
 
-    In the scope of **version v0.2, only one-off payments are covered**. Recurrent payments (a.k.a. payment subscriptions) are not covered so far.
+    In the scope of **version v0.3, only one-off payments are covered**. Recurrent payments (a.k.a. payment subscriptions) are not covered so far.
 
     The API provides several endpoints/operations:
     - An endpoint to request a 1-STEP Payment, named `createPayment`.
@@ -97,10 +97,16 @@ info:
 
     After `cancelPayment`, status=`cancelled`.
 
+    # Authorization and authentication
+
+    CAMARA guidelines defines a set of authorization flows which can grant API clients access to the API functionality, as outlined in the document [CAMARA-API-access-and-user-consent.md](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md). Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation.
+
+    It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control.
+
     # Further info and support
 
     (FAQs will be added in a later version of the documentation)
-  version: 0.2.1
+  version: 0.3.0-wip
   title: Carrier Billing
   termsOfService: http://swagger.io/terms/
   contact:
@@ -630,6 +636,10 @@ components:
           type: string
           format: date-time
           description: Date time when the payment is effectively performed. This is a business information. It must follow RFC 3339 and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z).
+        paymentRemainingAmount:
+          allOf:
+            - $ref: "#/components/schemas/PaymentRemainingAmount"
+            - description: Remaining Amount of a given payment not refunded yet. Only included when a payment has been refunded at least one time. Check Carrier Billing Refund API for details.
         webhook:
           allOf:
             - $ref: "#/components/schemas/Webhook"
@@ -647,6 +657,37 @@ components:
           type: string
           description: Authentification token for callback endpoint
           example: "c8974e592c2fa383d4a3960714"
+    PaymentRemainingAmount:
+      type: object
+      required:
+        - amount
+        - currency
+      properties:
+        amount:
+          type: number
+          format: float
+          multipleOf: 0.001
+          description: Specific amount not yet refunded for the payment.
+          example: 100
+        currency:
+          type: string
+          description: Currency code in which amount is expressed as defined in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html).
+          example: "EUR"
+        description:
+          type: string
+          description: Description text (human readable) to contextualize this amount. Optionally indicated by Telco Operator.
+          example: "Current Amount not refunded so far"
+        isTaxIncluded:
+          type: boolean
+          default: false
+          description: If true, the `amount` is tax included, if false the `amount` is provided without tax. In both cases, `taxAmount` could be indicated to provide tax amount.
+        taxAmount:
+          type: number
+          format: float
+          multipleOf: 0.001
+          description: |
+            The tax amount refunded by the merchant. Indicated when the merchant is the one applying taxes. This field also provides an indicator to the downstream billing system.
+          example: 21
     AmountTransaction:
       required:
         - phoneNumber
@@ -678,7 +719,7 @@ components:
         transactionOperationStatus:
           type: string
           description:
-            Specifies the payment status (`processing`, `pending_validation`, `denied`, `reserved`, `succeeded`, `cancelled`).
+            Specifies the payment status (`processing`, `pending_validation`, `denied`, `reserved`, `succeeded`, `cancelled`, `refund_in_progress`, `totally_refunded`, `partially_refunded`).
           example: "processing"
         resourceURL:
           type: string
@@ -817,7 +858,7 @@ components:
         transactionOperationStatus:
           type: string
           description:
-            Specifies the payment status (`processing`, `pending_validation`, `denied`, `reserved`, `succeeded`, `cancelled`).
+            Specifies the payment status (`processing`, `pending_validation`, `denied`, `reserved`, `succeeded`, `cancelled`, `refund_in_progress`, `totally_refunded`, `partially_refunded`).
           example: "processing"
         resourceURL:
           type: string
@@ -1684,6 +1725,9 @@ components:
             - reserved
             - succeeded
             - cancelled
+            - refund_in_progress
+            - totally_refunded
+            - partially_refunded
     MerchantIdentifier:
       description: Merchant identifier to filter the results
       in: query