From aecf86a1ce7330262908801348bc94ded325a648 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Fri, 12 Apr 2024 16:50:42 +0200 Subject: [PATCH 01/24] (refund_proposal_and_payment_aligment --- code/API_definitions/carrier_billing.yaml | 52 +- .../carrier_billing_refund.yaml | 1053 +++++++++++++++++ 2 files changed, 1101 insertions(+), 4 deletions(-) create mode 100644 code/API_definitions/carrier_billing_refund.yaml diff --git a/code/API_definitions/carrier_billing.yaml b/code/API_definitions/carrier_billing.yaml index 7bb30f8..5e86856 100644 --- a/code/API_definitions/carrier_billing.yaml +++ b/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 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 + 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 diff --git a/code/API_definitions/carrier_billing_refund.yaml b/code/API_definitions/carrier_billing_refund.yaml new file mode 100644 index 0000000..a72dfdf --- /dev/null +++ b/code/API_definitions/carrier_billing_refund.yaml @@ -0,0 +1,1053 @@ +openapi: 3.0.3 +info: + description: |- + Service Enabling Refunds against OB 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) to a given back to the user. + + # API Functionality + + This API allows to third party clients to request the refund ...., 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 `webhook.notificationUrl` when provided by API client. + + + State transitions: + + TBD + + # 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.1.0-wip + title: Carrier Billing Refunds + termsOfService: http://swagger.io/terms/ + contact: + email: project-email@sample.com + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html +externalDocs: + description: Product documentation at Camara + url: https://github.com/camaraproject/ +servers: + - url: "{apiRoot}/{basePath}" + variables: + apiRoot: + default: http://localhost:9091 + description: API root + basePath: + default: carrier-billing-refund/v0 + description: Base path for the carrier billing refund API +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: + - $ref: "#/components/parameters/x-correlator" + requestBody: + description: Refund transaction + content: + application/json: + schema: + $ref: "#/components/schemas/CreateRefund" + required: true + callbacks: + notifications: + "{$request.body#/webhook/notificationUrl}": + 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" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + "504": + $ref: "#/components/responses/Generic504" + responses: + "201": + description: Created + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/RefundCreated" + "400": + $ref: "#/components/responses/RefundInvalid400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/RefundPermissionDenied403" + "409": + $ref: "#/components/responses/Generic409" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + "504": + $ref: "#/components/responses/Generic504" + 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 (TBD). + 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: + - $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/TransactionOperationStatus" +# - $ref: "#/components/parameters/MerchantIdentifier" (OPEN) + 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/RefundReadPermissionDenied403" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + "504": + $ref: "#/components/responses/Generic504" + /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: 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-Last-Key: + $ref: "#/components/headers/Content-Last-Key" + X-Total-Count: + $ref: "#/components/headers/X-Total-Count" + content: + application/json: + schema: + $ref: "#/components/schemas/Refund" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/RefundReadPermissionDenied403" + "404": + $ref: "#/components/responses/Generic404" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + "504": + $ref: "#/components/responses/Generic504" +components: + securitySchemes: + openId: + type: openIdConnect + openIdConnectUrl: https://example.com/.well-known/openid-configuration + notificationsBearerAuth: + type: http + scheme: bearer + bearerFormat: "{$request.body#/webhook/notificationAuthToken}" + schemas: + CreateRefund: + type: object + required: + - amountTransaction + - type + properties: + amountTransaction: + $ref: "#/components/schemas/AmountTransactionInput" + type: + type: string + description: |- + Type of refund. + - `total` stands for a final refund, whose amount can be indicated by API Consumer (PENDING POINT). 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. + webhook: + allOf: + - $ref: "#/components/schemas/Webhook" + - description: Information to manage refund notifications + RefundCreated: + type: object + required: + - amountTransaction + - refundId + - refundCreationDate + - type + properties: + refundId: + type: string + description: Unique Identifier of the refund + example: "AK234rfweSBuWGFUEWFGWEVWRV" + type: + type: string + description: |- + Type of refund. + - `total` stands for a final refund, whose amount can be 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 + amountTransaction: + $ref: "#/components/schemas/AmountTransaction" + 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 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). + 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 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). + reason: + type: string + description: Reason provided to request the refund. Optionally provided by the user or the merchant. + webhook: + allOf: + - $ref: "#/components/schemas/Webhook" + - description: Information to manage refund notifications + RefundArray: + description: A list of refund(s) + type: array + minItems: 0 + items: + $ref: "#/components/schemas/Refund" + Refund: + type: object + required: + - amountTransaction + - refundId + - refundCreationDate + - type + properties: + refundId: + type: string + description: Unique Identifier of the refund + example: "AK234rfweSBuWGFUEWFGWEVWRV" + type: + type: string + description: |- + Type of refund. + - `total` stands for a final refund, whose amount can be 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 + amountTransaction: + $ref: "#/components/schemas/AmountTransaction" + 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 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). + 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 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). + reason: + type: string + description: Reason provided to request the refund. Optionally provided by the user or the merchant. + webhook: + allOf: + - $ref: "#/components/schemas/Webhook" + - description: Information to manage refund notifications + Webhook: + type: object + required: + - notificationUrl + properties: + notificationUrl: + type: string + description: Callback URL to allow asynchronous delivery of refund related events + example: "https://myservice.com/refund/events" + notificationAuthToken: + type: string + description: Authentification token for callback endpoint + example: "c8974e592c2fa383d4a3960714" + AmountTransaction: + required: + - refundAmount + - referenceCode + - transactionOperationStatus + type: object + 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 + refund twice. This field SHOULD be present. Same value as indicated in the request. + example: "req-12f2pgh448gh2hvrfrv" + refundAmount: + $ref: "#/components/schemas/RefundAmount" + referenceCode: + type: string + description: + Merchant generated refund reference to uniquely identify the + request, for instance, in the case of disputes. Same value as the one provided in the request. + example: "ref-refund-834tfr2rA3v8r8vr3rv" + transactionOperationStatus: + type: string + description: + Specifies the refund status (`processing`, `denied`, `succeeded`). + example: "processing" + serverReferenceCode: + type: string + description: + Reference to the charge or refund, provided by the server, + and meaningful to the server’s backend system for the purpose of reconciliation. + example: "ref-pay-834tfr2rA3v8r8vr3rv-serv" + AmountTransactionInput: + 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/RefundAmount" + referenceCode: + type: string + description: + Merchant generated refund reference to uniquely identify the + request, for instance, in the case of disputes. + example: "ref-refund-834tfr2rA3v8r8vr3rv" + RefundAmount: + type: object + required: + - chargingInformation + properties: + chargingInformation: + $ref: "#/components/schemas/ChargingInformation" +# chargingMetaData: +# $ref: "#/components/schemas/ChargingMetaData" + refundDetails: + $ref: "#/components/schemas/RefundDetails" + 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: + - amount + - currency + - description + properties: + amount: + type: number + format: float + multipleOf: 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 + 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 + ChargingInformation: + type: object + required: + - amount + - currency + - description + properties: + amount: + type: number + format: float + multipleOf: 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 + 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: +# merchantName: +# type: string +# description: Indicates the merchant name. Allows aggregators/partners to specify the actual merchant name +# example: "EA Sports" +# merchantIdentifier: +# type: string +# description: Indicates the merchant identifier. Allows aggregators/partners to specify the actual merchant identifier +# example: "eas-12345" +# fee: +# type: number +# format: float +# multipleOf: 0.01 +# description: Percentage of the amount to be received by the requester +# example: 10 +# purchaseCategoryCode: +# type: string +# description: A category defining the type of service, product or media being purchased +# example: "games" +# channel: +# type: string +# description: The channel over which the requester is interacting with the merchant (e.g. WAP, Web, SMS...) +# example: "web" +# serviceId: +# type: string +# description: The identifier of the partner/merchant service being purchased +# example: "games-online" +# productId: +# type: string +# description: The product identifier to be combined with the `serviceId` to uniquely identify the product being purchased. For example if the `serviceId` relates to a VOD service, the `productId` can specify the movie rented +# example: "138235321" + 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" + Source: + type: string + format: uri-reference + minLength: 1 + description: |- + Identifies the context in which an event happened - be a non-empty `URI-reference` like: + - URI with a DNS authority: + * https://github.com/cloudevents + * mailto:cncf-wg-serverless@lists.cncf.io + - Universally-unique URN with a UUID: + * urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 + - Application-specific identifier: + * /cloudevents/spec/pull/123 + * 1-555-123-4567 + example: "https://notificationSendServer12.supertelco.com" + DateTime: + type: string + format: date-time + description: Timestamp when the occurrence happened. Must adhere to RFC 3339. + example: "2023-11-03T12:27:10Z" + EventRefundCompleted: + description: Event structure for refund completed + allOf: + - $ref: "#/components/schemas/CloudEvent" + - type: object + properties: + data: + $ref: "#/components/schemas/RefundCompleted" + EventRefundDenied: + description: Event structure for refund denied + allOf: + - $ref: "#/components/schemas/CloudEvent" + - type: object + properties: + data: + $ref: "#/components/schemas/RefundDenied" + EventRefundInBill: + description: Event structure for refund in bill (i.e. confirmation about refund will be applied in next bill) + allOf: + - $ref: "#/components/schemas/CloudEvent" + - type: object + properties: + data: + $ref: "#/components/schemas/RefundInBill" + RefundCompleted: + allOf: + - description: Event detail structure for org.camaraproject.carrier-billing-refund.v0.refund-completed event + - $ref: "#/components/schemas/BasicEvent" + - type: object + required: + - refundDate + properties: + paymentDate: + type: string + description: Date when the refund 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). + format: date-time + example: "2023-11-03T12:27:08.312Z" + RefundDenied: + allOf: + - description: Event detail structure for org.camaraproject.carrier-billing-refund.v0.refund-denied event + - $ref: "#/components/schemas/BasicEvent" + - type: object + properties: + denialReason: + type: string + description: Indicates the business reason for denying the refund. + example: "User is blocked due to pending debt" + RefundInBill: + allOf: + - description: Event detail structure for org.camaraproject.carrier-billing-refund.v0.refund-in-bill event + - $ref: "#/components/schemas/BasicEvent" + BasicEvent: + type: object + description: Data type to provide basic refund event information + required: + - paymentId + - refundId + - status + - description + properties: + paymentId: + type: string + description: Unique Identifier of the payment + example: "AK234rfweSBuWGFUEWFGWEVWRV" + refundId: + type: string + description: Unique Identifier of the refund + example: "AK234rfweSBuWGFUEWFGWEVWRV" + status: + type: string + enum: + - succeeded + - failed + description: |- + Status of the refund procedure. Possible status are: + * `succeeded`: procedure was accomplished + * `failed`: procedure failed. + description: + type: string + description: Description of the notification, both used when process was `succeeded` or `failed` indicating in the latter case human understable reason about why process failed. + example: "Payment Notification" + ErrorInfo: + type: object + required: + - code + - message + - status + properties: + code: + type: string + description: Code given to this error + status: + type: integer + description: HTTP response status code + message: + type: string + description: Detailed error description + responses: + Generic400: + description: Invalid input + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + code: INVALID_ARGUMENT + status: 400 + message: "Schema validation failed at ..." + GetRefundsInvalid400: + description: |- + Invalid input. In addition to regular INVALID_ARGUMENT scenario other scenarios may exist: + - Inconsistent startDate and endDate values ("code": "CARRIER_BILLING.INVALID_DATE_RANGE","message": "Client specified an invalid date range"). + - Request out of range ("code": "OUT_OF_RANGE","message": "Client specified an invalid range"). + - Too many matching records found ("code": "CARRIER_BILLING.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: + $ref: "#/components/schemas/ErrorInfo" + examples: + Generic400: + summary: Invalid Argument + value: + code: INVALID_ARGUMENT + status: 400 + message: "Invalid Argument ..." + InvalidDateRange: + summary: Inconsistent startDate and endDate values + value: + status: 400 + code: CARRIER_BILLING_REFUND.INVALID_DATE_RANGE + message: "Client specified an invalid date range" + OutOfRange: + summary: Request out of range + value: + status: 400 + code: OUT_OF_RANGE + message: "Client specified an invalid range" + TooManyMatchingRecords: + summary: 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" + RefundInvalid400: + description: |- + Invalid input. + Common INVALID_ARGUMENT scenarios usually are: + - Schema validation failed ("code": "INVALID_ARGUMENT","message": "Schema validation failed at ..."). + - Currency is unknown or not authorized ("code": "INVALID_ARGUMENT","message": "Currency is unknown or not authorized"). + - clientCorrelator still exist ("code": "INVALID_ARGUMENT","message": "clientCorrelator already exist on server"). + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + Generic400: + summary: Schema validation failed + value: + code: INVALID_ARGUMENT + status: 400 + message: "Schema validation failed at ..." + WrongCurrency: + summary: Currency is unknown or not authorized + value: + code: INVALID_ARGUMENT + status: 400 + message: "Currency is unknown or not authorized" + DuplicateClientCorrelator: + summary: clientCorrelator still exist + value: + code: INVALID_ARGUMENT + status: 400 + message: "clientCorrelator already exist on server" + Generic401: + description: Unauthorized + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + code: UNAUTHORIZED + status: 401 + message: "Authorization failed: ..." + Generic403: + description: Forbidden + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + code: FORBIDDEN + status: 403 + message: "Operation not allowed: ..." + RefundPermissionDenied403: + description: |- + Client does not have sufficient permission. + In addition to regular PERMISSION_DENIED scenario other scenarios may exist: + - Phone Number cannot be deducted from Access Token context (3-legged scenario) ("code": "CARRIER_BILLING_REFUND.INVALID_TOKEN_CONTEXT","message": "User phone number cannot be deducted from Access Token context"). + - Unauthorized refund amount requested ("code": "CARRIER_BILLING_REFUND.UNAUTHORIZED_AMOUNT","message": "Unauthorized amount requested"). + - Accumulated threshold refund amount for the user's mobile account overpassed ("code": "CARRIER_BILLING_REFUND.USER_AMOUNT_THRESHOLD_OVERPASSED","message": "Unathorized refund request. Accumulated user mobile refunds overpass account amount threshold"). + - Refund denied by business ("code": "CARRIER_BILLING_REFUND.REFUND_DENIED","message": "Payment denied by business"). + - 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"). + - Payment is not in suitable status for refund ("code": "CARRIER_BILLING_REFUND.INVALID_PAYMENT_STATUS","message": "Payment is not yet completed"). + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + Generic403: + summary: Forbidden + value: + status: 403 + code: PERMISSION_DENIED + message: "Operation not allowed: ..." + PhoneNumberCannotBeDeducted: + summary: Phone Number cannot be deducted from Access Token context (3-legged scenario) + value: + status: 403 + code: CARRIER_BILLING.INVALID_TOKEN_CONTEXT + message: "User phone number cannot be deducted from Access Token context" + UnauthorizedRefundAmount: + summary: Unauthorized refund amount requested + value: + status: 403 + code: CARRIER_BILLING_REFUND.UNAUTHORIZED_AMOUNT + message: "Unauthorized amount requested" + UserMobileAccumulatedThresholdRefundAmountOverpassed: + summary: Accumulated threshold refund amount for the user's mobile account overpassed + value: + status: 403 + code: CARRIER_BILLING_REFUND.USER_AMOUNT_THRESHOLD_OVERPASSED + message: "Unathorized refund request. Accumulated user mobile payments overpass account amount threshold" + RefundDenied: + summary: Refund denied by business + value: + status: 403 + code: CARRIER_BILLING_REFUND.REFUND_DENIED + message: "Refund denied by business" + PaymentNotEligibleForRefund: + summary: 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" + InvalidPaymentStatus: + summary: Payment is not in suitable status for refund + value: + status: 403 + code: CARRIER_BILLING_REFUND.INVALID_PAYMENT_STATUS + message: "Payment is not yet completed" + RefundReadPermissionDenied403: + description: |- + Client does not have sufficient permission. + In addition to regular PERMISSION_DENIED scenario other scenarios may exist: + - Phone Number cannot be deducted from access token context ("code": "CARRIER_BILLING_REFUND.INVALID_TOKEN_CONTEXT","message": "User phone number cannot be deducted from Access Token context"). + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + Generic403: + summary: Forbidden + value: + status: 403 + code: PERMISSION_DENIED + message: "Operation not allowed: ..." + InvalidTokenContext: + summary: Phone Number cannot be deducted from access token context + value: + status: 403 + code: CARRIER_BILLING_REFUND.INVALID_TOKEN_CONTEXT + message: "User phone number cannot be deducted from Access Token context" + Generic404: + description: Resource Not Found + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + code: NOT_FOUND + status: 404 + message: "The specified resource is not found" + Generic409: + description: Conflict + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 409 + code: ALREADY_EXISTS + message: "A specified resource duplicate entry found" + Generic500: + description: Server error + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + code: SERVER_ERROR + status: 500 + message: "Server Error" + Generic503: + description: Service unavailable + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + code: SERVICE_UNAVAILABLE + status: 503 + message: "Service unavailable" + Generic504: + description: Request timeout exceeded + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + code: REQUEST_TIMEOUT_EXCEEDED + status: 504 + message: "Request timeout exceeded" + parameters: + x-correlator: + name: x-correlator + in: header + description: Correlation id for the different services + schema: + 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 + PerPage: + name: perPage + in: query + description: Requested number of resources to be provided in response + schema: + type: integer + default: 10 + StartRefundCreationDate: + description: Initial `refundCreationDate` for running the query. 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) + in: query + name: refundCreationDate.gte + required: false + schema: + format: date-time + type: string + EndRefundCreationDate: + description: End `refundCreationDate` for running the query. 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) + in: query + name: refundCreationDate.lte + required: false + schema: + format: date-time + type: string + Order: + description: Used to return the sorted results in descending (default) or ascending order, based on `paymentCreationDate` property + in: query + name: order + required: false + schema: + default: desc + enum: + - desc + - asc + type: string + TransactionOperationStatus: + description: List of refund status to be considered for the query + in: query + name: transactionOperationStatus + required: false + schema: + type: array + items: + type: string + enum: + - processing + - denied + - succeeded +# MerchantIdentifier: +# description: Merchant identifier to filter the results +# in: query +# name: merchantIdentifier +# required: false +# schema: +# type: string + headers: + x-correlator: + description: Correlation id for the different services + schema: + type: string + 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 From 6cc4c105e99757103133e64ad93098f2ef04bfae Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Fri, 12 Apr 2024 17:23:14 +0200 Subject: [PATCH 02/24] fix_megalinter_path_param_definition_abscence_error --- .../carrier_billing_refund.yaml | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/code/API_definitions/carrier_billing_refund.yaml b/code/API_definitions/carrier_billing_refund.yaml index a72dfdf..4a3ab5e 100644 --- a/code/API_definitions/carrier_billing_refund.yaml +++ b/code/API_definitions/carrier_billing_refund.yaml @@ -77,6 +77,12 @@ paths: 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 @@ -171,6 +177,12 @@ paths: - 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" @@ -219,6 +231,12 @@ paths: 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 From ac5f082376282e352d174d54268e7484fea77ecd Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Fri, 12 Apr 2024 17:59:38 +0200 Subject: [PATCH 03/24] fix_megalinter_format_comments --- code/API_definitions/carrier_billing.yaml | 8 +- .../carrier_billing_refund.yaml | 100 +++++++++--------- 2 files changed, 54 insertions(+), 54 deletions(-) diff --git a/code/API_definitions/carrier_billing.yaml b/code/API_definitions/carrier_billing.yaml index 5e86856..691365f 100644 --- a/code/API_definitions/carrier_billing.yaml +++ b/code/API_definitions/carrier_billing.yaml @@ -673,10 +673,10 @@ components: 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" + 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 diff --git a/code/API_definitions/carrier_billing_refund.yaml b/code/API_definitions/carrier_billing_refund.yaml index 4a3ab5e..1997e21 100644 --- a/code/API_definitions/carrier_billing_refund.yaml +++ b/code/API_definitions/carrier_billing_refund.yaml @@ -38,7 +38,7 @@ info: 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) @@ -190,7 +190,7 @@ paths: - $ref: "#/components/parameters/EndRefundCreationDate" - $ref: "#/components/parameters/Order" - $ref: "#/components/parameters/TransactionOperationStatus" -# - $ref: "#/components/parameters/MerchantIdentifier" (OPEN) + #- $ref: "#/components/parameters/MerchantIdentifier" (OPEN) responses: "200": description: OK @@ -290,8 +290,8 @@ components: $ref: "#/components/schemas/AmountTransactionInput" type: type: string - description: |- - Type of refund. + description: |- + Type of refund. - `total` stands for a final refund, whose amount can be indicated by API Consumer (PENDING POINT). 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: @@ -318,8 +318,8 @@ components: example: "AK234rfweSBuWGFUEWFGWEVWRV" type: type: string - description: |- - Type of refund. + description: |- + Type of refund. - `total` stands for a final refund, whose amount can be 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: @@ -362,8 +362,8 @@ components: example: "AK234rfweSBuWGFUEWFGWEVWRV" type: type: string - description: |- - Type of refund. + description: |- + Type of refund. - `total` stands for a final refund, whose amount can be 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: @@ -462,8 +462,8 @@ components: properties: chargingInformation: $ref: "#/components/schemas/ChargingInformation" -# chargingMetaData: -# $ref: "#/components/schemas/ChargingMetaData" + #chargingMetaData: + #$ref: "#/components/schemas/ChargingMetaData" refundDetails: $ref: "#/components/schemas/RefundDetails" RefundDetails: @@ -536,39 +536,39 @@ components: 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: -# merchantName: -# type: string -# description: Indicates the merchant name. Allows aggregators/partners to specify the actual merchant name -# example: "EA Sports" -# merchantIdentifier: -# type: string -# description: Indicates the merchant identifier. Allows aggregators/partners to specify the actual merchant identifier -# example: "eas-12345" -# fee: -# type: number -# format: float -# multipleOf: 0.01 -# description: Percentage of the amount to be received by the requester -# example: 10 -# purchaseCategoryCode: -# type: string -# description: A category defining the type of service, product or media being purchased -# example: "games" -# channel: -# type: string -# description: The channel over which the requester is interacting with the merchant (e.g. WAP, Web, SMS...) -# example: "web" -# serviceId: -# type: string -# description: The identifier of the partner/merchant service being purchased -# example: "games-online" -# productId: -# type: string -# description: The product identifier to be combined with the `serviceId` to uniquely identify the product being purchased. For example if the `serviceId` relates to a VOD service, the `productId` can specify the movie rented -# example: "138235321" + #ChargingMetaData: + #type: object + #properties: + #merchantName: + #type: string + #description: Indicates the merchant name. Allows aggregators/partners to specify the actual merchant name + #example: "EA Sports" + #merchantIdentifier: + #type: string + #description: Indicates the merchant identifier. Allows aggregators/partners to specify the actual merchant identifier + #example: "eas-12345" + #fee: + #type: number + #format: float + #multipleOf: 0.01 + #description: Percentage of the amount to be received by the requester + #example: 10 + #purchaseCategoryCode: + #type: string + #description: A category defining the type of service, product or media being purchased + #example: "games" + #channel: + #type: string + #description: The channel over which the requester is interacting with the merchant (e.g. WAP, Web, SMS...) + #example: "web" + #serviceId: + #type: string + #description: The identifier of the partner/merchant service being purchased + #example: "games-online" + #productId: + #type: string + #description: The product identifier to be combined with the `serviceId` to uniquely identify the product being purchased. For example if the `serviceId` relates to a VOD service, the `productId` can specify the movie rented + #example: "138235321" CloudEvent: description: The notification format required: @@ -1049,13 +1049,13 @@ components: - processing - denied - succeeded -# MerchantIdentifier: -# description: Merchant identifier to filter the results -# in: query -# name: merchantIdentifier -# required: false -# schema: -# type: string + #MerchantIdentifier: + #description: Merchant identifier to filter the results + #in: query + #name: merchantIdentifier + #required: false + #schema: + #type: string headers: x-correlator: description: Correlation id for the different services From a9510f81ec7397656a4cdeb35983fee86b45f60c Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Fri, 12 Apr 2024 18:05:41 +0200 Subject: [PATCH 04/24] fix_megalinter_final_comments --- .../carrier_billing_refund.yaml | 51 +++---------------- 1 file changed, 8 insertions(+), 43 deletions(-) diff --git a/code/API_definitions/carrier_billing_refund.yaml b/code/API_definitions/carrier_billing_refund.yaml index 1997e21..ec66522 100644 --- a/code/API_definitions/carrier_billing_refund.yaml +++ b/code/API_definitions/carrier_billing_refund.yaml @@ -190,7 +190,7 @@ paths: - $ref: "#/components/parameters/EndRefundCreationDate" - $ref: "#/components/parameters/Order" - $ref: "#/components/parameters/TransactionOperationStatus" - #- $ref: "#/components/parameters/MerchantIdentifier" (OPEN) + - $ref: "#/components/parameters/MerchantIdentifier" responses: "200": description: OK @@ -462,8 +462,6 @@ components: properties: chargingInformation: $ref: "#/components/schemas/ChargingInformation" - #chargingMetaData: - #$ref: "#/components/schemas/ChargingMetaData" refundDetails: $ref: "#/components/schemas/RefundDetails" RefundDetails: @@ -536,39 +534,6 @@ components: 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: - #merchantName: - #type: string - #description: Indicates the merchant name. Allows aggregators/partners to specify the actual merchant name - #example: "EA Sports" - #merchantIdentifier: - #type: string - #description: Indicates the merchant identifier. Allows aggregators/partners to specify the actual merchant identifier - #example: "eas-12345" - #fee: - #type: number - #format: float - #multipleOf: 0.01 - #description: Percentage of the amount to be received by the requester - #example: 10 - #purchaseCategoryCode: - #type: string - #description: A category defining the type of service, product or media being purchased - #example: "games" - #channel: - #type: string - #description: The channel over which the requester is interacting with the merchant (e.g. WAP, Web, SMS...) - #example: "web" - #serviceId: - #type: string - #description: The identifier of the partner/merchant service being purchased - #example: "games-online" - #productId: - #type: string - #description: The product identifier to be combined with the `serviceId` to uniquely identify the product being purchased. For example if the `serviceId` relates to a VOD service, the `productId` can specify the movie rented - #example: "138235321" CloudEvent: description: The notification format required: @@ -1049,13 +1014,13 @@ components: - processing - denied - succeeded - #MerchantIdentifier: - #description: Merchant identifier to filter the results - #in: query - #name: merchantIdentifier - #required: false - #schema: - #type: string + MerchantIdentifier: + description: Merchant identifier to filter the results + in: query + name: merchantIdentifier + required: false + schema: + type: string headers: x-correlator: description: Correlation id for the different services From 7b224ea01003e4d8aac1be692f12c34add63c293 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Wed, 15 May 2024 11:59:51 +0200 Subject: [PATCH 05/24] fix_amount_and_taxAmount_non-negative --- code/API_definitions/carrier_billing.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/code/API_definitions/carrier_billing.yaml b/code/API_definitions/carrier_billing.yaml index 691365f..83f846d 100644 --- a/code/API_definitions/carrier_billing.yaml +++ b/code/API_definitions/carrier_billing.yaml @@ -928,6 +928,7 @@ components: type: number format: float multipleOf: 0.001 + minimum: 0.001 description: Specific amount to be charged or reserved referred to a specific item. example: 100 currency: @@ -946,6 +947,7 @@ components: type: number format: float multipleOf: 0.001 + minimum: 0 description: | The tax amount charged 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 @@ -960,6 +962,7 @@ components: type: number format: float multipleOf: 0.001 + minimum: 0.001 description: Amount to be charged or reserved. example: 100 currency: @@ -978,6 +981,7 @@ components: type: number format: float multipleOf: 0.001 + minimum: 0 description: | The tax amount charged 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 From d12b4cfcf29a5358c64fcad249e9617a11500d57 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Wed, 15 May 2024 12:55:47 +0200 Subject: [PATCH 06/24] status_naming_and_alignment_fix_refund_non_negative_amounts --- code/API_definitions/carrier_billing.yaml | 39 ++++++++++--------- .../carrier_billing_refund.yaml | 28 ++++++++----- 2 files changed, 40 insertions(+), 27 deletions(-) diff --git a/code/API_definitions/carrier_billing.yaml b/code/API_definitions/carrier_billing.yaml index 83f846d..bf3a85e 100644 --- a/code/API_definitions/carrier_billing.yaml +++ b/code/API_definitions/carrier_billing.yaml @@ -245,7 +245,7 @@ paths: - $ref: "#/components/parameters/StartPaymentCreationDate" - $ref: "#/components/parameters/EndPaymentCreationDate" - $ref: "#/components/parameters/Order" - - $ref: "#/components/parameters/TransactionOperationStatus" + - $ref: "#/components/parameters/PaymentStatus" - $ref: "#/components/parameters/MerchantIdentifier" responses: "200": @@ -589,6 +589,7 @@ components: required: - amountTransaction - paymentId + - paymentStatus - paymentCreationDate properties: paymentId: @@ -597,6 +598,11 @@ components: example: "AK234rfweSBuWGFUEWFGWEVWRV" amountTransaction: $ref: "#/components/schemas/AmountTransaction" + paymentStatus: + type: string + description: + Specifies the payment status (`processing`, `pending_validation`, `denied`, `reserved`, `succeeded`, `cancelled`). + example: "processing" paymentCreationDate: type: string format: date-time @@ -620,6 +626,7 @@ components: required: - amountTransaction - paymentId + - paymentStatus - paymentCreationDate properties: paymentId: @@ -628,6 +635,11 @@ components: example: "AK234rfweSBuWGFUEWFGWEVWRV" amountTransaction: $ref: "#/components/schemas/AmountTransaction" + paymentStatus: + type: string + description: + Specifies the payment status (`processing`, `pending_validation`, `denied`, `reserved`, `succeeded`, `cancelled`). + example: "processing" paymentCreationDate: type: string format: date-time @@ -693,7 +705,6 @@ components: - phoneNumber - paymentAmount - referenceCode - - transactionOperationStatus type: object properties: phoneNumber: @@ -716,11 +727,6 @@ components: Merchant generated payment reference to uniquely identify the request, for instance, in the case of disputes. Same value as the one provided in the request. example: "ref-pay-834tfr2rA3v8r8vr3rv" - transactionOperationStatus: - type: string - description: - Specifies the payment status (`processing`, `pending_validation`, `denied`, `reserved`, `succeeded`, `cancelled`, `refund_in_progress`, `totally_refunded`, `partially_refunded`). - example: "processing" resourceURL: type: string description: URI of the created resource (same as in the Location header) @@ -797,6 +803,7 @@ components: required: - amountTransaction - paymentId + - paymentStatus - paymentCreationDate type: object properties: @@ -806,6 +813,11 @@ components: example: "AK234rfweSBuWGFUEWFGWEVWRV" amountTransaction: $ref: "#/components/schemas/AmountReservationTransactionForReserve" + paymentStatus: + type: string + description: + Specifies the payment status (`processing`, `pending_validation`, `denied`, `reserved`, `succeeded`, `cancelled`). + example: "processing" paymentCreationDate: type: string format: date-time @@ -833,7 +845,6 @@ components: required: - paymentAmount - referenceCode - - transactionOperationStatus type: object properties: phoneNumber: @@ -855,11 +866,6 @@ components: Merchant generated payment reference to uniquely identify the request, for example, in the case of disputes. Same value as the one provided in the request. example: "ref-pay-834tfr2rA3v8r8vr3rv" - transactionOperationStatus: - type: string - description: - Specifies the payment status (`processing`, `pending_validation`, `denied`, `reserved`, `succeeded`, `cancelled`, `refund_in_progress`, `totally_refunded`, `partially_refunded`). - example: "processing" resourceURL: type: string description: URI of the created resource (same as in the Location header) @@ -1713,10 +1719,10 @@ components: - desc - asc type: string - TransactionOperationStatus: + PaymentStatus: description: List of payment status to be considered for the query in: query - name: transactionOperationStatus + name: paymentStatus required: false schema: type: array @@ -1729,9 +1735,6 @@ components: - reserved - succeeded - cancelled - - refund_in_progress - - totally_refunded - - partially_refunded MerchantIdentifier: description: Merchant identifier to filter the results in: query diff --git a/code/API_definitions/carrier_billing_refund.yaml b/code/API_definitions/carrier_billing_refund.yaml index ec66522..94fadc2 100644 --- a/code/API_definitions/carrier_billing_refund.yaml +++ b/code/API_definitions/carrier_billing_refund.yaml @@ -189,7 +189,7 @@ paths: - $ref: "#/components/parameters/StartRefundCreationDate" - $ref: "#/components/parameters/EndRefundCreationDate" - $ref: "#/components/parameters/Order" - - $ref: "#/components/parameters/TransactionOperationStatus" + - $ref: "#/components/parameters/RefundStatus" - $ref: "#/components/parameters/MerchantIdentifier" responses: "200": @@ -309,6 +309,7 @@ components: required: - amountTransaction - refundId + - refundStatus - refundCreationDate - type properties: @@ -316,6 +317,11 @@ components: 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: |- @@ -353,6 +359,7 @@ components: required: - amountTransaction - refundId + - refundStatus - refundCreationDate - type properties: @@ -360,6 +367,11 @@ components: 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: |- @@ -403,7 +415,6 @@ components: required: - refundAmount - referenceCode - - transactionOperationStatus type: object properties: clientCorrelator: @@ -422,11 +433,6 @@ components: Merchant generated refund reference to uniquely identify the request, for instance, in the case of disputes. Same value as the one provided in the request. example: "ref-refund-834tfr2rA3v8r8vr3rv" - transactionOperationStatus: - type: string - description: - Specifies the refund status (`processing`, `denied`, `succeeded`). - example: "processing" serverReferenceCode: type: string description: @@ -481,6 +487,7 @@ components: type: number format: float multipleOf: 0.001 + minimum: 0.001 description: Specific amount to be refunded referred to a specific item. example: 100 currency: @@ -499,6 +506,7 @@ components: 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 @@ -513,6 +521,7 @@ components: type: number format: float multipleOf: 0.001 + minimum: 0.001 description: Amount to be refunded. example: 100 currency: @@ -531,6 +540,7 @@ components: 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 @@ -1001,10 +1011,10 @@ components: - desc - asc type: string - TransactionOperationStatus: + RefundStatus: description: List of refund status to be considered for the query in: query - name: transactionOperationStatus + name: refundStatus required: false schema: type: array From 04b4cb1ff9c3476fde1f7d71a8eb24fd89f3d39e Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Wed, 15 May 2024 13:00:46 +0200 Subject: [PATCH 07/24] fix_linter_error --- code/API_definitions/carrier_billing.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/carrier_billing.yaml b/code/API_definitions/carrier_billing.yaml index bf3a85e..dcc28aa 100644 --- a/code/API_definitions/carrier_billing.yaml +++ b/code/API_definitions/carrier_billing.yaml @@ -602,7 +602,7 @@ components: type: string description: Specifies the payment status (`processing`, `pending_validation`, `denied`, `reserved`, `succeeded`, `cancelled`). - example: "processing" + example: "processing" paymentCreationDate: type: string format: date-time From bb99437f73199e8e70dd7dffd1acd838538e925a Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Fri, 24 May 2024 19:29:23 +0200 Subject: [PATCH 08/24] carrier_billing_phoneNumber_aligment --- code/API_definitions/carrier_billing.yaml | 117 +++++++++++++++++----- 1 file changed, 94 insertions(+), 23 deletions(-) diff --git a/code/API_definitions/carrier_billing.yaml b/code/API_definitions/carrier_billing.yaml index dcc28aa..0d70b12 100644 --- a/code/API_definitions/carrier_billing.yaml +++ b/code/API_definitions/carrier_billing.yaml @@ -56,13 +56,13 @@ info: **1-STEP Payment** If `createPayment` is a **SYNC** process: - - Response contains `paymentId` and status=`succeeded`. + - Response contains `paymentId` and paymentStatus=`succeeded`. - In case of any error scenario `paymentId` is not created. If `createPayment` is an **ASYNC** process: - - Response contains `paymentId` and status=`processing`. After completion: - - When payment is successfully completed then status=`succeeded`. - - When payment is not successfully performed then status=`denied`. + - Response contains `paymentId` and paymentStatus=`processing`. After completion: + - When payment is successfully completed then paymentStatus=`succeeded`. + - When payment is not successfully performed then paymentStatus=`denied`. - In case of any error scenario `paymentId` is not created. **2-STEP Payment** @@ -71,31 +71,31 @@ info: If `preparePayment` is a **SYNC** process: - **Case A** - `validationInfo` is NOT provided in response. - - Response contains `paymentId` and status=`reserved`. + - Response contains `paymentId` and paymentStatus=`reserved`. - **Case B** - `validationInfo` is provided in response. - - Response contains `paymentId` and status=`pending_validation`. + - Response contains `paymentId` and paymentStatus=`pending_validation`. - In case of any error scenario `paymentId` is not created. If `preparePayment` is an **ASYNC** process: - **Case A** - `validationInfo` is NOT provided in response. - - Response contains `paymentId` and status=`processing`. After completion: - - When payment preparation is successfully completed then status=`reserved`. - - When payment preparation is not successfully performed then status=`denied`. + - Response contains `paymentId` and paymentStatus=`processing`. After completion: + - When payment preparation is successfully completed then paymentStatus=`reserved`. + - When payment preparation is not successfully performed then paymentStatus=`denied`. - **Case B** - `validationInfo` is provided in response. - - Response contains `paymentId` and status=`processing`. After completion: - - When payment preparation is successfully completed then status=`pending_validation`. [1] - - When payment preparation is not successfully performed then status=`denied`. + - Response contains `paymentId` and paymentStatus=`processing`. After completion: + - When payment preparation is successfully completed then paymentStatus=`pending_validation`. [1] + - When payment preparation is not successfully performed then paymentStatus=`denied`. - In case of any error scenario `paymentId` is not created. [OPTIONAL] VALIDATE STEP [1] - After `validatePayment`, status=`reserved` OR `denied`, depending whether it was successful or not. + After `validatePayment`, paymentStatus=`reserved` OR `denied`, depending whether it was successful or not. SECOND STEP - After `confirmPayment`, status=`succeeded` OR `denied`, depending whether it was successful or not. + After `confirmPayment`, paymentStatus=`succeeded` OR `denied`, depending whether it was successful or not. - After `cancelPayment`, status=`cancelled`. + After `cancelPayment`, paymentStatus=`cancelled`. # Authorization and authentication @@ -552,7 +552,7 @@ paths: "401": $ref: "#/components/responses/Generic401" "403": - $ref: "#/components/responses/Generic403" + $ref: "#/components/responses/PaymentCancelPermissionDenied403" "404": $ref: "#/components/responses/Generic404" "409": @@ -709,7 +709,11 @@ components: properties: phoneNumber: type: string - description: Identifies the mobile account to be charged. Phone number in E.164 format (starting with country code). Optionally prefixed with '+'. + description: |- + Identifies the mobile account to be charged. + + A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. + pattern: '^\+[1-9][0-9]{4,14}$' example: "+34671999000" clientCorrelator: type: string @@ -745,11 +749,15 @@ components: properties: phoneNumber: type: string - description: | - Identifies the mobile account to be charged. Phone number in E.164 format (starting with country code). Optionally prefixed with '+'. + description: |- + Identifies the mobile account to be charged. + + A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. + Additional Considerations: - When phoneNumber is not indicated, it can be inferred from authorization context (i.e. token), otherwise `HTTP 403` will be answered. - When phoneNumber is indicated, authorization context will be consistent, otherwise `HTTP 403` will be answered. + pattern: '^\+[1-9][0-9]{4,14}$' example: "+34671999000" clientCorrelator: type: string @@ -783,7 +791,15 @@ components: properties: phoneNumber: type: string - description: Identifies the mobile account to be charged. Phone number in E.164 format (starting with country code). Optionally prefixed with '+'. + description: |- + Identifies the mobile account to be charged. + + A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. + + Additional Considerations: + - When phoneNumber is not indicated, it can be inferred from authorization context (i.e. token), otherwise `HTTP 403` will be answered. + - When phoneNumber is indicated, authorization context will be consistent, otherwise `HTTP 403` will be answered. + pattern: '^\+[1-9][0-9]{4,14}$' example: "+34671999000" ValidatePayment: type: object @@ -843,13 +859,18 @@ components: - description: Information to manage payment notifications AmountReservationTransactionForReserve: required: + - phoneNumber - paymentAmount - referenceCode type: object properties: phoneNumber: type: string - description: Identifies the mobile account to be charged. Phone number in E.164 format (starting with country code). Optionally prefixed with '+'. + description: |- + Identifies the mobile account to be charged. + + A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. + pattern: '^\+[1-9][0-9]{4,14}$' example: "+34671999000" clientCorrelator: type: string @@ -884,11 +905,15 @@ components: properties: phoneNumber: type: string - description: | - Identifies the mobile account to be charged. Phone number in E.164 format (starting with country code). Optionally prefixed with '+'. + description: |- + Identifies the mobile account to be charged. + + A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. + Additional Considerations: - When phoneNumber is not indicated, it can be inferred from authorization context (i.e. token), otherwise `HTTP 403` will be answered. - When phoneNumber is indicated, authorization context will be consistent, otherwise `HTTP 403` will be answered. + pattern: '^\+[1-9][0-9]{4,14}$' example: "+34671999000" clientCorrelator: type: string @@ -1498,6 +1523,8 @@ components: description: |- Client does not have sufficient permission. In addition to regular PERMISSION_DENIED scenario other scenarios may exist: + - Phone Number is required ("code": "CARRIER_BILLING.PHONE_NUMBER_REQUIRED","message": "Phone Number is required"). + - Phone Number provided not matching Access Token context ("code": "CARRIER_BILLING.INVALID_TOKEN_CONTEXT","message": "Phone Number does not match with Access Token context"). - Payment denied by business ("code": "CARRIER_BILLING.PAYMENT_DENIED","message": "Payment denied by business"). headers: x-correlator: @@ -1513,12 +1540,56 @@ components: status: 403 code: PERMISSION_DENIED message: "Operation not allowed: ..." + PhoneNumberRequired: + summary: Phone Number is required + value: + status: 403 + code: CARRIER_BILLING.PHONE_NUMBER_REQUIRED + message: "Phone Number not provided and cannot be obtained from Access Token context" + PhoneNumberMismatch: + summary: Phone Number provided not matching Access Token context + value: + status: 403 + code: CARRIER_BILLING.INVALID_TOKEN_CONTEXT + message: "Phone Number does not match with Access Token context" PaymentDenied: summary: Payment denied by business value: status: 403 code: CARRIER_BILLING.PAYMENT_DENIED message: "Payment denied by business" + PaymentCancelPermissionDenied403: + description: |- + Client does not have sufficient permission. + In addition to regular PERMISSION_DENIED scenario other scenarios may exist: + - Phone Number is required ("code": "CARRIER_BILLING.PHONE_NUMBER_REQUIRED","message": "Phone Number is required"). + - Phone Number provided not matching Access Token context ("code": "CARRIER_BILLING.INVALID_TOKEN_CONTEXT","message": "Phone Number does not match with Access Token context"). + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + Generic403: + summary: Forbidden + value: + status: 403 + code: PERMISSION_DENIED + message: "Operation not allowed: ..." + PhoneNumberRequired: + summary: Phone Number is required + value: + status: 403 + code: CARRIER_BILLING.PHONE_NUMBER_REQUIRED + message: "Phone Number not provided and cannot be obtained from Access Token context" + PhoneNumberMismatch: + summary: Phone Number provided not matching Access Token context + value: + status: 403 + code: CARRIER_BILLING.INVALID_TOKEN_CONTEXT + message: "Phone Number does not match with Access Token context" PaymentReadPermissionDenied403: description: |- Client does not have sufficient permission. From 659b2aa46ef4dd0494a8576e47952cea64761601 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Fri, 24 May 2024 20:20:34 +0200 Subject: [PATCH 09/24] adding_merchant_identifier_model_422_exceptions_and_more_description --- .../carrier_billing_refund.yaml | 51 +++++++++++++++++-- 1 file changed, 48 insertions(+), 3 deletions(-) diff --git a/code/API_definitions/carrier_billing_refund.yaml b/code/API_definitions/carrier_billing_refund.yaml index 94fadc2..837ec65 100644 --- a/code/API_definitions/carrier_billing_refund.yaml +++ b/code/API_definitions/carrier_billing_refund.yaml @@ -17,11 +17,11 @@ info: 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) to a given back to the user. + 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 ...., as well as to retrieve information about a specific refund or a list of refunds. + 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`. @@ -31,7 +31,15 @@ info: State transitions: - TBD + 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. # Authorization and authentication @@ -148,6 +156,8 @@ paths: $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/RefundPermissionDenied403" + "422": + $ref: "#/components/responses/CreateRefundUnprocessableContent422" "409": $ref: "#/components/responses/Generic409" "500": @@ -468,6 +478,8 @@ components: properties: chargingInformation: $ref: "#/components/schemas/ChargingInformation" + chargingMetaData: + $ref: "#/components/schemas/ChargingMetaData" refundDetails: $ref: "#/components/schemas/RefundDetails" RefundDetails: @@ -544,6 +556,13 @@ components: 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" CloudEvent: description: The notification format required: @@ -924,6 +943,32 @@ components: status: 409 code: ALREADY_EXISTS message: "A specified resource duplicate entry found" + CreateRefundUnprocessableContent422: + description: |- + Client indicates content that is understable by the Server but unable to be processed. + Scenarios considered: + - 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."). + - 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: + $ref: "#/components/schemas/ErrorInfo" + examples: + TaxesManagementMismatch: + summary: 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." + RefundDetailsMismatch: + summary: 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." Generic500: description: Server error headers: From 08837a86b7ab472aa9d84c7bbcab8cdff022ca5b Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Sat, 25 May 2024 00:14:09 +0200 Subject: [PATCH 10/24] polymorphic_refund_model --- .../carrier_billing_refund.yaml | 205 +++++++++--------- 1 file changed, 103 insertions(+), 102 deletions(-) diff --git a/code/API_definitions/carrier_billing_refund.yaml b/code/API_definitions/carrier_billing_refund.yaml index 837ec65..e6ffd82 100644 --- a/code/API_definitions/carrier_billing_refund.yaml +++ b/code/API_definitions/carrier_billing_refund.yaml @@ -149,13 +149,15 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/RefundCreated" + $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": @@ -292,17 +294,15 @@ components: schemas: CreateRefund: type: object + description: Information to create a Refund resource. required: - - amountTransaction - type properties: - amountTransaction: - $ref: "#/components/schemas/AmountTransactionInput" type: type: string description: |- Type of refund. - - `total` stands for a final refund, whose amount can be indicated by API Consumer (PENDING POINT). No more refunds are allowed for that `paymentId`. + - `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 @@ -314,60 +314,33 @@ components: allOf: - $ref: "#/components/schemas/Webhook" - description: Information to manage refund notifications - RefundCreated: - type: object - required: - - amountTransaction - - 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, whose amount can be 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 - amountTransaction: - $ref: "#/components/schemas/AmountTransaction" - 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 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). - 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 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). - reason: - type: string - description: Reason provided to request the refund. Optionally provided by the user or the merchant. - webhook: - allOf: - - $ref: "#/components/schemas/Webhook" - - description: Information to manage refund notifications - RefundArray: - description: A list of refund(s) - type: array - minItems: 0 - items: - $ref: "#/components/schemas/Refund" + 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: - - amountTransaction - refundId - refundStatus - refundCreationDate @@ -386,13 +359,11 @@ components: type: string description: |- Type of refund. - - `total` stands for a final refund, whose amount can be indicated by API Consumer. No more refunds are allowed for that `paymentId`. + - `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 - amountTransaction: - $ref: "#/components/schemas/AmountTransaction" refundCreationDate: type: string format: date-time @@ -408,24 +379,34 @@ components: allOf: - $ref: "#/components/schemas/Webhook" - description: Information to manage refund notifications - Webhook: + 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: - - notificationUrl - properties: - notificationUrl: - type: string - description: Callback URL to allow asynchronous delivery of refund related events - example: "https://myservice.com/refund/events" - notificationAuthToken: - type: string - description: Authentification token for callback endpoint - example: "c8974e592c2fa383d4a3960714" - AmountTransaction: required: - refundAmount - referenceCode - type: object properties: clientCorrelator: type: string @@ -433,23 +414,23 @@ components: 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 - refund twice. This field SHOULD be present. Same value as indicated in the request. + charge twice. This field SHOULD be present. example: "req-12f2pgh448gh2hvrfrv" refundAmount: - $ref: "#/components/schemas/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. Same value as the one provided in the request. + request, for instance, in the case of disputes. example: "ref-refund-834tfr2rA3v8r8vr3rv" - serverReferenceCode: - type: string - description: - Reference to the charge or refund, provided by the server, - and meaningful to the server’s backend system for the purpose of reconciliation. - example: "ref-pay-834tfr2rA3v8r8vr3rv-serv" - AmountTransactionInput: + 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 @@ -464,15 +445,16 @@ components: charge twice. This field SHOULD be present. example: "req-12f2pgh448gh2hvrfrv" refundAmount: - $ref: "#/components/schemas/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" - RefundAmount: + RefundAmountPartialRefund: type: object + description: Information for a `partial` refund. Amount to be refunded is required. required: - chargingInformation properties: @@ -482,13 +464,26 @@ components: $ref: "#/components/schemas/ChargingMetaData" refundDetails: $ref: "#/components/schemas/RefundDetails" - RefundDetails: + RefundArray: + description: A list of refund(s) type: array - description: Detailed description of the concepts/items considered within a specific refund procedure. - minItems: 1 + minItems: 0 items: - $ref: "#/components/schemas/RefundItem" - RefundItem: + $ref: "#/components/schemas/Refund" + Webhook: + type: object + required: + - notificationUrl + properties: + notificationUrl: + type: string + description: Callback URL to allow asynchronous delivery of refund related events + example: "https://myservice.com/refund/events" + notificationAuthToken: + type: string + description: Authentification token for callback endpoint + example: "c8974e592c2fa383d4a3960714" + ChargingInformation: type: object required: - amount @@ -500,7 +495,7 @@ components: format: float multipleOf: 0.001 minimum: 0.001 - description: Specific amount to be refunded referred to a specific item. + description: Amount to be refunded. example: 100 currency: type: string @@ -508,7 +503,7 @@ components: example: "EUR" description: type: string - description: Description text to be used for information and billing text referred to a specific item. + description: Description text to be used for information and billing text example: "FIFA EA Sports 24" isTaxIncluded: type: boolean @@ -522,7 +517,20 @@ components: 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 - ChargingInformation: + 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: - amount @@ -534,7 +542,7 @@ components: format: float multipleOf: 0.001 minimum: 0.001 - description: Amount to be refunded. + description: Specific amount to be refunded referred to a specific item. example: 100 currency: type: string @@ -542,7 +550,7 @@ components: example: "EUR" description: type: string - description: Description text to be used for information and billing text + description: Description text to be used for information and billing text referred to a specific item. example: "FIFA EA Sports 24" isTaxIncluded: type: boolean @@ -556,13 +564,6 @@ components: 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" CloudEvent: description: The notification format required: From efe24441d606325a7b55d1c24a464f1a54b4a209 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Sat, 25 May 2024 00:44:35 +0200 Subject: [PATCH 11/24] payment_remaining_amount_new_proposal --- code/API_definitions/carrier_billing.yaml | 35 -------- .../carrier_billing_refund.yaml | 81 +++++++++++++++++++ 2 files changed, 81 insertions(+), 35 deletions(-) diff --git a/code/API_definitions/carrier_billing.yaml b/code/API_definitions/carrier_billing.yaml index 0d70b12..a700b6e 100644 --- a/code/API_definitions/carrier_billing.yaml +++ b/code/API_definitions/carrier_billing.yaml @@ -648,10 +648,6 @@ 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" @@ -669,37 +665,6 @@ 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 diff --git a/code/API_definitions/carrier_billing_refund.yaml b/code/API_definitions/carrier_billing_refund.yaml index e6ffd82..ad3e7dc 100644 --- a/code/API_definitions/carrier_billing_refund.yaml +++ b/code/API_definitions/carrier_billing_refund.yaml @@ -282,6 +282,53 @@ paths: $ref: "#/components/responses/Generic503" "504": $ref: "#/components/responses/Generic504" + /payments/{paymentId}/refunds/remainingAmount: + 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. + + 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-Last-Key: + $ref: "#/components/headers/Content-Last-Key" + X-Total-Count: + $ref: "#/components/headers/X-Total-Count" + content: + application/json: + schema: + $ref: "#/components/schemas/PaymentRemainingAmount" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/RefundReadPermissionDenied403" + "404": + $ref: "#/components/responses/Generic404" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + "504": + $ref: "#/components/responses/Generic504" components: securitySchemes: openId: @@ -564,6 +611,40 @@ components: 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" + 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 CloudEvent: description: The notification format required: From 56569a641a39933f01b8126674e2689ccedf9d66 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Sat, 25 May 2024 00:49:40 +0200 Subject: [PATCH 12/24] fix_linter_error --- code/API_definitions/carrier_billing_refund.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/carrier_billing_refund.yaml b/code/API_definitions/carrier_billing_refund.yaml index ad3e7dc..5e35035 100644 --- a/code/API_definitions/carrier_billing_refund.yaml +++ b/code/API_definitions/carrier_billing_refund.yaml @@ -282,7 +282,7 @@ paths: $ref: "#/components/responses/Generic503" "504": $ref: "#/components/responses/Generic504" - /payments/{paymentId}/refunds/remainingAmount: + /payments/{paymentId}/refunds/remaining-amount: get: security: - openId: From 4d03b249acb8eddfb15a12681897ff5c936eb0e3 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Mon, 10 Jun 2024 20:55:57 +0200 Subject: [PATCH 13/24] align_camara_commonalities_and_notification_model --- code/API_definitions/carrier_billing.yaml | 260 ++++++++++++++---- .../carrier_billing_refund.yaml | 189 ++++++++++--- 2 files changed, 364 insertions(+), 85 deletions(-) diff --git a/code/API_definitions/carrier_billing.yaml b/code/API_definitions/carrier_billing.yaml index a700b6e..de9803b 100644 --- a/code/API_definitions/carrier_billing.yaml +++ b/code/API_definitions/carrier_billing.yaml @@ -34,7 +34,7 @@ info: - One endpoint to setup the payment reservation, named `preparePayment`. - A couple of endpoints to confirm/cancel such payment reservation, named `confirmPayment` and `cancelPayment` respectively. - A set of endpoints to retrieve information about a list of payments or a specific payment (identified by its specific `paymentId`), named `retrievePayments` and `retrievePayment` respectively. - - A callback endpoint where API Server can send notifications about a payment procedure, as defined within `createPayment` and `preparePayment` operations, towards the `webhook.notificationUrl` when provided by API client. + - A callback endpoint where API Server can send notifications about a payment procedure, as defined within `createPayment` and `preparePayment` operations, towards the `sink` when provided by API client. The usage of the API is based on Payment resource, which can be created (in 1-STEP or 2-STEP Payment process), confirmed/cancelled (for 2-STEP Payment process), and queried/retrieved (list of payments or a specific payment). @@ -43,7 +43,7 @@ info: - **1-STEP & 2-STEP Payment**: - **1-STEP Payment**: The request intent is to charge an amount to the mobile line. When the server receives the request, it will check the user account associated with this line and, if nothing prevents it, the amount is charged and will be either bill in next invoice or removed from current line credit/balance. - **2-STEP Payment**: The first call is to request a payment preparation, which implies an amount reservation. The amount is not charged and the server has to be ready to get a confirmation or a cancellation to perform the payment. Only when the confirmation is done, payment is charged. Depending on business rules of the Telco operator, a `prepared` payment could expire after a defined delay. - - **Notification URL**: Developers may provide a callback URL (`webhook.notificationUrl` param) on which status change notifications, regarding the payment, can be received from the Telco Operator. This is an optional parameter. + - **Notification URL**: Developers may provide a callback URL (`sink` param) on which status change notifications, regarding the payment, can be received from the Telco Operator. This is an optional parameter. Following diagram shows the API resources operation sequencing: ![PaymentSequence](https://raw.githubusercontent.com/camaraproject/CarrierBillingCheckOut/main/documentation/API_documentation/resources/Carrier_Billing_sequence_diagram.png) @@ -117,15 +117,13 @@ info: externalDocs: description: Product documentation at Camara url: https://github.com/camaraproject/ +x-camara-commonalities: 0.4.0 servers: - - url: "{apiRoot}/{basePath}" + - url: "{apiRoot}/carrier-billing/v0" variables: apiRoot: default: http://localhost:9091 - description: API root - basePath: - default: carrier-billing/v0 - description: Base path for the carrier billing API + description: API root, defined by the service provider tags: - name: One Step Payment description: Operations to manage One Step Payment procedure @@ -155,7 +153,7 @@ paths: required: true callbacks: notifications: - "{$request.body#/webhook/notificationUrl}": + "{$request.body#/sink}": post: security: - {} @@ -188,12 +186,14 @@ paths: $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/Generic403" + "410": + $ref: "#/components/responses/Generic410" + "429": + $ref: "#/components/responses/Generic429" "500": $ref: "#/components/responses/Generic500" "503": $ref: "#/components/responses/Generic503" - "504": - $ref: "#/components/responses/Generic504" responses: "201": description: Created @@ -337,7 +337,7 @@ paths: required: true callbacks: notifications: - "{$request.body#/webhook/notificationUrl}": + "{$request.body#/sink}": post: security: - {} @@ -370,12 +370,14 @@ paths: $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/Generic403" + "410": + $ref: "#/components/responses/Generic410" + "429": + $ref: "#/components/responses/Generic429" "500": $ref: "#/components/responses/Generic500" "503": $ref: "#/components/responses/Generic503" - "504": - $ref: "#/components/responses/Generic504" responses: "201": description: Created @@ -571,7 +573,7 @@ components: notificationsBearerAuth: type: http scheme: bearer - bearerFormat: "{$request.body#/webhook/notificationAuthToken}" + bearerFormat: "{$request.body#/sinkCredential.credentialType}" schemas: CreatePayment: type: object @@ -580,10 +582,15 @@ components: properties: amountTransaction: $ref: "#/components/schemas/AmountTransactionInput" - webhook: + sink: + type: string + format: url + description: The address to which events shall be delivered using the selected protocol. + example: "https://endpoint.example.com/sink" + sinkCredential: allOf: - - $ref: "#/components/schemas/Webhook" - - description: Information to manage payment notifications + - description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target. + - $ref: "#/components/schemas/SinkCredential" PaymentCreated: type: object required: @@ -600,8 +607,7 @@ components: $ref: "#/components/schemas/AmountTransaction" paymentStatus: type: string - description: - Specifies the payment status (`processing`, `pending_validation`, `denied`, `reserved`, `succeeded`, `cancelled`). + description: Specifies the payment status (`processing`, `pending_validation`, `denied`, `reserved`, `succeeded`, `cancelled`). example: "processing" paymentCreationDate: type: string @@ -611,10 +617,15 @@ 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). - webhook: + sink: + type: string + format: url + description: The address to which events shall be delivered using the selected protocol. + example: "https://endpoint.example.com/sink" + sinkCredential: allOf: - - $ref: "#/components/schemas/Webhook" - - description: Information to manage payment notifications + - description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target. + - $ref: "#/components/schemas/SinkCredential" PaymentArray: description: A list of payment(s) type: array @@ -637,8 +648,7 @@ components: $ref: "#/components/schemas/AmountTransaction" paymentStatus: type: string - description: - Specifies the payment status (`processing`, `pending_validation`, `denied`, `reserved`, `succeeded`, `cancelled`). + description: Specifies the payment status (`processing`, `pending_validation`, `denied`, `reserved`, `succeeded`, `cancelled`). example: "processing" paymentCreationDate: type: string @@ -648,23 +658,104 @@ 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). - webhook: + sink: + type: string + format: url + description: The address to which events shall be delivered using the selected protocol. + example: "https://endpoint.example.com/sink" + sinkCredential: allOf: - - $ref: "#/components/schemas/Webhook" - - description: Information to manage payment notifications - Webhook: + - description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target. + - $ref: "#/components/schemas/SinkCredential" + SinkCredential: type: object - required: - - notificationUrl properties: - notificationUrl: - type: string - description: Callback URL to allow asynchronous delivery of payment related events - example: "https://myservice.com/payment/events" - notificationAuthToken: + credentialType: type: string - description: Authentification token for callback endpoint - example: "c8974e592c2fa383d4a3960714" + 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 instant at which the token shall be considered expired. + 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 instant at which the token shall be considered expired. + 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 AmountTransaction: required: - phoneNumber @@ -796,8 +887,7 @@ components: $ref: "#/components/schemas/AmountReservationTransactionForReserve" paymentStatus: type: string - description: - Specifies the payment status (`processing`, `pending_validation`, `denied`, `reserved`, `succeeded`, `cancelled`). + description: Specifies the payment status (`processing`, `pending_validation`, `denied`, `reserved`, `succeeded`, `cancelled`). example: "processing" paymentCreationDate: type: string @@ -807,10 +897,15 @@ components: allOf: - $ref: "#/components/schemas/ValidationInfo" - description: Information to perform otp validation. Only needed when business case requires it. Sending of OTP is outside the scope of this specification. - webhook: + sink: + type: string + format: url + description: The address to which events shall be delivered using the selected protocol. + example: "https://endpoint.example.com/sink" + sinkCredential: allOf: - - $ref: "#/components/schemas/Webhook" - - description: Information to manage payment notifications + - description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target. + - $ref: "#/components/schemas/SinkCredential" BodyAmountReservationTransactionForReserveInput: required: - amountTransaction @@ -818,10 +913,15 @@ components: properties: amountTransaction: $ref: "#/components/schemas/AmountReservationTransactionForReserveInput" - webhook: + sink: + type: string + format: url + description: The address to which events shall be delivered using the selected protocol. + example: "https://endpoint.example.com/sink" + sinkCredential: allOf: - - $ref: "#/components/schemas/Webhook" - - description: Information to manage payment notifications + - description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target. + - $ref: "#/components/schemas/SinkCredential" AmountReservationTransactionForReserve: required: - phoneNumber @@ -1028,14 +1128,14 @@ components: discriminator: propertyName: action mapping: - open: '#/components/schemas/Open' - validate: '#/components/schemas/Validate' + open: "#/components/schemas/Open" + validate: "#/components/schemas/Validate" example: action: validate authorizationId: "Fn34o8g239v3wrb3t" Open: allOf: - - $ref: '#/components/schemas/ValidationInfo' + - $ref: "#/components/schemas/ValidationInfo" - type: object description: Information for otp validation by means of browseable URL. required: @@ -1047,7 +1147,7 @@ components: example: "https://my-payment-service.com/validate/358y24t2g4f2397g45" Validate: allOf: - - $ref: '#/components/schemas/ValidationInfo' + - $ref: "#/components/schemas/ValidationInfo" - type: object description: Information for otp validation by means of received otp. required: @@ -1295,6 +1395,8 @@ components: - Schema validation failed ("code": "INVALID_ARGUMENT","message": "Schema validation failed at ..."). - Currency is unknown or not authorized ("code": "INVALID_ARGUMENT","message": "Currency is unknown or not authorized"). - clientCorrelator still exist ("code": "INVALID_ARGUMENT","message": "clientCorrelator already exist on server"). + - Invalid sink credential ("code": "INVALID_CREDENTIAL","message": "Only Access token is supported"). + - Invalid sink credential access token ("code": "INVALID_TOKEN","message": "Only bearer token is supported"). headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -1321,6 +1423,18 @@ components: code: INVALID_ARGUMENT status: 400 message: "clientCorrelator already exist on server" + InvalidCredential: + summary: Invalid sink credential + value: + status: 400 + code: "INVALID_CREDENTIAL" + message: "Only Access token is supported" + InvalidToken: + summary: Invalid sink credential access token + value: + status: 400 + code: "INVALID_TOKEN" + message: "Only bearer token is supported" Payment2StepInvalid400: description: |- Invalid input. @@ -1328,6 +1442,8 @@ components: - Schema validation failed ("code": "INVALID_ARGUMENT","message": "Schema validation failed at ..."). - Phone Number is required ("code": "INVALID_ARGUMENT","message": "Expected property is missing: phoneNumber"). - paymentId is required ("code": "INVALID_ARGUMENT","message": "Expected property is missing: paymentId"). + - Invalid sink credential ("code": "INVALID_CREDENTIAL","message": "Only Access token is supported"). + - Invalid sink credential access token ("code": "INVALID_TOKEN","message": "Only bearer token is supported"). headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -1354,6 +1470,18 @@ components: code: INVALID_ARGUMENT status: 400 message: "Expected property is missing: paymentId" + InvalidCredential: + summary: Invalid sink credential + value: + status: 400 + code: "INVALID_CREDENTIAL" + message: "Only Access token is supported" + InvalidToken: + summary: Invalid sink credential access token + value: + status: 400 + code: "INVALID_TOKEN" + message: "Only bearer token is supported" ValidatePaymentInvalid400: description: |- Invalid input. @@ -1442,7 +1570,7 @@ components: - Payment denied by business ("code": "CARRIER_BILLING.PAYMENT_DENIED","message": "Payment denied by business"). headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -1493,7 +1621,7 @@ components: - Payment denied by business ("code": "CARRIER_BILLING.PAYMENT_DENIED","message": "Payment denied by business"). headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -1531,7 +1659,7 @@ components: - Phone Number provided not matching Access Token context ("code": "CARRIER_BILLING.INVALID_TOKEN_CONTEXT","message": "Phone Number does not match with Access Token context"). headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -1562,7 +1690,7 @@ components: - Phone Number cannot be deducted from access token context ("code": "CARRIER_BILLING.INVALID_TOKEN_CONTEXT","message": "User phone number cannot be deducted from access token context"). headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -1668,6 +1796,32 @@ components: code: CARRIER_BILLING.PAYMENT_CANCELLED status: 409 message: "Payment has been cancelled" + Generic410: + description: Gone + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + code: GONE + status: 410 + description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available + Generic429: + description: Too Many Requests + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + code: TOO_MANY_REQUESTS + status: 429 + message: Either out of resource quota or reaching rate limiting. Generic500: description: Server error headers: diff --git a/code/API_definitions/carrier_billing_refund.yaml b/code/API_definitions/carrier_billing_refund.yaml index 5e35035..c8a131c 100644 --- a/code/API_definitions/carrier_billing_refund.yaml +++ b/code/API_definitions/carrier_billing_refund.yaml @@ -26,7 +26,7 @@ info: 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 `webhook.notificationUrl` when provided by API client. + - 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. State transitions: @@ -61,15 +61,13 @@ info: externalDocs: description: Product documentation at Camara url: https://github.com/camaraproject/ +x-camara-commonalities: 0.4.0 servers: - - url: "{apiRoot}/{basePath}" + - url: "{apiRoot}/carrier-billing-refund/v0" variables: apiRoot: default: http://localhost:9091 - description: API root - basePath: - default: carrier-billing-refund/v0 - description: Base path for the carrier billing refund API + description: API root, defined by the service provider tags: - name: Refund description: Operations to manage Refund procedure @@ -101,7 +99,7 @@ paths: required: true callbacks: notifications: - "{$request.body#/webhook/notificationUrl}": + "{$request.body#/sink}": post: security: - {} @@ -134,12 +132,14 @@ paths: $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/Generic403" + "410": + $ref: "#/components/responses/Generic410" + "429": + $ref: "#/components/responses/Generic429" "500": $ref: "#/components/responses/Generic500" "503": $ref: "#/components/responses/Generic503" - "504": - $ref: "#/components/responses/Generic504" responses: "201": description: Created @@ -177,7 +177,7 @@ paths: 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 (TBD). + 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. @@ -337,7 +337,7 @@ components: notificationsBearerAuth: type: http scheme: bearer - bearerFormat: "{$request.body#/webhook/notificationAuthToken}" + bearerFormat: "{$request.body#/sinkCredential.credentialType}" schemas: CreateRefund: type: object @@ -357,10 +357,15 @@ components: reason: type: string description: Reason provided to request the refund. Optionally provided by the user or the merchant. - webhook: + sink: + type: string + format: url + description: The address to which events shall be delivered using the selected protocol. + example: "https://endpoint.example.com/sink" + sinkCredential: allOf: - - $ref: "#/components/schemas/Webhook" - - description: Information to manage refund notifications + - 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: @@ -399,8 +404,7 @@ components: example: "AK234rfweSBuWGFUEWFGWEVWRV" refundStatus: type: string - description: - Specifies the refund status (`processing`, `denied`, `succeeded`). + description: Specifies the refund status (`processing`, `denied`, `succeeded`). example: "processing" type: type: string @@ -422,10 +426,15 @@ components: reason: type: string description: Reason provided to request the refund. Optionally provided by the user or the merchant. - webhook: + sink: + type: string + format: url + description: The address to which events shall be delivered using the selected protocol. + example: "https://endpoint.example.com/sink" + sinkCredential: allOf: - - $ref: "#/components/schemas/Webhook" - - description: Information to manage refund notifications + - 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: @@ -517,19 +526,95 @@ components: minItems: 0 items: $ref: "#/components/schemas/Refund" - Webhook: + SinkCredential: type: object - required: - - notificationUrl properties: - notificationUrl: + credentialType: type: string - description: Callback URL to allow asynchronous delivery of refund related events - example: "https://myservice.com/refund/events" - notificationAuthToken: - type: string - description: Authentification token for callback endpoint - example: "c8974e592c2fa383d4a3960714" + 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 instant at which the token shall be considered expired. + 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 instant at which the token shall be considered expired. + 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: @@ -862,6 +947,8 @@ components: - Schema validation failed ("code": "INVALID_ARGUMENT","message": "Schema validation failed at ..."). - Currency is unknown or not authorized ("code": "INVALID_ARGUMENT","message": "Currency is unknown or not authorized"). - clientCorrelator still exist ("code": "INVALID_ARGUMENT","message": "clientCorrelator already exist on server"). + - Invalid sink credential ("code": "INVALID_CREDENTIAL","message": "Only Access token is supported"). + - Invalid sink credential access token ("code": "INVALID_TOKEN","message": "Only bearer token is supported"). headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -888,6 +975,18 @@ components: code: INVALID_ARGUMENT status: 400 message: "clientCorrelator already exist on server" + InvalidCredential: + summary: Invalid sink credential + value: + status: 400 + code: "INVALID_CREDENTIAL" + message: "Only Access token is supported" + InvalidToken: + summary: Invalid sink credential access token + value: + status: 400 + code: "INVALID_TOKEN" + message: "Only bearer token is supported" Generic401: description: Unauthorized headers: @@ -926,7 +1025,7 @@ components: - Payment is not in suitable status for refund ("code": "CARRIER_BILLING_REFUND.INVALID_PAYMENT_STATUS","message": "Payment is not yet completed"). headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -981,7 +1080,7 @@ components: - Phone Number cannot be deducted from access token context ("code": "CARRIER_BILLING_REFUND.INVALID_TOKEN_CONTEXT","message": "User phone number cannot be deducted from Access Token context"). headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -1033,7 +1132,7 @@ components: - 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' + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -1051,6 +1150,32 @@ components: status: 422 code: CARRIER_BILLING_REFUND.REFUND_DETAILS_MISMATCH message: "Inconsistent refundDetails information with regards to related payment." + Generic410: + description: Gone + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + code: GONE + status: 410 + description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available + Generic429: + description: Too Many Requests + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + code: TOO_MANY_REQUESTS + status: 429 + message: Either out of resource quota or reaching rate limiting. Generic500: description: Server error headers: From 960f3b1387da2f2bb74113ac3fcb1480a96036ee Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Mon, 10 Jun 2024 21:01:01 +0200 Subject: [PATCH 14/24] fix_linter_10_june --- code/API_definitions/carrier_billing.yaml | 2 +- code/API_definitions/carrier_billing_refund.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/carrier_billing.yaml b/code/API_definitions/carrier_billing.yaml index de9803b..4671975 100644 --- a/code/API_definitions/carrier_billing.yaml +++ b/code/API_definitions/carrier_billing.yaml @@ -1808,7 +1808,7 @@ components: example: code: GONE status: 410 - description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available + message: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available Generic429: description: Too Many Requests headers: diff --git a/code/API_definitions/carrier_billing_refund.yaml b/code/API_definitions/carrier_billing_refund.yaml index c8a131c..5af00a7 100644 --- a/code/API_definitions/carrier_billing_refund.yaml +++ b/code/API_definitions/carrier_billing_refund.yaml @@ -1162,7 +1162,7 @@ components: example: code: GONE status: 410 - description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available + message: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available Generic429: description: Too Many Requests headers: From 9c723cd6c8f37cbf5ff6dac146d2343b6dffc5e4 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Tue, 11 Jun 2024 13:01:49 +0200 Subject: [PATCH 15/24] include_paymentItemId_concept --- code/API_definitions/carrier_billing.yaml | 6 ++++++ code/API_definitions/carrier_billing_refund.yaml | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/code/API_definitions/carrier_billing.yaml b/code/API_definitions/carrier_billing.yaml index 4671975..2008795 100644 --- a/code/API_definitions/carrier_billing.yaml +++ b/code/API_definitions/carrier_billing.yaml @@ -1016,10 +1016,16 @@ components: PaymentItem: type: object required: + - id - amount - currency - description properties: + id: + type: string + description: |- + Unique payment item identifier. Relevant to uniquely identify an item within a given payment when `paymentDetails` are provided and also to correlate information when a refund regarding this item is performed, by means of using `refundDetails`. + example: "3goug3uvu32v3b" amount: type: number format: float diff --git a/code/API_definitions/carrier_billing_refund.yaml b/code/API_definitions/carrier_billing_refund.yaml index 5af00a7..ebcd6fc 100644 --- a/code/API_definitions/carrier_billing_refund.yaml +++ b/code/API_definitions/carrier_billing_refund.yaml @@ -665,10 +665,16 @@ components: 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 From 692c175329b0e5617e4bbdab0a2c798ff83213c5 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Tue, 11 Jun 2024 13:25:47 +0200 Subject: [PATCH 16/24] fix_linter_comment --- code/API_definitions/carrier_billing.yaml | 2 +- code/API_definitions/carrier_billing_refund.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/carrier_billing.yaml b/code/API_definitions/carrier_billing.yaml index 2008795..a1ed250 100644 --- a/code/API_definitions/carrier_billing.yaml +++ b/code/API_definitions/carrier_billing.yaml @@ -1023,7 +1023,7 @@ components: properties: id: type: string - description: |- + description: |- Unique payment item identifier. Relevant to uniquely identify an item within a given payment when `paymentDetails` are provided and also to correlate information when a refund regarding this item is performed, by means of using `refundDetails`. example: "3goug3uvu32v3b" amount: diff --git a/code/API_definitions/carrier_billing_refund.yaml b/code/API_definitions/carrier_billing_refund.yaml index ebcd6fc..789ad4b 100644 --- a/code/API_definitions/carrier_billing_refund.yaml +++ b/code/API_definitions/carrier_billing_refund.yaml @@ -672,7 +672,7 @@ components: properties: paymentItemId: type: string - description: |- + 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: From e07bed4e516ef9cd9f1fa61e3f5b99ff1b6ddd0b Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Tue, 11 Jun 2024 20:33:43 +0200 Subject: [PATCH 17/24] fix_typo --- code/API_definitions/carrier_billing_refund.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/carrier_billing_refund.yaml b/code/API_definitions/carrier_billing_refund.yaml index 789ad4b..4074f18 100644 --- a/code/API_definitions/carrier_billing_refund.yaml +++ b/code/API_definitions/carrier_billing_refund.yaml @@ -1026,7 +1026,7 @@ components: - Phone Number cannot be deducted from Access Token context (3-legged scenario) ("code": "CARRIER_BILLING_REFUND.INVALID_TOKEN_CONTEXT","message": "User phone number cannot be deducted from Access Token context"). - Unauthorized refund amount requested ("code": "CARRIER_BILLING_REFUND.UNAUTHORIZED_AMOUNT","message": "Unauthorized amount requested"). - Accumulated threshold refund amount for the user's mobile account overpassed ("code": "CARRIER_BILLING_REFUND.USER_AMOUNT_THRESHOLD_OVERPASSED","message": "Unathorized refund request. Accumulated user mobile refunds overpass account amount threshold"). - - Refund denied by business ("code": "CARRIER_BILLING_REFUND.REFUND_DENIED","message": "Payment denied by business"). + - Refund denied by business ("code": "CARRIER_BILLING_REFUND.REFUND_DENIED","message": "Refund denied by business"). - 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"). - Payment is not in suitable status for refund ("code": "CARRIER_BILLING_REFUND.INVALID_PAYMENT_STATUS","message": "Payment is not yet completed"). headers: From e2be5764777e87a7ab10771617424fcd3b7db7a9 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Wed, 12 Jun 2024 13:20:43 +0200 Subject: [PATCH 18/24] fix_error_typos_in_payment --- code/API_definitions/carrier_billing.yaml | 41 +++++++++++++++++++++-- 1 file changed, 39 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/carrier_billing.yaml b/code/API_definitions/carrier_billing.yaml index a1ed250..0530359 100644 --- a/code/API_definitions/carrier_billing.yaml +++ b/code/API_definitions/carrier_billing.yaml @@ -389,7 +389,7 @@ paths: schema: $ref: "#/components/schemas/BodyAmountReservationTransactionForReserve" "400": - $ref: "#/components/responses/PaymentInvalid400" + $ref: "#/components/responses/Payment2StepPrepareInvalid400" "401": $ref: "#/components/responses/Generic401" "403": @@ -1401,6 +1401,8 @@ components: - Schema validation failed ("code": "INVALID_ARGUMENT","message": "Schema validation failed at ..."). - Currency is unknown or not authorized ("code": "INVALID_ARGUMENT","message": "Currency is unknown or not authorized"). - clientCorrelator still exist ("code": "INVALID_ARGUMENT","message": "clientCorrelator already exist on server"). + + In addition to regular INVALID_ARGUMENT scenario other scenarios may exist: - Invalid sink credential ("code": "INVALID_CREDENTIAL","message": "Only Access token is supported"). - Invalid sink credential access token ("code": "INVALID_TOKEN","message": "Only bearer token is supported"). headers: @@ -1441,13 +1443,15 @@ components: status: 400 code: "INVALID_TOKEN" message: "Only bearer token is supported" - Payment2StepInvalid400: + Payment2StepPrepareInvalid400: description: |- Invalid input. Common INVALID_ARGUMENT scenarios usually are: - Schema validation failed ("code": "INVALID_ARGUMENT","message": "Schema validation failed at ..."). - Phone Number is required ("code": "INVALID_ARGUMENT","message": "Expected property is missing: phoneNumber"). - paymentId is required ("code": "INVALID_ARGUMENT","message": "Expected property is missing: paymentId"). + + In addition to regular INVALID_ARGUMENT scenario other scenarios may exist: - Invalid sink credential ("code": "INVALID_CREDENTIAL","message": "Only Access token is supported"). - Invalid sink credential access token ("code": "INVALID_TOKEN","message": "Only bearer token is supported"). headers: @@ -1488,6 +1492,39 @@ components: status: 400 code: "INVALID_TOKEN" message: "Only bearer token is supported" + Payment2StepInvalid400: + description: |- + Invalid input. + Common INVALID_ARGUMENT scenarios usually are: + - Schema validation failed ("code": "INVALID_ARGUMENT","message": "Schema validation failed at ..."). + - Phone Number is required ("code": "INVALID_ARGUMENT","message": "Expected property is missing: phoneNumber"). + - paymentId is required ("code": "INVALID_ARGUMENT","message": "Expected property is missing: paymentId"). + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + Generic400: + summary: Schema validation failed + value: + code: INVALID_ARGUMENT + status: 400 + message: "Schema validation failed at ..." + phoneNumberRequired: + summary: Phone Number is required + value: + code: INVALID_ARGUMENT + status: 400 + message: "Expected property is missing: phoneNumber" + paymentIdRequired: + summary: paymentId is required + value: + code: INVALID_ARGUMENT + status: 400 + message: "Expected property is missing: paymentId" ValidatePaymentInvalid400: description: |- Invalid input. From 8d079e383cdeec649e63cdc07b2c646099a81ae1 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Wed, 12 Jun 2024 13:22:45 +0200 Subject: [PATCH 19/24] fix_error_typos_in_payment_refund --- code/API_definitions/carrier_billing_refund.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/code/API_definitions/carrier_billing_refund.yaml b/code/API_definitions/carrier_billing_refund.yaml index 4074f18..5e38f2e 100644 --- a/code/API_definitions/carrier_billing_refund.yaml +++ b/code/API_definitions/carrier_billing_refund.yaml @@ -953,6 +953,8 @@ components: - Schema validation failed ("code": "INVALID_ARGUMENT","message": "Schema validation failed at ..."). - Currency is unknown or not authorized ("code": "INVALID_ARGUMENT","message": "Currency is unknown or not authorized"). - clientCorrelator still exist ("code": "INVALID_ARGUMENT","message": "clientCorrelator already exist on server"). + + In addition to regular INVALID_ARGUMENT scenario other scenarios may exist: - Invalid sink credential ("code": "INVALID_CREDENTIAL","message": "Only Access token is supported"). - Invalid sink credential access token ("code": "INVALID_TOKEN","message": "Only bearer token is supported"). headers: From a647deaa050492aae4a662710decddbb0a764023 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Wed, 12 Jun 2024 13:34:50 +0200 Subject: [PATCH 20/24] missing_404_code_in_retrieveRefunds --- code/API_definitions/carrier_billing_refund.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/code/API_definitions/carrier_billing_refund.yaml b/code/API_definitions/carrier_billing_refund.yaml index 5e38f2e..66647f6 100644 --- a/code/API_definitions/carrier_billing_refund.yaml +++ b/code/API_definitions/carrier_billing_refund.yaml @@ -223,6 +223,8 @@ paths: $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/RefundReadPermissionDenied403" + "404": + $ref: "#/components/responses/Generic404" "500": $ref: "#/components/responses/Generic500" "503": From 85a008a0a6c619a6521dd2a759ae4c161fbffcfc Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Wed, 19 Jun 2024 12:34:39 +0200 Subject: [PATCH 21/24] description_enhancements_based_on_Ludovic_14_JUN_review --- code/API_definitions/carrier_billing.yaml | 6 ++++-- code/API_definitions/carrier_billing_refund.yaml | 8 +++++--- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/code/API_definitions/carrier_billing.yaml b/code/API_definitions/carrier_billing.yaml index 0530359..d971ab0 100644 --- a/code/API_definitions/carrier_billing.yaml +++ b/code/API_definitions/carrier_billing.yaml @@ -1,7 +1,7 @@ openapi: 3.0.3 info: description: |- - Service Enabling Payments against OB Carrier Billing Systems + Service Enabling Payments against Operator Carrier Billing Systems # Introduction @@ -99,7 +99,9 @@ info: # 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. + [Camara Security and Interoperability Profile](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md) provides details on how a client requests an access token. + + 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. diff --git a/code/API_definitions/carrier_billing_refund.yaml b/code/API_definitions/carrier_billing_refund.yaml index 66647f6..a4cae99 100644 --- a/code/API_definitions/carrier_billing_refund.yaml +++ b/code/API_definitions/carrier_billing_refund.yaml @@ -1,7 +1,7 @@ openapi: 3.0.3 info: description: |- - Service Enabling Refunds against OB Carrier Billing Systems + Service Enabling Refunds against Operator Carrier Billing Systems # Introduction @@ -27,7 +27,7 @@ info: - 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: @@ -43,7 +43,9 @@ info: # 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. + [Camara Security and Interoperability Profile](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md) provides details on how a client requests an access token. + + 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. From 9377d6cacf22c5e182ce9508f89c80bc8d777f34 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Wed, 19 Jun 2024 17:22:04 +0200 Subject: [PATCH 22/24] semantic_enhancements_based_on_Ludovic_14_JUN_review --- .../carrier_billing_refund.yaml | 28 +++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/carrier_billing_refund.yaml b/code/API_definitions/carrier_billing_refund.yaml index a4cae99..992e63b 100644 --- a/code/API_definitions/carrier_billing_refund.yaml +++ b/code/API_definitions/carrier_billing_refund.yaml @@ -39,7 +39,7 @@ info: - 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. + - 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. # Authorization and authentication @@ -296,7 +296,31 @@ paths: summary: Get remaining amount not refunded for a given payment operationId: retrievePaymentRemainingAmount description: |- - Retrieve remaining amount not yet refunded for a given payment. + 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: From 8c230ba20700a15605abd94f748fcebc6ea658f2 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Fri, 21 Jun 2024 13:24:47 +0200 Subject: [PATCH 23/24] commonalities_alignment_errors_and_endpoint_versions --- code/API_definitions/carrier_billing.yaml | 113 +++++++++++------- .../carrier_billing_refund.yaml | 52 ++++---- 2 files changed, 95 insertions(+), 70 deletions(-) diff --git a/code/API_definitions/carrier_billing.yaml b/code/API_definitions/carrier_billing.yaml index d971ab0..e0f2d3a 100644 --- a/code/API_definitions/carrier_billing.yaml +++ b/code/API_definitions/carrier_billing.yaml @@ -121,7 +121,7 @@ externalDocs: url: https://github.com/camaraproject/ x-camara-commonalities: 0.4.0 servers: - - url: "{apiRoot}/carrier-billing/v0" + - url: "{apiRoot}/carrier-billing/v0.3" variables: apiRoot: default: http://localhost:9091 @@ -214,6 +214,8 @@ paths: $ref: "#/components/responses/PaymentPermissionDenied403" "409": $ref: "#/components/responses/Generic409" + "422": + $ref: "#/components/responses/PaymentUnprocessable422" "500": $ref: "#/components/responses/Generic500" "503": @@ -409,6 +411,8 @@ paths: code: ALREADY_EXISTS status: 409 message: "Another session is created for the same UE" + "422": + $ref: "#/components/responses/PaymentUnprocessable422" "500": $ref: "#/components/responses/Generic500" "503": @@ -514,6 +518,8 @@ paths: $ref: "#/components/responses/Generic404" "409": $ref: "#/components/responses/PaymentConfirmConflict409" + "422": + $ref: "#/components/responses/PaymentSecondStepUnprocessable422" "500": $ref: "#/components/responses/Generic500" "503": @@ -561,6 +567,8 @@ paths: $ref: "#/components/responses/Generic404" "409": $ref: "#/components/responses/PaymentCancelConflict409" + "422": + $ref: "#/components/responses/PaymentSecondStepUnprocessable422" "500": $ref: "#/components/responses/Generic500" "503": @@ -1608,10 +1616,7 @@ components: description: |- Client does not have sufficient permission. In addition to regular PERMISSION_DENIED scenario other scenarios may exist: - - Phone Number is required ("code": "CARRIER_BILLING.PHONE_NUMBER_REQUIRED","message": "Phone Number is required"). - - Phone Number provided not matching Access Token context ("code": "CARRIER_BILLING.INVALID_TOKEN_CONTEXT","message": "Phone Number does not match with Access Token context"). - - Unauthorized amount requested ("code": "CARRIER_BILLING.UNAUTHORIZED_AMOUNT","message": "Unauthorized amount requested"). - - Accumulated threshold amount for the user's mobile account overpassed ("code": "CARRIER_BILLING.USER_AMOUNT_THRESHOLD_OVERPASSED","message": "Unathorized payment request. Accumulated user mobile payments overpass account amount threshold"). + - Phone Number provided not matching Access Token context ("code": "INVALID_TOKEN_CONTEXT","message": "Phone Number does not match with Access Token context"). - Payment denied by business ("code": "CARRIER_BILLING.PAYMENT_DENIED","message": "Payment denied by business"). headers: x-correlator: @@ -1627,30 +1632,12 @@ components: status: 403 code: PERMISSION_DENIED message: "Operation not allowed: ..." - PhoneNumberRequired: - summary: Phone Number is required - value: - status: 403 - code: CARRIER_BILLING.PHONE_NUMBER_REQUIRED - message: "Phone Number not provided and cannot be obtained from Access Token context" PhoneNumberMismatch: summary: Phone Number provided not matching Access Token context value: status: 403 - code: CARRIER_BILLING.INVALID_TOKEN_CONTEXT + code: INVALID_TOKEN_CONTEXT message: "Phone Number does not match with Access Token context" - UnauthorizedAmount: - summary: Unauthorized amount requested - value: - status: 403 - code: CARRIER_BILLING.UNAUTHORIZED_AMOUNT - message: "Unauthorized amount requested" - UserMobileAccumulatedThresholdAmountOverpassed: - summary: Accumulated threshold amount for the user's mobile account overpassed - value: - status: 403 - code: CARRIER_BILLING.USER_AMOUNT_THRESHOLD_OVERPASSED - message: "Unathorized payment request. Accumulated user mobile payments overpass account amount threshold" PaymentDenied: summary: Payment denied by business value: @@ -1661,8 +1648,7 @@ components: description: |- Client does not have sufficient permission. In addition to regular PERMISSION_DENIED scenario other scenarios may exist: - - Phone Number is required ("code": "CARRIER_BILLING.PHONE_NUMBER_REQUIRED","message": "Phone Number is required"). - - Phone Number provided not matching Access Token context ("code": "CARRIER_BILLING.INVALID_TOKEN_CONTEXT","message": "Phone Number does not match with Access Token context"). + - Phone Number provided not matching Access Token context ("code": "INVALID_TOKEN_CONTEXT","message": "Phone Number does not match with Access Token context"). - Payment denied by business ("code": "CARRIER_BILLING.PAYMENT_DENIED","message": "Payment denied by business"). headers: x-correlator: @@ -1678,17 +1664,11 @@ components: status: 403 code: PERMISSION_DENIED message: "Operation not allowed: ..." - PhoneNumberRequired: - summary: Phone Number is required - value: - status: 403 - code: CARRIER_BILLING.PHONE_NUMBER_REQUIRED - message: "Phone Number not provided and cannot be obtained from Access Token context" PhoneNumberMismatch: summary: Phone Number provided not matching Access Token context value: status: 403 - code: CARRIER_BILLING.INVALID_TOKEN_CONTEXT + code: INVALID_TOKEN_CONTEXT message: "Phone Number does not match with Access Token context" PaymentDenied: summary: Payment denied by business @@ -1700,8 +1680,7 @@ components: description: |- Client does not have sufficient permission. In addition to regular PERMISSION_DENIED scenario other scenarios may exist: - - Phone Number is required ("code": "CARRIER_BILLING.PHONE_NUMBER_REQUIRED","message": "Phone Number is required"). - - Phone Number provided not matching Access Token context ("code": "CARRIER_BILLING.INVALID_TOKEN_CONTEXT","message": "Phone Number does not match with Access Token context"). + - Phone Number provided not matching Access Token context ("code": "INVALID_TOKEN_CONTEXT","message": "Phone Number does not match with Access Token context"). headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -1716,23 +1695,17 @@ components: status: 403 code: PERMISSION_DENIED message: "Operation not allowed: ..." - PhoneNumberRequired: - summary: Phone Number is required - value: - status: 403 - code: CARRIER_BILLING.PHONE_NUMBER_REQUIRED - message: "Phone Number not provided and cannot be obtained from Access Token context" PhoneNumberMismatch: summary: Phone Number provided not matching Access Token context value: status: 403 - code: CARRIER_BILLING.INVALID_TOKEN_CONTEXT + code: INVALID_TOKEN_CONTEXT message: "Phone Number does not match with Access Token context" PaymentReadPermissionDenied403: description: |- Client does not have sufficient permission. In addition to regular PERMISSION_DENIED scenario other scenarios may exist: - - Phone Number cannot be deducted from access token context ("code": "CARRIER_BILLING.INVALID_TOKEN_CONTEXT","message": "User phone number cannot be deducted from access token context"). + - Phone Number cannot be deducted from access token context ("code": "INVALID_TOKEN_CONTEXT","message": "User phone number cannot be deducted from access token context"). headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -1751,7 +1724,7 @@ components: summary: Phone Number cannot be deducted from access token context value: status: 403 - code: CARRIER_BILLING.INVALID_TOKEN_CONTEXT + code: INVALID_TOKEN_CONTEXT message: "User phone number cannot be deducted from access token context" Generic404: description: Resource Not Found @@ -1854,6 +1827,58 @@ components: code: GONE status: 410 message: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available + PaymentUnprocessable422: + description: |- + Client indicates content that is understable by the Server but unable to be processed. + Scenarios that may exist: + - Phone Number is required ("code": "CARRIER_BILLING.PHONE_NUMBER_REQUIRED","message": "Phone Number is required"). + - Unauthorized amount requested ("code": "CARRIER_BILLING.UNAUTHORIZED_AMOUNT","message": "Unauthorized amount requested"). + - Accumulated threshold amount for the user's mobile account overpassed ("code": "CARRIER_BILLING.USER_AMOUNT_THRESHOLD_OVERPASSED","message": "Unathorized payment request. Accumulated user mobile payments overpass account amount threshold"). + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + PhoneNumberRequired: + summary: Phone Number is required + value: + status: 422 + code: CARRIER_BILLING.PHONE_NUMBER_REQUIRED + message: "Phone Number not provided and cannot be obtained from Access Token context" + UnauthorizedAmount: + summary: Unauthorized amount requested + value: + status: 422 + code: CARRIER_BILLING.UNAUTHORIZED_AMOUNT + message: "Unauthorized amount requested" + UserMobileAccumulatedThresholdAmountOverpassed: + summary: Accumulated threshold amount for the user's mobile account overpassed + value: + status: 422 + code: CARRIER_BILLING.USER_AMOUNT_THRESHOLD_OVERPASSED + message: "Unathorized payment request. Accumulated user mobile payments overpass account amount threshold" + PaymentSecondStepUnprocessable422: + description: |- + Client indicates content that is understable by the Server but unable to be processed. + Scenarios that may exist: + - Phone Number is required ("code": "CARRIER_BILLING.PHONE_NUMBER_REQUIRED","message": "Phone Number is required"). + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + PhoneNumberRequired: + summary: Phone Number is required + value: + status: 422 + code: CARRIER_BILLING.PHONE_NUMBER_REQUIRED + message: "Phone Number not provided and cannot be obtained from Access Token context" Generic429: description: Too Many Requests headers: diff --git a/code/API_definitions/carrier_billing_refund.yaml b/code/API_definitions/carrier_billing_refund.yaml index 992e63b..d898a4e 100644 --- a/code/API_definitions/carrier_billing_refund.yaml +++ b/code/API_definitions/carrier_billing_refund.yaml @@ -65,7 +65,7 @@ externalDocs: url: https://github.com/camaraproject/ x-camara-commonalities: 0.4.0 servers: - - url: "{apiRoot}/carrier-billing-refund/v0" + - url: "{apiRoot}/carrier-billing-refund/v0.1" variables: apiRoot: default: http://localhost:9091 @@ -1053,12 +1053,9 @@ components: description: |- Client does not have sufficient permission. In addition to regular PERMISSION_DENIED scenario other scenarios may exist: - - Phone Number cannot be deducted from Access Token context (3-legged scenario) ("code": "CARRIER_BILLING_REFUND.INVALID_TOKEN_CONTEXT","message": "User phone number cannot be deducted from Access Token context"). - - Unauthorized refund amount requested ("code": "CARRIER_BILLING_REFUND.UNAUTHORIZED_AMOUNT","message": "Unauthorized amount requested"). - - Accumulated threshold refund amount for the user's mobile account overpassed ("code": "CARRIER_BILLING_REFUND.USER_AMOUNT_THRESHOLD_OVERPASSED","message": "Unathorized refund request. Accumulated user mobile refunds overpass account amount threshold"). + - Phone Number cannot be deducted from Access Token context (3-legged scenario) ("code": "INVALID_TOKEN_CONTEXT","message": "User phone number cannot be deducted from Access Token context"). - Refund denied by business ("code": "CARRIER_BILLING_REFUND.REFUND_DENIED","message": "Refund denied by business"). - 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"). - - Payment is not in suitable status for refund ("code": "CARRIER_BILLING_REFUND.INVALID_PAYMENT_STATUS","message": "Payment is not yet completed"). headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -1077,20 +1074,8 @@ components: summary: Phone Number cannot be deducted from Access Token context (3-legged scenario) value: status: 403 - code: CARRIER_BILLING.INVALID_TOKEN_CONTEXT + code: INVALID_TOKEN_CONTEXT message: "User phone number cannot be deducted from Access Token context" - UnauthorizedRefundAmount: - summary: Unauthorized refund amount requested - value: - status: 403 - code: CARRIER_BILLING_REFUND.UNAUTHORIZED_AMOUNT - message: "Unauthorized amount requested" - UserMobileAccumulatedThresholdRefundAmountOverpassed: - summary: Accumulated threshold refund amount for the user's mobile account overpassed - value: - status: 403 - code: CARRIER_BILLING_REFUND.USER_AMOUNT_THRESHOLD_OVERPASSED - message: "Unathorized refund request. Accumulated user mobile payments overpass account amount threshold" RefundDenied: summary: Refund denied by business value: @@ -1103,17 +1088,11 @@ components: status: 403 code: CARRIER_BILLING_REFUND.PAYMENT_NOT_ELIGIBLE_FOR_REFUND message: "Payment not eligible for refund" - InvalidPaymentStatus: - summary: Payment is not in suitable status for refund - value: - status: 403 - code: CARRIER_BILLING_REFUND.INVALID_PAYMENT_STATUS - message: "Payment is not yet completed" RefundReadPermissionDenied403: description: |- Client does not have sufficient permission. In addition to regular PERMISSION_DENIED scenario other scenarios may exist: - - Phone Number cannot be deducted from access token context ("code": "CARRIER_BILLING_REFUND.INVALID_TOKEN_CONTEXT","message": "User phone number cannot be deducted from Access Token context"). + - Phone Number cannot be deducted from access token context ("code": "INVALID_TOKEN_CONTEXT","message": "User phone number cannot be deducted from Access Token context"). headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -1132,7 +1111,7 @@ components: summary: Phone Number cannot be deducted from access token context value: status: 403 - code: CARRIER_BILLING_REFUND.INVALID_TOKEN_CONTEXT + code: INVALID_TOKEN_CONTEXT message: "User phone number cannot be deducted from Access Token context" Generic404: description: Resource Not Found @@ -1164,6 +1143,9 @@ components: description: |- Client indicates content that is understable by the Server but unable to be processed. Scenarios considered: + - Unauthorized refund amount requested ("code": "CARRIER_BILLING_REFUND.UNAUTHORIZED_AMOUNT","message": "Unauthorized amount requested"). + - Accumulated threshold refund amount for the user's mobile account overpassed ("code": "CARRIER_BILLING_REFUND.USER_AMOUNT_THRESHOLD_OVERPASSED","message": "Unathorized refund request. Accumulated user mobile refunds overpass account amount threshold"). + - Payment is not in suitable status for refund ("code": "CARRIER_BILLING_REFUND.INVALID_PAYMENT_STATUS","message": "Payment is not yet completed"). - 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."). - 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: @@ -1174,6 +1156,24 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" examples: + UnauthorizedRefundAmount: + summary: Unauthorized refund amount requested + value: + status: 422 + code: CARRIER_BILLING_REFUND.UNAUTHORIZED_AMOUNT + message: "Unauthorized amount requested" + UserMobileAccumulatedThresholdRefundAmountOverpassed: + summary: Accumulated threshold refund amount for the user's mobile account overpassed + value: + status: 422 + code: CARRIER_BILLING_REFUND.USER_AMOUNT_THRESHOLD_OVERPASSED + message: "Unathorized refund request. Accumulated user mobile payments overpass account amount threshold" + InvalidPaymentStatus: + summary: Payment is not in suitable status for refund + value: + status: 422 + code: CARRIER_BILLING_REFUND.INVALID_PAYMENT_STATUS + message: "Payment is not yet completed" TaxesManagementMismatch: summary: Property `isTaxIncluded` has not the same value as related Payment value: From 8cfe775ce8e556e15094eb8fe0d92c9e1932d7f4 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Thu, 27 Jun 2024 16:24:08 +0200 Subject: [PATCH 24/24] fix_refundDate_typo --- code/API_definitions/carrier_billing_refund.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/carrier_billing_refund.yaml b/code/API_definitions/carrier_billing_refund.yaml index d898a4e..3cfb562 100644 --- a/code/API_definitions/carrier_billing_refund.yaml +++ b/code/API_definitions/carrier_billing_refund.yaml @@ -857,7 +857,7 @@ components: required: - refundDate properties: - paymentDate: + refundDate: type: string description: Date when the refund 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). format: date-time