From 61c870be119d92b58f64dc20867948086b2b1cee Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Wed, 1 Nov 2023 09:13:05 +0100 Subject: [PATCH 01/10] alignment_commonalities_PR57 --- code/API_definitions/carrier_billing.yaml | 57 ++++++++--------------- 1 file changed, 20 insertions(+), 37 deletions(-) diff --git a/code/API_definitions/carrier_billing.yaml b/code/API_definitions/carrier_billing.yaml index 1041971..7998f0d 100644 --- a/code/API_definitions/carrier_billing.yaml +++ b/code/API_definitions/carrier_billing.yaml @@ -69,9 +69,8 @@ paths: /payments: post: security: - - oAuth2ClientCredentials: [] - - three_legged: - - carrier-billing-payments-create + - openId: + - carrier-billing-payments:create tags: - One Step Payment summary: Create a new Payment @@ -180,9 +179,8 @@ paths: $ref: "#/components/responses/Generic504" get: security: - - oAuth2ClientCredentials: [] - - three_legged: - - carrier-billing-payments-read + - openId: + - carrier-billing-payments:read tags: - Payment summary: Get a list of payments @@ -255,9 +253,8 @@ paths: /payments/{paymentId}: get: security: - - oAuth2ClientCredentials: [] - - three_legged: - - carrier-billing-payments-read + - openId: + - carrier-billing-payments:read tags: - Payment summary: Get payment details @@ -296,9 +293,8 @@ paths: /payments/prepare: post: security: - - oAuth2ClientCredentials: [] - - three_legged: - - carrier-billing-payments-prepare + - openId: + - carrier-billing-payments:create tags: - Two Step Payment summary: Prepare (reserve) a payment @@ -419,9 +415,8 @@ paths: /payments/{paymentId}/confirm: post: security: - - oAuth2ClientCredentials: [] - - three_legged: - - carrier-billing-payments-confirm + - openId: + - carrier-billing-payments:write tags: - Two Step Payment summary: Confirm a payment @@ -479,6 +474,8 @@ paths: $ref: "#/components/responses/Generic401" 403: $ref: "#/components/responses/Generic403" + 404: + $ref: "#/components/responses/Generic404" 409: description: Conflict headers: @@ -516,9 +513,8 @@ paths: /payments/{paymentId}/cancel: post: security: - - oAuth2ClientCredentials: [] - - three_legged: - - carrier-billing-payments-cancel + - openId: + - carrier-billing-payments:write tags: - Two Step Payment summary: Cancel a payment @@ -577,6 +573,8 @@ paths: $ref: "#/components/responses/Generic401" 403: $ref: "#/components/responses/Generic403" + 404: + $ref: "#/components/responses/Generic404" 409: description: Conflict headers: @@ -648,6 +646,10 @@ paths: "504": $ref: "#/components/responses/Generic504" components: + securitySchemes: + openId: + type: openIdConnect + openIdConnectUrl: https://example.com/.well-known/openid-configuration schemas: CreatePayment: type: object @@ -1262,22 +1264,3 @@ components: description: Total number of items matching criteria schema: type: integer - securitySchemes: - oAuth2ClientCredentials: - type: oauth2 - flows: - clientCredentials: - tokenUrl: "{tokenUrl}" - scopes: {} - three_legged: - type: oauth2 - flows: - authorizationCode: - authorizationUrl: https://auth.example.com/authorize - tokenUrl: https://auth.example.com/token - scopes: - carrier-billing-payments-create: perform payment (1-step) - carrier-billing-payments-prepare: reserve a payment (2-step) - carrier-billing-payments-confirm: confirm a payment (2-step) - carrier-billing-payments-cancel: cancel a payment (2-step) - carrier-billing-payments-read: retrieve payment(s) information From 6b275b65a3804d9a8ab8bf48b028485c65b737e8 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Thu, 2 Nov 2023 20:32:16 +0100 Subject: [PATCH 02/10] chore: managing_3_decimal_digits_Issue_105 --- code/API_definitions/carrier_billing.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/code/API_definitions/carrier_billing.yaml b/code/API_definitions/carrier_billing.yaml index 7998f0d..b34bb39 100644 --- a/code/API_definitions/carrier_billing.yaml +++ b/code/API_definitions/carrier_billing.yaml @@ -921,7 +921,7 @@ components: amount: type: number format: float - multipleOf: 0.01 + multipleOf: 0.001 description: Specific amount to be charged or reserved referred to a specific item. currency: type: string @@ -936,7 +936,7 @@ components: taxAmount: type: number format: float - multipleOf: 0.01 + multipleOf: 0.001 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. ChargingInformation: @@ -949,7 +949,7 @@ components: amount: type: number format: float - multipleOf: 0.01 + multipleOf: 0.001 description: Amount to be charged or reserved. currency: type: string @@ -964,7 +964,7 @@ components: taxAmount: type: number format: float - multipleOf: 0.01 + multipleOf: 0.001 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. ChargingMetaData: From 2886e8e8781382febec4992d652e6917802ae772 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Thu, 2 Nov 2023 22:32:29 +0100 Subject: [PATCH 03/10] align_commonalities_cloud_event_format_Issue_112 --- code/API_definitions/carrier_billing.yaml | 274 ++++++++++++++++------ 1 file changed, 207 insertions(+), 67 deletions(-) diff --git a/code/API_definitions/carrier_billing.yaml b/code/API_definitions/carrier_billing.yaml index b34bb39..31e3a1a 100644 --- a/code/API_definitions/carrier_billing.yaml +++ b/code/API_definitions/carrier_billing.yaml @@ -86,9 +86,46 @@ paths: $ref: "#/components/schemas/CreatePayment" required: true callbacks: - eventNotifications: - "{$request.body#/webhook.notificationUrl}/eventNotifications": - $ref: "#/paths/~1eventNotifications" + notifications: + "{$request.body#/webhook/notificationUrl}": + post: + security: + - {} + - notificationsBearerAuth: [] + tags: + - Payment Notifications + summary: Carrier Billing payment notifications + operationId: paymentNotification + 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 payment notification + content: + application/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 @@ -310,9 +347,46 @@ paths: $ref: "#/components/schemas/BodyAmountReservationTransactionForReserveInput" required: true callbacks: - eventNotifications: - "{$request.body#/webhook.notificationUrl}/eventNotifications": - $ref: "#/paths/~1eventNotifications" + notifications: + "{$request.body#/webhook/notificationUrl}": + post: + security: + - {} + - notificationsBearerAuth: [] + tags: + - Payment Notifications + summary: Carrier Billing payment notifications + operationId: paymentNotification + 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 payment notification + content: + application/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 @@ -625,7 +699,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/EventNotification" + $ref: "#/components/schemas/CloudEvent" required: true responses: "204": @@ -650,6 +724,10 @@ components: openId: type: openIdConnect openIdConnectUrl: https://example.com/.well-known/openid-configuration + notificationsBearerAuth: + type: http + scheme: bearer + bearerFormat: "{$request.body#/webhook/notificationAuthToken}" schemas: CreatePayment: type: object @@ -685,6 +763,12 @@ components: description: Backend generated URL to trigger otp validation. Only needed when business case requires it. Sending of OTP is outside the scope of this specification. webhook: $ref: "#/components/schemas/Webhook" + PaymentArray: + description: A list of payment(s) + type: array + minItems: 0 + items: + $ref: "#/components/schemas/Payment" Payment: type: object required: @@ -993,91 +1077,147 @@ components: 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 - ErrorInfo: - type: object + CloudEvent: + description: The notification format required: - - code - - message - - status + - id + - source + - specversion + - type + - time properties: - code: + id: type: string - description: Code given to this error - status: + description: Identifier of this event, that must be unique in the source context. + example: sd5e-uy52-88t4-za66 + source: + $ref: "#/components/schemas/Source" + type: type: string - description: HTTP response status code - message: + description: Type of event as defined in each CAMARA API + example: org.camaraproject.carrier-billing.v0.payment-reserved + specversion: type: string - description: Detailed error description - EventNotification: - type: object - description: Generic CAMARA data type for event notification structure - required: - - event - properties: - eventSubscriptionId: + description: Version of the specification to which this event conforms (must be 1.0 if it conforms to cloudevents 1.0.2 version) + example: 1.0 + datacontenttype: type: string - description: subscription identifier - event: - $ref: "#/components/schemas/Event" - Event: + 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.v0.payment-reserved: "#/components/schemas/EventPaymentReserved" + org.camaraproject.carrier-billing.v0.payment-completed: "#/components/schemas/EventPaymentCompleted" + org.camaraproject.carrier-billing.v0.payment-cancelled: "#/components/schemas/EventPaymentCancelled" + Source: + type: string + format: uri-reference + minLength: 1 + description: Identifies the context in which an event happened in the specific Provider Implementation. + example: + - https://github.com/cloudevents + - mailto:cncf-wg-serverless@lists.cncf.io + - urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 + - cloudevents/spec/pull/123 + - /sensors/tn-1234567/alerts + - 1-555-123-4567 + DateTime: + type: string + format: date-time + description: Timestamp when the occurrence happened. Must adhere to RFC 3339. + example: "2023-11-03T12:27:10Z" + EventPaymentReserved: + description: Event structure for payment reserved + allOf: + - $ref: "#/components/schemas/CloudEvent" + - type: object + properties: + data: + $ref: "#/components/schemas/PaymentReserved" + EventPaymentCompleted: + description: Event structure for payment completed + allOf: + - $ref: "#/components/schemas/CloudEvent" + - type: object + properties: + data: + $ref: "#/components/schemas/PaymentCompleted" + EventPaymentCancelled: + description: Event structure for payment cancelled + allOf: + - $ref: "#/components/schemas/CloudEvent" + - type: object + properties: + data: + $ref: "#/components/schemas/PaymentCancelled" + PaymentReserved: + allOf: + - description: Event detail structure for org.camaraproject.carrier-billing.v0.payment-reserved event + - $ref: "#/components/schemas/BasicEvent" + PaymentCompleted: + allOf: + - description: Event detail structure for org.camaraproject.carrier-billing.v0.payment-completed event + - $ref: "#/components/schemas/BasicEvent" + - type: object + required: + - paymentDate + properties: + paymentDate: + type: string + description: Date when the payment is effectively performed, both in 1-step and 2-step scenarios. 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" + PaymentCancelled: + allOf: + - description: Event detail structure for org.camaraproject.carrier-billing.v0.payment-cancelled event + - $ref: "#/components/schemas/BasicEvent" + BasicEvent: type: object - description: Generic CAMARA data type for event structure + description: Data type to provide basic payment event information required: - - eventType - - eventTime - - eventDetail - properties: - eventId: - type: string - format: uuid - description: Identifier of the event from the server where the event was reported - eventType: - type: string - description: | - Type of event. Different types considered so far: - - `PAYMENT_COMPLETED`: Notification indication about payment completion, both in 1-step and 2-step scenarios. - - `PAYMENT_RESERVED`: Notification about payment reservation, in 2-step scenario. - - `PAYMENT_CANCELLED`: Notification about payment cancellation, in 2-step scenario. - eventTime: - type: string - format: date-time - description: Date time, in ISO-8601 extended local date format, when the event occurred. Time-offset from UTC may be used to match local OB time. - eventDetail: - $ref: "#/components/schemas/EventDetail" - EventDetail: - type: object - description: Data type to provide event detail information + - paymentId + - status + - description properties: paymentId: type: string description: Unique Identifier of the payment + example: "238r62efh289gt4g2794tg" status: type: string enum: - succeeded - failed description: | - Status of the procedure, according to `eventType` param. Possible status are: + Status of the 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. - paymentDate: - type: string - description: Date when the payment is effectively performed, both in 1-step and 2-step scenarios. This is a business information. - format: date-time + example: "Payment Notification" + ErrorInfo: + type: object required: - - paymentId + - code + - message - status - - description - PaymentArray: - description: A list of payment(s) - type: array - minItems: 0 - items: - $ref: "#/components/schemas/Payment" + properties: + code: + type: string + description: Code given to this error + status: + type: string + description: HTTP response status code + message: + type: string + description: Detailed error description responses: Generic400: description: Invalid input From d5e42cd9e71b1f062d7928f32c4c157af15b2a53 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Fri, 3 Nov 2023 08:25:32 +0100 Subject: [PATCH 04/10] remove_old_notifications_endpoint_and_related_tag_Issue_112 --- code/API_definitions/carrier_billing.yaml | 38 ----------------------- 1 file changed, 38 deletions(-) diff --git a/code/API_definitions/carrier_billing.yaml b/code/API_definitions/carrier_billing.yaml index 31e3a1a..eb38ec5 100644 --- a/code/API_definitions/carrier_billing.yaml +++ b/code/API_definitions/carrier_billing.yaml @@ -63,8 +63,6 @@ tags: description: Operations to manage Two Step Payment procedure - name: Payment description: Operations to obtain information about payments - - name: Payment Notifications - description: Operations to handle payment notifications paths: /payments: post: @@ -683,42 +681,6 @@ paths: $ref: "#/components/responses/Generic503" 504: $ref: "#/components/responses/Generic504" - /eventNotifications: - post: - tags: - - Payment Notifications - summary: Carrier Billing payment notifications - operationId: paymentNotification - description: | - Important: this endpoint is to be 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 payment notification - content: - application/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" components: securitySchemes: openId: From 2a5abd85e09735b213ba03ecb3d164c23831e895 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Fri, 3 Nov 2023 12:08:53 +0100 Subject: [PATCH 05/10] Addressing_Issue_97_part_I --- code/API_definitions/carrier_billing.yaml | 215 +++++++++------------- 1 file changed, 83 insertions(+), 132 deletions(-) diff --git a/code/API_definitions/carrier_billing.yaml b/code/API_definitions/carrier_billing.yaml index eb38ec5..83f6dbf 100644 --- a/code/API_definitions/carrier_billing.yaml +++ b/code/API_definitions/carrier_billing.yaml @@ -135,75 +135,11 @@ paths: schema: $ref: "#/components/schemas/PaymentCreated" 400: - description: Invalid input - 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" + $ref: "#/components/responses/PaymentInvalid400" 401: $ref: "#/components/responses/Generic401" 403: - description: Forbidden - 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 not provided and cannot be obtained from Authorization context - value: - status: 403 - code: CARRIER_BILLING.PHONE_NUMBER_REQUIRED - message: "Phone Number is required" - PhoneNumberMismatch: - summary: Phone Number provided not matching Authorization context - value: - status: 403 - code: CARRIER_BILLING.INVALID_TOKEN_CONTEXT - message: "Phone Number does not match with Authorization 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" + $ref: "#/components/responses/PaymentPermissionDenied403" 409: $ref: "#/components/responses/Generic409" 500: @@ -396,75 +332,11 @@ paths: schema: $ref: "#/components/schemas/BodyAmountReservationTransactionForReserve" 400: - description: Invalid input - 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" + $ref: "#/components/responses/PaymentInvalid400" 401: $ref: "#/components/responses/Generic401" 403: - description: Forbidden - 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 not provided and cannot be obtained from Authorization context - value: - status: 403 - code: CARRIER_BILLING.PHONE_NUMBER_REQUIRED - message: "Phone Number is required" - PhoneNumberMismatch: - summary: Phone Number provided not matching Authorization context - value: - status: 403 - code: CARRIER_BILLING.INVALID_TOKEN_CONTEXT - message: "Phone Number does not match with Authorization 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" + $ref: "#/components/responses/PaymentPermissionDenied403" 409: description: Conflict headers: @@ -1194,6 +1066,39 @@ components: code: INVALID_ARGUMENT status: 400 message: "Schema validation failed at ..." + PaymentInvalid400: + 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: @@ -1220,6 +1125,52 @@ components: code: FORBIDDEN status: 403 message: "Operation not allowed: ..." + PaymentPermissionDenied403: + 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"). + 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" + 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" Generic404: description: Resource Not Found headers: From 3234da4195f016ba6c1f0c1bf9f966b3edf4e0c2 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Fri, 3 Nov 2023 18:07:44 +0100 Subject: [PATCH 06/10] addressing_Issue_97_Part_II --- code/API_definitions/carrier_billing.yaml | 260 +++++++++++----------- 1 file changed, 131 insertions(+), 129 deletions(-) diff --git a/code/API_definitions/carrier_billing.yaml b/code/API_definitions/carrier_billing.yaml index 83f6dbf..a1eb4d6 100644 --- a/code/API_definitions/carrier_billing.yaml +++ b/code/API_definitions/carrier_billing.yaml @@ -190,27 +190,7 @@ paths: schema: $ref: "#/components/schemas/PaymentArray" 400: - description: Invalid input - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - examples: - InvalidDateRange: - summary: Inconsistent startDate and endDate values - value: - status: 400 - code: CARRIER_BILLING.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" + $ref: "#/components/responses/GetPaymentsInvalid400" 401: $ref: "#/components/responses/Generic401" 403: @@ -387,33 +367,7 @@ paths: x-correlator: $ref: "#/components/headers/x-correlator" 400: - description: Invalid input - 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" + $ref: "#/components/responses/Payment2StepInvalid400" 401: $ref: "#/components/responses/Generic401" 403: @@ -421,33 +375,7 @@ paths: 404: $ref: "#/components/responses/Generic404" 409: - description: Conflict - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - examples: - Generic409: - summary: Conflict - value: - code: ALREADY_EXISTS - status: 409 - message: "Payment confirmation in progress" - AlreadyConfirmed: - summary: paymentId is already confirmed - value: - code: CARRIER_BILLING.PAYMENT_CONFIRMED - status: 409 - message: "Payment has been confirmed" - AlreadyCancelled: - summary: paymentId is already cancelled - value: - code: CARRIER_BILLING.PAYMENT_CANCELLED - status: 409 - message: "Payment has been cancelled" + $ref: "#/components/responses/PaymentConfirmConflict409" 500: $ref: "#/components/responses/Generic500" 503: @@ -486,33 +414,7 @@ paths: x-correlator: $ref: "#/components/headers/x-correlator" 400: - description: Invalid input - 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" + $ref: "#/components/responses/Payment2StepInvalid400" 401: $ref: "#/components/responses/Generic401" 403: @@ -520,33 +422,7 @@ paths: 404: $ref: "#/components/responses/Generic404" 409: - description: Conflict - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - examples: - Generic409: - summary: Conflict - value: - code: ALREADY_EXISTS - status: 409 - message: "Payment cancellation in progress" - AlreadyConfirmed: - summary: paymentId is already confirmed - value: - code: CARRIER_BILLING.PAYMENT_CONFIRMED - status: 409 - message: "Payment has been confirmed" - AlreadyCancelled: - summary: paymentId is already cancelled - value: - code: CARRIER_BILLING.PAYMENT_CANCELLED - status: 409 - message: "Payment has been cancelled" + $ref: "#/components/responses/PaymentCancelConflict409" 500: $ref: "#/components/responses/Generic500" 503: @@ -1066,6 +942,37 @@ components: code: INVALID_ARGUMENT status: 400 message: "Schema validation failed at ..." + GetPaymentsInvalid400: + 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"). + 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.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" PaymentInvalid400: description: |- Invalid input. @@ -1099,6 +1006,39 @@ components: code: INVALID_ARGUMENT status: 400 message: "clientCorrelator already exist on server" + 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" Generic401: description: Unauthorized headers: @@ -1197,6 +1137,68 @@ components: status: 409 code: ALREADY_EXISTS message: "A specified resource duplicate entry found" + PaymentConfirmConflict409: + description: |- + Conflict. In addition of regular ALREADY_EXISTS scenario other scenarios may exist: + - paymentId is already confirmed ("code": "CARRIER_BILLING.PAYMENT_CONFIRMED","message": "Payment has been confirmed"). + - paymentId is already cancelled ("code": "CARRIER_BILLING.PAYMENT_CANCELLED","message": "Payment has been cancelled"). + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + Generic409: + summary: Conflict + value: + code: ALREADY_EXISTS + status: 409 + message: "Payment confirmation in progress" + AlreadyConfirmed: + summary: paymentId is already confirmed + value: + code: CARRIER_BILLING.PAYMENT_CONFIRMED + status: 409 + message: "Payment has been confirmed" + AlreadyCancelled: + summary: paymentId is already cancelled + value: + code: CARRIER_BILLING.PAYMENT_CANCELLED + status: 409 + message: "Payment has been cancelled" + PaymentCancelConflict409: + description: |- + Conflict. In addition of regular ALREADY_EXISTS scenario other scenarios may exist: + - paymentId is already confirmed ("code": "CARRIER_BILLING.PAYMENT_CONFIRMED","message": "Payment has been confirmed"). + - paymentId is already cancelled ("code": "CARRIER_BILLING.PAYMENT_CANCELLED","message": "Payment has been cancelled"). + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + Generic409: + summary: Conflict + value: + code: ALREADY_EXISTS + status: 409 + message: "Payment cancellation in progress" + AlreadyConfirmed: + summary: paymentId is already confirmed + value: + code: CARRIER_BILLING.PAYMENT_CONFIRMED + status: 409 + message: "Payment has been confirmed" + AlreadyCancelled: + summary: paymentId is already cancelled + value: + code: CARRIER_BILLING.PAYMENT_CANCELLED + status: 409 + message: "Payment has been cancelled" Generic500: description: Server error headers: From fadc94763d2c9dd82cbd402a1b3ca4488d9f416e Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Tue, 7 Nov 2023 22:25:42 +0100 Subject: [PATCH 07/10] addressing_issue_106 --- code/API_definitions/carrier_billing.yaml | 70 +++++++++++++++++++---- 1 file changed, 59 insertions(+), 11 deletions(-) diff --git a/code/API_definitions/carrier_billing.yaml b/code/API_definitions/carrier_billing.yaml index a1eb4d6..8ebc354 100644 --- a/code/API_definitions/carrier_billing.yaml +++ b/code/API_definitions/carrier_billing.yaml @@ -1,37 +1,85 @@ openapi: 3.0.3 info: - description: | + description: |- Service Enabling Payments against OB Carrier Billing Systems # Introduction - The Carrier Billing API is used by an application to charge an amount on a mobile line. The API provides management of a payment entity and its associated lifecycle. + The Carrier Billing API provides programmable interface for developers and other users (capabilities consumers) to charge an amount on a mobile line. + It can be easily integrated and allows end-users to buy digital content in an easy & secured way. The API provides management of a payment 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 OB Billing Systems, accordingly to the user's configuration in the OB. In a common usage in the industry, the payment is processed on current account balance or charged on next bill generated for the line. + 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). - **1-STEP Payment**: - Payment process performed in one phase (i.e. one action), that involves all the OB Carrier Billing Systems checking and trigger the charging request against billing systems. + Payment process performed in one phase (i.e. one action), that involves all the Telco Operator Carrier Billing Systems checking and trigger the charging request against Billing Systems. - **2-STEP Payment**: Payment process performed in two phases (i.e. two actions). First action deals with payment preparation request to guarantee the reservation of the involved amount. Second action is an explicit confirmation or cancellation of the payment by the user. Any payment not confirmed/cancelled by a given user is discarded after some time in order to avoid inconsistency in the billing systems. # API Functionality - This API allows to clients to request the payment of a (set of) good(s)/service(s), as well as to retrieve information about a specific payment or a list of payments. + 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. The API provides several endpoints/operations: - - An endpoint to request the payment in one step. - - A set of endpoints to request the payment in two steps: - - One endpoint to setup the payment reservation. - - A couple of endpoints to confirm/cancel such payment reservation. - - A set of endpoints to retrieve information about a list of payments or a specific payment, identified by its specific `paymentId`. - - An endpoint where API Server can send notifications about a payment procedure, towards the `webhook.notificationUrl` when provided by API client. + - An endpoint to request a 1-STEP Payment, named `createPayment`. + - A set of endpoints to request a 2-STEP Payment: + - 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. + + 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). + + Before starting to use the API, the developer needs to know about the below specified details: + - **Payment service endpoint**: The URL pointing to the RESTful resource of the payment API. As 1-STEP and 2-STEP processes are managed, 2 separate tags _`One Step Payment`_ and _`Two Step Payment`_ have been defined to explicitly distinguish them in the API specification. A third tag _`Payment`_ is defined for common operations in both processes (query/retrieve list of payments or a specific payment). + - **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. + + 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) + + Follow picture provides information about the payment state engine (state description & transition): + ![Payment State Engine](https://raw.githubusercontent.com/camaraproject/CarrierBillingCheckOut/main/documentation/API_documentation/resources/Carrier_Billing_State_Engine.JPG) + + State transitions: + + **1-STEP Payment** + + If `createPayment` is a **SYNC** process: + - Response contains `paymentId` and status=`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`. + + **2-STEP Payment** + + FIRST STEP + + If `preparePayment` is a **SYNC** process: + - Response contains `paymentId` and status=`reserved`. In case of any error scenario `paymentId` is not created. + + If `preparePayment` is an **ASYNC** process: + - 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`. + + SECOND STEP + + After `confirmPayment`, status=`succeeded` OR `denied`, depending whether it was successful or not. + + After `cancelPayment`, status=`cancelled`. # Further info and support From 31276a8c3c38cee2635166fd521494149c368565 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pedro=20D=C3=ADez=20Garc=C3=ADa?= Date: Wed, 8 Nov 2023 20:06:04 +0100 Subject: [PATCH 08/10] Update code/API_definitions/carrier_billing.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- 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 8ebc354..ec6ba3a 100644 --- a/code/API_definitions/carrier_billing.yaml +++ b/code/API_definitions/carrier_billing.yaml @@ -857,7 +857,7 @@ components: 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) - example: 1.0 + example: '1.0' datacontenttype: type: string description: 'media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs' From 3d30d8f8aaa238fe82cc64928244e2832ca99b24 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pedro=20D=C3=ADez=20Garc=C3=ADa?= Date: Wed, 8 Nov 2023 20:10:48 +0100 Subject: [PATCH 09/10] Update code/API_definitions/carrier_billing.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- code/API_definitions/carrier_billing.yaml | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/code/API_definitions/carrier_billing.yaml b/code/API_definitions/carrier_billing.yaml index ec6ba3a..9235cf3 100644 --- a/code/API_definitions/carrier_billing.yaml +++ b/code/API_definitions/carrier_billing.yaml @@ -878,13 +878,7 @@ components: format: uri-reference minLength: 1 description: Identifies the context in which an event happened in the specific Provider Implementation. - example: - - https://github.com/cloudevents - - mailto:cncf-wg-serverless@lists.cncf.io - - urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 - - cloudevents/spec/pull/123 - - /sensors/tn-1234567/alerts - - 1-555-123-4567 +example: https://notificationSendServer12.supertelco.com) DateTime: type: string format: date-time From 0af045ee63e8e0fc97c17ad6b40855c48f8dde21 Mon Sep 17 00:00:00 2001 From: PEDRO DIEZ GARCIA Date: Wed, 8 Nov 2023 20:31:33 +0100 Subject: [PATCH 10/10] corrections_after_1st_review --- code/API_definitions/carrier_billing.yaml | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/code/API_definitions/carrier_billing.yaml b/code/API_definitions/carrier_billing.yaml index 9235cf3..2c2146c 100644 --- a/code/API_definitions/carrier_billing.yaml +++ b/code/API_definitions/carrier_billing.yaml @@ -150,7 +150,7 @@ paths: requestBody: description: Creates a new carrier billing payment notification content: - application/json: + application/cloudevents+json: schema: $ref: "#/components/schemas/CloudEvent" required: true @@ -327,7 +327,7 @@ paths: requestBody: description: Creates a new carrier billing payment notification content: - application/json: + application/cloudevents+json: schema: $ref: "#/components/schemas/CloudEvent" required: true @@ -557,10 +557,11 @@ components: notificationUrl: type: string description: Callback URL to allow asynchronous delivery of payment related events + example: "https://myservice.com/payment/events" notificationAuthToken: type: string - example: "c8974e592c2fa383d4a3960714" description: Authentification token for callback endpoint + example: "c8974e592c2fa383d4a3960714" AmountTransaction: required: - phoneNumber @@ -847,21 +848,21 @@ components: id: type: string description: Identifier of this event, that must be unique in the source context. - example: sd5e-uy52-88t4-za66 + example: "sd5e-uy52-88t4-za66" source: $ref: "#/components/schemas/Source" type: type: string description: Type of event as defined in each CAMARA API - example: org.camaraproject.carrier-billing.v0.payment-reserved + 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) - example: '1.0' + 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 + example: "application/json" data: type: object description: Event details payload described in each CAMARA API and referenced by its type @@ -878,7 +879,7 @@ components: format: uri-reference minLength: 1 description: Identifies the context in which an event happened in the specific Provider Implementation. -example: https://notificationSendServer12.supertelco.com) + example: "https://notificationSendServer12.supertelco.com" DateTime: type: string format: date-time