GSMA Open Gateway Carrier Billing Refund API

openapi: 3.0.3
info:
  description: |-
    Service Enabling Refunds against Operator Carrier Billing Systems

    # Introduction

    The Carrier Billing Refund API provides programmable interface for developers and other users (capabilities consumers) to perform a refund over a given payment.
    The API provides management of a refund entity and its associated lifecycle.

    # Relevant terms and definitions

    - **Carrier Billing**:
    An online payment process which allows users to make purchases by charging payments against Telco Operator Billing Systems, accordingly to the user's configuration in the Telco Operator. In a common usage in the industry, the payment is processed on current account balance or charged on next bill generated for this line.

    - **Payment**:
    The process of paying for a (set of) good(s)/service(s).

    - **Refund**:
    The process of returning the amount involved in a given payment (totally or partially) back to the user.

    # API Functionality

    This API allows to third party clients to request the refund of a given payment, as well as to retrieve information about a specific refund or a list of refunds.

    The API provides several endpoints/operations:
    - An endpoint to request a refund, named `createRefund`.
    - A set of endpoints to retrieve information about a list of refunds or a specific refund (identified by its specific `refundId`), named `retrieveRefunds` and `retrieveRefund` respectively.
    - A callback endpoint where API Server can send notifications about a refund procedure, as defined within `createRefund` operation, towards the `sink` when provided by API client.
    - An endpoint to retrieve remaining amount on a payment taken into consideration processed refund, named `retrievePaymentRemainingAmount`.

    State transitions:

    If `createRefund` is a **SYNC** process:
    - Response contains `refundId` and refundStatus=`succeeded`.
    - In case of any error scenario `refundId` is not created.

    If `createRefund` is an **ASYNC** process:
    - Response contains `refundId` and refundStatus=`processing`. After completion:
      - When refund is successfully completed then refundStatus=`succeeded`.
      - When refund is not successfully performed then refundStatus=`denied`.
    - In case of any error scenario `refundId` is not created. That means a `denied` Refund is not considerated as an error for the ASYNC process, because a `denied` Refund is a refund that has been created (i.e. the refund resource exists) and after applying the internal business logic has been settled to `denied` refundStatus.

    # Generic Clarification about optional parameters

    Regarding optional parameters, they can be conditionally mandatory for a Telco Operator to implement them based on business scenarios or applicable regulations in a given market.

    NOTE: Within a given market, in a multi Telco Operator ecosystem, the set of optional parameters to be implemented MUST be aligned among involved Telco Operators.

    # Authorization and authentication

    The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile.

    The specific authorization flows to be used will be agreed upon during the onboarding process, happening between the API consumer and the API provider, taking into account the declared purpose for accessing the API, whilst also being subject to the prevailing legal framework dictated by local legislation.

    In cases where personal 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 three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design.

    # Additional CAMARA error responses

    The list of error codes in this API specification is not exhaustive. Therefore the API specification may not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`.

    Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified in the `API Readiness Checklist` document associated to this API version.

    As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API.

    # Further info and support

    (FAQs will be added in a later version of the documentation)
  version: wip
  title: Carrier Billing Refund
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  x-camara-commonalities: wip
externalDocs:
  description: Product documentation at Camara
  url: https://github.com/camaraproject/CarrierBillingCheckOut
servers:
  - url: "{apiRoot}/carrier-billing-refund/vwip"
    variables:
      apiRoot:
        default: http://localhost:9091
        description: API root, defined by the service provider
tags:
  - name: Refund
    description: Operations to manage Refund procedure
paths:
  /payments/{paymentId}/refunds:
    post:
      security:
        - openId:
            - carrier-billing-refund:refunds:create
      tags:
        - Refund
      summary: Create a new Refund
      operationId: createRefund
      description: Create a new refund for an existing payment. Refund can be `total` or `partial`. This procedure MUST be always limited to the API client which performed the related payment.
      parameters:
        - name: paymentId
          in: path
          description: The payment identifier for which the payment refund is requested.
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/x-correlator"
      requestBody:
        description: Refund transaction
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateRefund"
        required: true
      callbacks:
        notifications:
          "{$request.body#/sink}":
            post:
              security:
                - {}
                - notificationsBearerAuth: []
              tags:
                - Refund Notifications
              summary: Carrier Billing refund notifications
              operationId: createRefundNotification
              description: |
                Important: This endpoint is exposed by the API client, accepting requests in the defined format.
                The Carrier Billing server will call this endpoint whenever any carrier billing related event occurs.
              parameters:
                - $ref: "#/components/parameters/x-correlator"
              requestBody:
                description: Creates a new carrier billing refund notification
                content:
                  application/cloudevents+json:
                    schema:
                      $ref: "#/components/schemas/CloudEvent"
                required: true
              responses:
                "204":
                  description: Successful notification
                  headers:
                    x-correlator:
                      $ref: "#/components/headers/x-correlator"
                "400":
                  $ref: "#/components/responses/Generic400"
                "401":
                  $ref: "#/components/responses/Generic401"
                "403":
                  $ref: "#/components/responses/Generic403"
                "410":
                  $ref: "#/components/responses/Generic410"
                "429":
                  $ref: "#/components/responses/Generic429"
      responses:
        "201":
          description: Created
          headers:
            x-correlator:
              $ref: "#/components/headers/x-correlator"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Refund"
        "400":
          $ref: "#/components/responses/RefundInvalid400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/RefundPermissionDenied403"
        "404":
          $ref: "#/components/responses/Generic404"
        "422":
          $ref: "#/components/responses/CreateRefundUnprocessableContent422"
        "409":
          $ref: "#/components/responses/Generic409"
        "429":
          $ref: "#/components/responses/Generic429"
    get:
      security:
        - openId:
            - carrier-billing-refund:refunds:read
      tags:
        - Refund
      summary: Get a list of refunds
      operationId: retrieveRefunds
      description: |-
        Retrieve a list of refunds and their details for a specific payment, identified by its `paymentId`, based on some filtering criteria.
        Regardless the refund criteria provided, response MUST be always limited to refunds performed by the API client (i.e same oAuth credentials) triggering this request.
        This is to guarantee no API client can check refunds performed by other, therefore avoiding any legal or privacy topic.

        When Access Token is issued for a given user phone number, the list of refunds returned would be only the ones associated to that user phone number and API client. When Access Token is not associated to a user phone number, therefore only associated to API client the list of refunds returned would be all the ones managed by that API client.

        Considerations regarding `refundCreationDate.gte`, `refundCreationDate.lte`:
        - If both included, return refunds in that date range
        - If no one included, no filtering by date range is applied
        - If only settled `refundCreationDate.gte`, `refundCreationDate.lte` is considered current date-time
        - If only settled `refundCreationDate.lte`, every refund existing in the Operator billing system until such date is returned
      parameters:
        - name: paymentId
          in: path
          description: Payment identifier for which their refunds are queried
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/x-correlator"
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PerPage"
        - $ref: "#/components/parameters/StartRefundCreationDate"
        - $ref: "#/components/parameters/EndRefundCreationDate"
        - $ref: "#/components/parameters/Order"
        - $ref: "#/components/parameters/RefundStatus"
        - $ref: "#/components/parameters/MerchantIdentifier"
      responses:
        "200":
          description: OK
          headers:
            x-correlator:
              $ref: "#/components/headers/x-correlator"
            Content-Last-Key:
              $ref: "#/components/headers/Content-Last-Key"
            X-Total-Count:
              $ref: "#/components/headers/X-Total-Count"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RefundArray"
        "400":
          $ref: "#/components/responses/GetRefundsInvalid400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/Generic404"
        "429":
          $ref: "#/components/responses/Generic429"
  /payments/{paymentId}/refunds/{refundId}:
    get:
      security:
        - openId:
            - carrier-billing-refund:refunds:read
      tags:
        - Refund
      summary: Get refund details
      operationId: retrieveRefund
      description: |-
        Retrieve refund details for a given refund.

        When Access Token is issued for a given user phone number, the refund details would be returned in case the `refundId` is associated to that user phone number and API client, otherwise `404 NOT_FOUND` will be returned. When Access Token is not associated to a user phone number, the refund details are returned in case the API client managed that refund.
      parameters:
        - name: paymentId
          in: path
          description: Payment identifier associated to the `refundId`
          required: true
          schema:
            type: string
        - name: refundId
          in: path
          description: Refund identifier that was obtained from the create refund operation
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/x-correlator"
      responses:
        "200":
          description: OK
          headers:
            x-correlator:
              $ref: "#/components/headers/x-correlator"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Refund"
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/Generic404"
        "429":
          $ref: "#/components/responses/Generic429"
  /payments/{paymentId}/refunds/remaining-amount:
    get:
      security:
        - openId:
            - carrier-billing-refund:refunds:read
      tags:
        - Refund
      summary: Get remaining amount not refunded for a given payment
      operationId: retrievePaymentRemainingAmount
      description: |-
        Retrieve remaining amount not yet refunded for a given payment. This amount refers to the pending amount never requested to be refunded (i.e. a refund not yet consolidated -processing- implies that such an amount is not part of the remaining amount until final status for that procedure is reached). Some cases below to illustrate the behaviour:

        **Case_1:** Payment of 80 EUR, with 2 partial `succedeed` Refunds, each of them of 20 EUR
          - remainingAmount: 40 EUR

        **Case_2:** Payment of 80 EUR, with 2 partial Refunds, one `succeeded` of 20 EUR and other `processing` of 15 EUR
          - remainingAmount: 45 EUR (API cannot return 60 EUR, because there is an ongoing refund process)

            ***SubCase_A***: Second partial Refund of 15 EUR is `succeeded`
              - remainingAmount: 45 EUR

            ***SubCase_B***: Second partial Refund of 15 EUR is `denied`
              - remainingAmount: 60 EUR

        **Case_3:** Payment of 80 EUR, with 1 total `succeeded` Refund
          - remainingAmount: 0 EUR

        **Case_4:** Payment of 80 EUR, with 1 total `processing` Refund
          - remainingAmount: 0 EUR (API cannot return 80 EUR, because there is an ongoing refund process)

            ***SubCase_A***: Total Refund is `succeeded`
              - remainingAmount: 0 EUR

            ***SubCase_B***: Total Refund is `denied`
              - remainingAmount: 80 EUR

        When Access Token is issued for a given user phone number, information would be returned in case the `paymentId` is associated to that user phone number and API client, otherwise `404 NOT_FOUND` will be returned. When Access Token is not associated to a user phone number, the information is returned in case the API client managed that payment.
      parameters:
        - name: paymentId
          in: path
          description: Payment identifier associated to the `refundId`
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/x-correlator"
      responses:
        "200":
          description: OK
          headers:
            x-correlator:
              $ref: "#/components/headers/x-correlator"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentRemainingAmount"
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/Generic404"
        "429":
          $ref: "#/components/responses/Generic429"
components:
  securitySchemes:
    openId:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
    notificationsBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: "{$request.body#/sinkCredential.credentialType}"
  schemas:
    XCorrelator:
      type: string
      pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$
      example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"
    CreateRefund:
      type: object
      description: Information to create a Refund resource.
      required:
        - type
      properties:
        type:
          type: string
          description: |-
            Type of refund.
            - `total` stands for a final refund, where whole amount is refunded so as it is not indicated by API Consumer. No more refunds are allowed for that `paymentId`.
            - `partial` stands for a partial refund, whose amount is indicated by API Consumer. More refunds are allowed for that `paymentId`.
          enum:
            - total
            - partial
        reason:
          type: string
          description: Reason provided to request the refund. Optionally provided by the user or the merchant.
        sink:
          type: string
          format: uri
          pattern: ^https:\/\/.+$
          description: The address to which events shall be delivered, using the HTTP protocol.
          example: "https://endpoint.example.com/sink"
        sinkCredential:
          allOf:
            - description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target.
            - $ref: "#/components/schemas/SinkCredential"
      discriminator:
        propertyName: type
        mapping:
          total: "#/components/schemas/CreateTotalRefund"
          partial: "#/components/schemas/CreatePartialRefund"
    CreateTotalRefund:
      allOf:
        - $ref: "#/components/schemas/CreateRefund"
        - type: object
          required:
            - amountTransaction
          properties:
            amountTransaction:
              $ref: "#/components/schemas/AmountTransactionTotalRefund"
    CreatePartialRefund:
      allOf:
        - $ref: "#/components/schemas/CreateRefund"
        - type: object
          required:
            - amountTransaction
          properties:
            amountTransaction:
              $ref: "#/components/schemas/AmountTransactionPartialRefund"
    Refund:
      type: object
      description: Information about a Refund resource.
      required:
        - refundId
        - refundStatus
        - refundCreationDate
        - type
      properties:
        refundId:
          type: string
          description: Unique Identifier of the refund
          example: "AK234rfweSBuWGFUEWFGWEVWRV"
        refundStatus:
          type: string
          description: Specifies the refund status (`processing`, `denied`, `succeeded`).
          example: "processing"
        type:
          type: string
          description: |-
            Type of refund.
            - `total` stands for a final refund, where whole amount is refunded so as it is not indicated by API Consumer. No more refunds are allowed for that `paymentId`.
            - `partial` stands for a partial refund, whose amount is indicated by API Consumer. More refunds are allowed for that `paymentId`.
          enum:
            - total
            - partial
        refundCreationDate:
          type: string
          format: date-time
          description: Date time when the refund is created in server database. This is a technical information. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
        refundDate:
          type: string
          format: date-time
          description: Date time when the refund is effectively performed. This is a business information. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
        reason:
          type: string
          description: Reason provided to request the refund. Optionally provided by the user or the merchant.
        sink:
          type: string
          format: uri
          pattern: ^https:\/\/.+$
          description: The address to which events shall be delivered, using the HTTP protocol.
          example: "https://endpoint.example.com/sink"
      discriminator:
        propertyName: type
        mapping:
          total: "#/components/schemas/TotalRefund"
          partial: "#/components/schemas/PartialRefund"
    TotalRefund:
      allOf:
        - $ref: "#/components/schemas/Refund"
        - type: object
          required:
            - amountTransaction
          properties:
            amountTransaction:
              $ref: "#/components/schemas/AmountTransactionTotalRefund"
    PartialRefund:
      allOf:
        - $ref: "#/components/schemas/Refund"
        - type: object
          required:
            - amountTransaction
          properties:
            amountTransaction:
              $ref: "#/components/schemas/AmountTransactionPartialRefund"
    AmountTransactionTotalRefund:
      type: object
      required:
        - refundAmount
        - referenceCode
      properties:
        clientCorrelator:
          type: string
          description:
            Uniquely identifies this create refund request. If there is
            a communication failure during the refund request, using the same clientCorrelator
            when retrying the request allows the operator to avoid applying the same
            charge twice. This field SHOULD be present.
          example: "req-12f2pgh448gh2hvrfrv"
        refundAmount:
          $ref: "#/components/schemas/RefundAmountTotalRefund"
        referenceCode:
          type: string
          description:
            Merchant generated refund reference to uniquely identify the
            request, for instance, in the case of disputes.
          example: "ref-refund-834tfr2rA3v8r8vr3rv"
    RefundAmountTotalRefund:
      type: object
      description: Information for a `total` refund. Whole amount is refunded so as it is not needed to be provided, then it can be an empty object unless `merchantIdentifier` is indicated.
      properties:
        chargingMetaData:
          $ref: "#/components/schemas/ChargingMetaData"
    AmountTransactionPartialRefund:
      type: object
      required:
        - refundAmount
        - referenceCode
      properties:
        clientCorrelator:
          type: string
          description:
            Uniquely identifies this create refund request. If there is
            a communication failure during the refund request, using the same clientCorrelator
            when retrying the request allows the operator to avoid applying the same
            charge twice. This field SHOULD be present.
          example: "req-12f2pgh448gh2hvrfrv"
        refundAmount:
          $ref: "#/components/schemas/RefundAmountPartialRefund"
        referenceCode:
          type: string
          description:
            Merchant generated refund reference to uniquely identify the
            request, for instance, in the case of disputes.
          example: "ref-refund-834tfr2rA3v8r8vr3rv"
    RefundAmountPartialRefund:
      type: object
      description: Information for a `partial` refund. Amount to be refunded is required.
      required:
        - chargingInformation
      properties:
        chargingInformation:
          $ref: "#/components/schemas/ChargingInformation"
        chargingMetaData:
          $ref: "#/components/schemas/ChargingMetaData"
        refundDetails:
          $ref: "#/components/schemas/RefundDetails"
    RefundArray:
      description: A list of refund(s)
      type: array
      minItems: 0
      items:
        $ref: "#/components/schemas/Refund"
    SinkCredential:
      type: object
      properties:
        credentialType:
          type: string
          enum:
            - PLAIN
            - ACCESSTOKEN
            - REFRESHTOKEN
          description: "The type of the credential. Only `ACCESSTOKEN` is supported so far."
      discriminator:
        propertyName: credentialType
        mapping:
          PLAIN: "#/components/schemas/PlainCredential"
          ACCESSTOKEN: "#/components/schemas/AccessTokenCredential"
          REFRESHTOKEN: "#/components/schemas/RefreshTokenCredential"
      required:
        - credentialType
    PlainCredential:
      type: object
      description: A plain credential as a combination of an identifier and a secret.
      allOf:
        - $ref: "#/components/schemas/SinkCredential"
        - type: object
          required:
            - identifier
            - secret
          properties:
            identifier:
              description: The identifier might be an account or username.
              type: string
            secret:
              description: The secret might be a password or passphrase.
              type: string
    AccessTokenCredential:
      type: object
      description: An access token credential.
      allOf:
        - $ref: "#/components/schemas/SinkCredential"
        - type: object
          properties:
            accessToken:
              description: REQUIRED. An access token is a previously acquired token granting access to the target resource.
              type: string
            accessTokenExpiresUtc:
              type: string
              format: date-time
              description: REQUIRED. An absolute (UTC) timestamp at which the token shall be considered expired. Token expiration should occur after the expiration of the requested payment refund, allowing the client to be notified of any changes during the payment refund's existence. If the token expires while the payment refund is still active, the client will stop receiving notifications. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
            accessTokenType:
              description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)).
              type: string
              enum:
                - bearer
          required:
            - accessToken
            - accessTokenExpiresUtc
            - accessTokenType
    RefreshTokenCredential:
      type: object
      description: An access token credential with a refresh token.
      allOf:
        - $ref: "#/components/schemas/SinkCredential"
        - type: object
          properties:
            accessToken:
              description: REQUIRED. An access token is a previously acquired token granting access to the target resource.
              type: string
            accessTokenExpiresUtc:
              type: string
              format: date-time
              description: REQUIRED. An absolute (UTC) timestamp at which the token shall be considered expired. Token expiration should occur after the expiration of the requested payment refund, allowing the client to be notified of any changes during the payment refund's existence. If the token expires while the payment refund is still active, the client will stop receiving notifications. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
            accessTokenType:
              description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)).
              type: string
              enum:
                - bearer
            refreshToken:
              description: REQUIRED. An refresh token credential used to acquire access tokens.
              type: string
            refreshTokenEndpoint:
              type: string
              format: uri
              description: REQUIRED. A URL at which the refresh token can be traded for an access token.
      required:
        - accessToken
        - accessTokenExpiresUtc
        - accessTokenType
        - refreshToken
        - refreshTokenEndpoint
    ChargingInformation:
      type: object
      required:
        - amount
        - currency
        - description
      properties:
        amount:
          type: number
          format: float
          multipleOf: 0.001
          minimum: 0.001
          description: Amount to be refunded.
          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 to be used for information and billing text
          example: "FIFA EA Sports 24"
        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
          minimum: 0
          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
    ChargingMetaData:
      type: object
      properties:
        merchantIdentifier:
          type: string
          description: Indicates the merchant identifier. Allows aggregators/partners to specify the actual merchant identifier
          example: "eas-12345"
    RefundDetails:
      type: array
      description: Detailed description of the concepts/items considered within a specific refund procedure.
      minItems: 1
      items:
        $ref: "#/components/schemas/RefundItem"
    RefundItem:
      type: object
      required:
        - paymentItemId
        - amount
        - currency
        - description
      properties:
        paymentItemId:
          type: string
          description: |-
            Unique payment item identifier to which this refund item is related to. Relevant when indicating `refundDetails` to correlate information for a refund regarding this `paymentItemId`.
          example: "3goug3uvu32v3b"
        amount:
          type: number
          format: float
          multipleOf: 0.001
          minimum: 0.001
          description: Specific amount to be refunded referred to a specific item.
          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 to be used for information and billing text referred to a specific item.
          example: "FIFA EA Sports 24"
        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
          minimum: 0
          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
    PaymentRemainingAmount:
      type: object
      description: Remaining Amount of a given payment not refunded yet.
      required:
        - amount
        - currency
      properties:
        amount:
          type: number
          format: float
          multipleOf: 0.001
          minimum: 0
          description: Specific amount not yet refunded for the payment. When takes value `0` it means whole payment has been refunded.
          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"
        isTax

# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gsma/refs/heads/main/openapi/gsma-open-gateway-carrier-billing-refund-openapi.yml