openapi: 3.2.0
info:
  description: "Service Enabling Refunds against Operator Carrier Billing Systems\n\n# Introduction\n\nThe Carrier Billing Refund API provides programmable interface for developers and other users (capabilities consumers) to perform a refund over a given payment.\nThe API provides management of a refund entity and its associated lifecycle.\n\n# Relevant terms and definitions\n\n- **Carrier Billing**:\nAn 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.\n\n- **Payment**:\nThe process of paying for a (set of) good(s)/service(s).\n\n- **Refund**:\nThe process of returning the amount involved in a given payment (totally or partially) back to the user.\n\n# API Functionality\n\nThis 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.\n\nThe API provides several endpoints/operations:\n- An endpoint to request a refund, named `createRefund`.\n- 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.\n- 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.\n- An endpoint to retrieve remaining amount on a payment taken into consideration processed refund, named `retrievePaymentRemainingAmount`.\n\nState transitions:\n\nIf `createRefund` is a **SYNC** process:\n- Response contains `refundId` and refundStatus=`succeeded`.\n- In case of any error scenario `refundId` is not created.\n\nIf `createRefund` is an **ASYNC** process:\n- Response contains `refundId` and refundStatus=`processing`. After completion:\n  - When refund is successfully completed then refundStatus=`succeeded`.\n  - When refund is not successfully performed then refundStatus=`denied`.\n- 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.\n\n# Generic Clarification about optional parameters\n\nRegarding 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.\n\nNOTE: 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.\n\n# Authorization and authentication\n\nThe \"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.\n\nThe 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.\n\nIn 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.\n\n# Additional CAMARA error responses\n\nThe 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`.\n\nPlease 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.\n\nAs a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API.\n\n# Further info and support\n\n(FAQs will be added in a later version of the documentation)"
  version: wip
  title: Carrier Billing Refund API
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  x-camara-commonalities: wip
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:\n\n**Case_1:** Payment of 80 EUR, with 2 partial `succedeed` Refunds, each of them of 20 EUR\n  - remainingAmount: 40 EUR\n\n**Case_2:** Payment of 80 EUR, with 2 partial Refunds, one `succeeded` of 20 EUR and other `processing` of 15 EUR\n  - remainingAmount: 45 EUR (API cannot return 60 EUR, because there is an ongoing refund process)\n\n    ***SubCase_A***: Second partial Refund of 15 EUR is `succeeded`\n      - remainingAmount: 45 EUR\n\n    ***SubCase_B***: Second partial Refund of 15 EUR is `denied`\n      - remainingAmount: 60 EUR\n\n**Case_3:** Payment of 80 EUR, with 1 total `succeeded` Refund\n  - remainingAmount: 0 EUR\n\n**Case_4:** Payment of 80 EUR, with 1 total `processing` Refund\n  - remainingAmount: 0 EUR (API cannot return 80 EUR, because there is an ongoing refund process)\n\n    ***SubCase_A***: Total Refund is `succeeded`\n      - remainingAmount: 0 EUR\n\n    ***SubCase_B***: Total Refund is `denied`\n      - remainingAmount: 80 EUR\n\nWhen 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:
  schemas:
    ErrorInfo:
      type: object
      required:
      - status
      - code
      - message
      properties:
        status:
          type: integer
          description: HTTP response status code
        code:
          type: string
          description: A human-readable code to describe the error
        message:
          type: string
          description: A human-readable description of what the event represents
    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
    CloudEvent:
      description: The notification format
      required:
      - id
      - source
      - specversion
      - type
      - time
      properties:
        id:
          type: string
          description: Identifier of this event, that must be unique in the source context.
          minLength: 1
          example: sd5e-uy52-88t4-za66
        source:
          $ref: '#/components/schemas/Source'
        type:
          type: string
          description: Type of event as defined in each CAMARA API
          minLength: 25
          example: org.camaraproject.carrier-billing.v0.payment-reserved
        specversion:
          type: string
          description: Version of the specification to which this event conforms (must be 1.0 if it conforms to cloudevents 1.0.2 version)
          minLength: 3
          example: '1.0'
        datacontenttype:
          type: string
          description: media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs
          example: application/json
        data:
          type: object
          description: Event details payload described in each CAMARA API and referenced by its type
        time:
          $ref: '#/components/schemas/DateTime'
      discriminator:
        propertyName: type
        mapping:
          org.camaraproject.carrier-billing-refund.v0.refund-completed: '#/components/schemas/EventRefundCompleted'
          org.camaraproject.carrier-billing-refund.v0.refund-denied: '#/components/schemas/EventRefundDenied'
          org.camaraproject.carrier-billing-refund.v0.refund-in-bill: '#/components/schemas/EventRefundInBill'
    XCorrelator:
      type: string
      pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$
      example: b4333c46-49c0-4f62-80d7-f0ef930f1c46
    DateTime:
      type: string
      format: date-time
      description: Timestamp when the occurrence happened. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
      example: '2023-11-03T12:27:10Z'
    Source:
      type: string
      format: uri-reference
      minLength: 1
      description: "Identifies the context in which an event happened - be a non-empty `URI-reference` like:\n- URI with a DNS authority:\n  * https://github.com/cloudevents\n  * mailto:cncf-wg-serverless@lists.cncf.io\n- Universally-unique URN with a UUID:\n  * urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66\n- Application-specific identifier:\n  * /cloudevents/spec/pull/123\n  * 1-555-123-4567"
      example: https://notificationSendServer12.supertelco.com
    RefundArray:
      description: A list of refund(s)
      type: array
      minItems: 0
      items:
        $ref: '#/components/schemas/Refund'
    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'
    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
        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
    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'
  responses:
    GetRefundsInvalid400:
      description: "Invalid input. In addition to regular INVALID_ARGUMENT scenario other scenarios may exist:\n  - Inconsistent refundCreationDate.gte and refundCreationDate.lte values (\"code\": \"CARRIER_BILLING_REFUND.INVALID_DATE_RANGE\",\"message\": \"Client specified an invalid date range.\").\n  - Request out of range (\"code\": \"OUT_OF_RANGE\",\"message\": \"Client specified an invalid range.\").\n  - Too many matching records found (\"code\": \"CARRIER_BILLING_REFUND.TOO_MANY_MATCHING_RECORDS\",\"message\": \"Too many matching records found. Specify additional/suitable criteria to limit the number of records.\")."
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorInfo'
            - type: object
              properties:
                status:
                  enum:
                  - 400
                code:
                  enum:
                  - INVALID_ARGUMENT
                  - OUT_OF_RANGE
                  - CARRIER_BILLING_REFUND.INVALID_DATE_RANGE
                  - CARRIER_BILLING_REFUND.TOO_MANY_MATCHING_RECORDS
          examples:
            GENERIC_400_INVALID_ARGUMENT:
              summary: Generic Invalid Argument
              description: Invalid Argument. Generic Syntax Exception
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: Client specified an invalid argument, request body or query param.
            GENERIC_400_INVALID_DATE_RANGE:
              summary: Generic Invalid Date Range
              description: Inconsistent refundCreationDate.gte and refundCreationDate.lte values
              value:
                status: 400
                code: CARRIER_BILLING_REFUND.INVALID_DATE_RANGE
                message: Client specified an invalid date range.
            GENERIC_400_OUT_OF_RANGE:
              summary: Generic Out Of Range
              description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested
              value:
                status: 400
                code: OUT_OF_RANGE
                message: Client specified an invalid range.
            GENERIC_400_TOO_MANY_MATCHING_RECORDS:
              summary: Generic Too Many Matching Records
              description: Too many matching records found
              value:
                status: 400
                code: CARRIER_BILLING_REFUND.TOO_MANY_MATCHING_RECORDS
                message: Too many matching records found. Specify additional/suitable criteria to limit the number of records.
    Generic409:
      description: Conflict
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorInfo'
            - type: object
              properties:
                status:
                  enum:
                  - 409
                code:
                  enum:
                  - ALREADY_EXISTS
          examples:
            GENERIC_409_ALREADY_EXISTS:
              summary: Generic Already Exists
              description: Trying to create an existing resource
              value:
                status: 409
                code: ALREADY_EXISTS
                message: The resource that a client tried to create already exists.
    Generic403:
      description: Forbidden
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorInfo'
            - type: object
              properties:
                status:
                  enum:
                  - 403
                code:
                  enum:
                  - PERMISSION_DENIED
          examples:
            GENERIC_403_PERMISSION_DENIED:
              description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
              value:
                status: 403
                code: PERMISSION_DENIED
                message: Client does not have sufficient permissions to perform this action.
    Generic404:
      description: Resource Not Found
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorInfo'
            - type: object
              properties:
                status:
                  enum:
                  - 404
                code:
                  enum:
                  - NOT_FOUND
          examples:
            GENERIC_404_NOT_FOUND:
              summary: Generic Not Found
              description: Resource is not found
              value:
                status: 404
                code: NOT_FOUND
                message: The specified resource is not found.
    Generic410:
      description: Gone
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorInfo'
            - type: object
              properties:
                status:
                  enum:
                  - 410
                code:
                  enum:
                  - GONE
          examples:
            GENERIC_410_GONE:
              summary: Generic Gone
              description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available
              value:
                status: 410
                code: GONE
                message: Access to the target resource is no longer available.
    RefundInvalid400:
      description: "Invalid input.\nCommon INVALID_ARGUMENT scenarios usually are:\n  - Schema validation failed (\"code\": \"INVALID_ARGUMENT\",\"message\": \"Client specified an invalid argument, request body or query param.\").\n  - Currency is unknown or not authorized (\"code\": \"INVALID_ARGUMENT\",\"message\": \"Currency is unknown or not authorized.\").\n  - clientCorrelator still exist (\"code\": \"INVALID_ARGUMENT\",\"message\": \"clientCorrelator already exist on server.\").\n\nIn addition to regular INVALID_ARGUMENT scenario other scenarios may exist:\n  - Invalid sink credential (\"code\": \"INVALID_CREDENTIAL\",\"message\": \"Only Access token is supported\").\n  - Invalid sink credential access token (\"code\": \"INVALID_TOKEN\",\"message\": \"Only bearer token is supported\").\n  - Invalid sink (\"code\": \"INVALID_SINK\",\"message\": \"sink not valid for the specified protocol\")."
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorInfo'
            - type: object
              properties:
                status:
                  enum:
                  - 400
                code:
                  enum:
                  - INVALID_ARGUMENT
                  - INVALID_CREDENTIAL
                  - INVALID_TOKEN
                  - INVALID_SINK
          examples:
            GENERIC_400_INVALID_ARGUMENT:
              summary: Generic Invalid Argument
              description: Invalid Argument. Generic Syntax Exception
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: Client specified an invalid argument, request body or query param.
            GENERIC_400_WRONG_CURRENCY:
              summary: Generic Wrong Currency
              description: Currency is unknown or not authorized
              value:
                code: INVALID_ARGUMENT
                status: 400
                message: Currency is unknown or not authorized.
            GENERIC_400_DUPLICATE_CLIENT_CORRELATOR:
              summary: Generic Duplicate Client Correlator
              description: clientCorrelator still exist
              value:
                code: INVALID_ARGUMENT
                status: 400
                message: clientCorrelator already exist on server.
            GENERIC_400_INVALID_CREDENTIAL:
              summary: Generic Invalid Credential
              description: Invalid sink credential
              value:
                status: 400
                code: INVALID_CREDENTIAL
                message: Only Access token is supported
            GENERIC_400_INVALID_TOKEN:
              summary: Generic Invalid Token
              description: Invalid sink credential access token
              value:
                status: 400
                code: INVALID_TOKEN
                message: Only bearer token is supported
            GENERIC_400_INVALID_SINK:
              summary: Generic Invalid Sink
              description: Invalid sink value
              value:
                status: 400
                code: INVALID_SINK
                message: sink not valid for the specified protocol
    RefundPermissionDenied403:
      description: "Client does not have sufficient permission.\nIn addition to regular PERMISSION_DENIED scenario other scenarios may exist:\n  - Refund denied by business (\"code\": \"CARRIER_BILLING_REFUND.REFUND_DENIED\",\"message\": \"Refund denied by business.\").\n  - Payment not eligible for Refund (e.g. Payment conditions agreed do not allow refund) (\"code\": \"CARRIER_BILLING_REFUND.PAYMENT_NOT_ELIGIBLE_FOR_REFUND\",\"message\": \"Payment not eligible for refund.\")."
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorInfo'
            - type: object
              properties:
                status:
                  enum:
                  - 403
                code:
                  enum:
                  - PERMISSION_DENIED
                  - CARRIER_BILLING_REFUND.REFUND_DENIED
                  - CARRIER_BILLING_REFUND.PAYMENT_NOT_ELIGIBLE_FOR_REFUND
          examples:
            GENERIC_403_PERMISSION_DENIED:
              description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
              value:
                status: 403
                code: PERMISSION_DENIED
                message: Client does not have sufficient permissions to perform this action.
            GENERIC_403_REFUND_DENIED:
              summary: Generic Refund Denied
              description: Refund denied by business
              value:
                status: 403
                code: CARRIER_BILLING_REFUND.REFUND_DENIED
                message: Refund denied by business.
            GENERIC_403_PAYMENT_NOT_ELIGIBLE_FOR_REFUND:
              summary: Generic Payment Not Eligible for Refund
              description: Payment not eligible for Refund (e.g. Payment conditions agreed do not allow refund)
              value:
                status: 403
                code: CARRIER_BILLING_REFUND.PAYMENT_NOT_ELIGIBLE_FOR_REFUND
                message: Payment not eligible for refund.
    Generic429:
      description: Too Many Requests
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorInfo'
            - type: object
              properties:
                status:
                  enum:
                  - 429
                code:
                  enum:
                  - TOO_MANY_REQUESTS
          examples:
            GENERIC_429_TOO_MANY_REQUESTS:
              summary: Generic Too Many Requests
              description: Access to the API has been temporarily blocked due to rate or spike arrest limits being reached
              value:
                status: 429
                code: TOO_MANY_REQUESTS
                message: Rate limit reached.
    CreateRefundUnprocessableContent422:
      description: "Client indicates content that is understable by the Server but unable to be processed.\nScenarios considered:\n  - Unauthorized refund amount requested (\"code\": \"CARRIER_BILLING_REFUND.UNAUTHORIZED_AMOUNT\",\"message\": \"Unauthorized amount requested.\").\n  - Accumulated threshold refund amount for the user's mobile account overpassed (\"code\": \"CARRIER_BILLING_REFUND.USER_AMOUNT_THRESHOLD_OVERPASSED\",\"message\": \"Unauthorized refund request. Accumulated user mobile refunds overpass account amount threshold.\").\n  - Payment is not in suitable status for refund (\"code\": \"CARRIER_BILLING_REFUND.INVALID_PAYMENT_STATUS\",\"message\": \"Payment is not yet completed.\").\n  - Property `isTaxIncluded` has not the same value as related Payment (\"code\": \"CARRIER_BILLING_REFUND.TAXES_MANAGEMENT_MISMATCH\",\"message\": \"Inconsistent isTaxIncluded value with regards to related payment.\").\n  - Refund details provided are inconsistent with regards to the related Payment (\"code\": \"CARRIER_BILLING_REFUND.REFUND_DETAILS_MISMATCH\",\"message\": \"Inconsistent refundDetails information with regards to related payment.\")."
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorInfo'
            - type: object
              properties:
                status:
                  enum:
                  - 422
                code:
                  enum:
                  - CARRIER_BILLING_REFUND.UNAUTHORIZED_AMOUNT
                  - CARRIER_BILLING_REFUND.USER_AMOUNT_THRESHOLD_OVERPASSED
                  - CARRIER_BILLING_REFUND.INVALID_PAYMENT_STATUS
                  - CARRIER_BILLING_REFUND.TAXES_MANAGEMENT_MISMATCH
                  - CARRIER_BILLING_REFUND.REFUND_DETAILS_MISMATCH
          examples:
            GENERIC_422_UNAUTHORIZED_REFUND_AMOUNT:
              summary: Generic Unauthorized Refund Amount
              description: Unauthorized refund amount requested
              value:
                status: 422
                code: CARRIER_BILLING_REFUND.UNAUTHORIZED_AMOUNT
                message: Unauthorized amount requested.
            GENERIC_422_GENERIC_422_USER_MOBILE_ACCUMULATED_THRESHOLD_REFUND_AMOUNT_OVERPASSED:
              summary: Generic User Mobile Accumulated threshold Refund Amount Overpassed
              description: Accumulated threshold refund amount for the user's mobile account overpassed
              value:
                status: 422
                code: CARRIER_BILLING_REFUND.USER_AMOUNT_THRESHOLD_OVERPASSED
                message: Unauthorized refund request. Accumulated user mobile payments overpass account amount threshold.
            GENERIC_422_INVALID_PAYMENT_STATUS:
              summary: Generic Invalid Payment Status
              description: Payment is not in suitable status for refund
              value:
                status: 422
                code: CARRIER_BILLING_REFUND.INVALID_PAYMENT_STATUS
                message: Payment is not yet completed.
            GENERIC_422_TAXES_MANAGEMENT_MISMATCH:
              summary: Generic Taxes Management Mismatch
              description: Property `isTaxIncluded` has not the same value as related Payment
              value:
                status: 422
                code: CARRIER_BILLING_REFUND.TAXES_MANAGEMENT_MISMATCH
                message: Inconsistent isTaxIncluded value with regards to related payment.
            GENERIC_422_REFUND_DETAILS_MISMATCH:
              summary: Generic Refund Details Mismatch
              description: Refund details provided are inconsistent with regards to the related Payment
              value:
                status: 422
                code: CARRIER_BILLING_REFUND.REFUND_DETAILS_MISMATCH
                message: Inconsistent refundDetails information with regards to related payment.
    Generic400:
      description: Invalid input
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorInfo'
            - type: object
              properties:
                status:
                  enum:
                  - 400
                code:
                  enum:
                  - INVALID_ARGUMENT
          examples:
            GENERIC_400_INVALID_ARGUMENT:
              summary: Generic Invalid Argument
              description: Invalid Argument. Generic Syntax Exception
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: Client specified an invalid argument, request body or query param.
    Generic401:
      description: Unauthorized
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorInfo'
            - type: object
              properties:
                status:
                  enum:
                  - 401
                code:
                  enum:
                  - UNAUTHENTICATED
          examples:
            GENERIC_401_UNAUTHENTICATED:
              description: Request cannot be authenticated and a new authentication is required
              value:
                status: 401
                code: UNAUTHENTICATED
                message: Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required.
  parameters:
    Order:
      description: Used to return the sorted results in descending (default) or ascending order, based on `refundCreationDate` property
      in: query
      name: order
      required: false
      schema:
        default: desc
        enum:
        - desc
        - asc
        type: string
    EndRefundCreationDate:
      description: End `refundCreationDate` for running the query. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
      in: query
      name: refundCreationDate.lte
      required: false
      schema:
        format: date-time
        type: string
    PerPage:
      name: perPage
      in: query
      description: Requested number of resources to be provided in response
      schema:
        type: integer
        default: 10
    x-correlator:
      name: x-correlator
      in: header
      description: Correlation id for the different services
      schema:
        $ref: '#/components/schemas/XCorrelator'
    StartRefundCreationDate:
      description: Initial `refundCreationDate` for running the query. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
      in: query
      name: refundCreationDate.gte
      required: false
      schema:
        format: date-time
        type: string
    Page:
      name: page
      in: query
      description: Requested index to indicate the start of the resources to be provided in the response
      schema:
        type: integer
        default: 1
    MerchantIdentifier:
      description: Merchant identifier to filter the results
      in: query
      name: merchantIdentifier
      required: false
      schema:
        type: string
    RefundStatus:
      description: List of refund status to be considered for the query
      in: query
      name: refundStatus
      required: false
      schema:
        type: array
        items:
          type: string
          enum:
          - processing
          - denied
          - succeeded
  headers:
    x-correlator:
      description: Correlation id for the different services
      schema:
        $ref: '#/components/schemas/XCorrelator'
    Content-Last-Key:
      description: Indicates the index of the last result provided in the response
      schema:
        type: integer
    X-Total-Count:
      description: Total number of items matching criteria
      schema:
        type: integer
  securitySchemes:
    openId:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
    notificationsBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: '{$request.body#/sinkCredential.credentialType}'
externalDocs:
  description: Product documentation at Camara
  url: https://github.com/camaraproject/CarrierBillingCheckOut