diff --git a/CHANGELOG.md b/CHANGELOG.md
index 458ffec..00d3223 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,7 @@
## Table of Contents
+- [r1.2](#r12)
- [r1.1 - rc](#r11---rc)
- [v0.2.1](#v021)
- [v0.2.0](#v020)
@@ -14,6 +15,94 @@ The below sections record the changes for each API version in each release as fo
* for subsequent alpha or release-candidate API versions, the delta with respect to the previous pre-release
* for a public API version, the consolidated changes since the release of the previous public API version
+## r1.2
+
+## Release Notes
+
+This release contains the definition and documentation of
+* Carrier Billing v0.3.0
+* Carrier Billing Refund v0.1.0
+
+The API definition(s) are based on
+* Commonalities v0.4.0
+* Identity and Consent Management v0.2.0
+
+## Carrier Billing v0.3.0
+
+**Carrier Billing v0.3.0 is the first public release for v0.3.0 of the Carrier Billing (Payment) API.**
+- **This version contains significant changes compared to v0.2.1, and it is not backward compatible:**
+ - Within notifications, callback concept named as `webhook` has been replaced by the terms `sink` and `sinkCredential` in accordance with the updated CAMARA Design Guidelines (Adoption of CloudEvent Subscription Model within MetaRelease Fall24 (v0.4.0))
+ - Exceptions has also been aligned with Commonalities MetaRelease-Fall24 (v0.4.0), so as some excepctions has changed their `HTTP` and/or `status` values.
+ - Version designed to work jointly with Carrier Billing Refund API
+
+- API definition **with inline documentation**:
+ - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/CarrierBillingCheckOut/r1.2/code/API_definitions/carrier-billing.yaml&nocors)
+ - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/CarrierBillingCheckOut/r1.2/code/API_definitions/carrier-billing.yaml)
+ - OpenAPI [YAML spec file](https://github.com/camaraproject/CarrierBillingCheckOut/blob/r1.2/code/API_definitions/carrier-billing.yaml)
+
+**Main changes since [r1.1 - rc](#r11---rc)**
+
+### Added
+* Basic Test cases definition in https://github.com/camaraproject/CarrierBillingCheckOut/pull/174
+
+### Changed
+* Update User Stories in https://github.com/camaraproject/CarrierBillingCheckOut/pull/172
+* Update `README.md` with meeting info and template alignment in https://github.com/camaraproject/CarrierBillingCheckOut/pull/177
+* Update filename to kebab-case format in https://github.com/camaraproject/CarrierBillingCheckOut/pull/178
+
+### Fixed
+* Align 401 Exception Codes with CAMARA Commonalities in https://github.com/camaraproject/CarrierBillingCheckOut/pull/178
+* Align Exceptions naming model with CAMARA Commonalities in https://github.com/camaraproject/CarrierBillingCheckOut/pull/178
+* Fix `sink` property description in https://github.com/camaraproject/CarrierBillingCheckOut/pull/178
+* Adjust `version` and `servers.url` values aligned with Release Mabagement Commonalities in https://github.com/camaraproject/CarrierBillingCheckOut/pull/178
+* Fix `externalDocs.url` value in https://github.com/camaraproject/CarrierBillingCheckOut/pull/178
+* Fix missing required Request Body for `confirmPayment` operation in https://github.com/camaraproject/CarrierBillingCheckOut/pull/178
+
+### Removed
+* N/A
+
+## Carrier Billing Refund v0.1.0
+
+**Carrier Billing Refund v0.1.0 is the first public release for v0.1.0 of the Carrier Billing Refund API.**
+- **This version defines a new API:**
+ - Initial version covering the following functionality and related endpoints:
+ - New endpoint `createRefund`, both total and partial refunds
+ - New endpoint `retrieveRefunds`
+ - New endpoint `retrieveRefund`
+ - New endpoint `retrievePaymentRemainingAmount`
+ - Support for `Instance-based (implicit) subscription` notification mode
+
+- API definition **with inline documentation**:
+ - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/CarrierBillingCheckOut/r1.2/code/API_definitions/carrier-billing-refund.yaml&nocors)
+ - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/CarrierBillingCheckOut/r1.2/code/API_definitions/carrier-billing-refund.yaml)
+ - OpenAPI [YAML spec file](https://github.com/camaraproject/CarrierBillingCheckOut/blob/r1.2/code/API_definitions/carrier-billing-refund.yaml)
+
+**Main changes since [r1.1 - rc](#r11---rc)**
+
+### Added
+* Generate User Stories in https://github.com/camaraproject/CarrierBillingCheckOut/pull/172
+* Basic Test cases definition in https://github.com/camaraproject/CarrierBillingCheckOut/pull/176
+
+### Changed
+* Update `README.md` with meeting info and template alignment in https://github.com/camaraproject/CarrierBillingCheckOut/pull/177
+* Update filename to kebab-case format in https://github.com/camaraproject/CarrierBillingCheckOut/pull/178
+
+### Fixed
+* Align 401 Exception Codes with CAMARA Commonalities in https://github.com/camaraproject/CarrierBillingCheckOut/pull/178
+* Align Exceptions naming model with CAMARA Commonalities in https://github.com/camaraproject/CarrierBillingCheckOut/pull/178
+* Fix `sink` property description in https://github.com/camaraproject/CarrierBillingCheckOut/pull/178
+* Adjust `version` and `servers.url` values aligned with Release Mabagement Commonalities in https://github.com/camaraproject/CarrierBillingCheckOut/pull/178
+* Fix `externalDocs.url` value in https://github.com/camaraproject/CarrierBillingCheckOut/pull/178
+
+### Removed
+* N/A
+
+## New Contributors
+* N/A
+
+
+**Full Changelog**: https://github.com/camaraproject/CarrierBillingCheckOut/compare/v0.2.1...r1.2
+
## r1.1 - rc
## Release Notes
diff --git a/README.md b/README.md
index b92ea97..1f03bd0 100644
--- a/README.md
+++ b/README.md
@@ -24,30 +24,28 @@ Repository to describe, develop, document and test the CarrierBilling API family
-* **The Release [r1.1 - rc](https://github.com/camaraproject/CarrierBillingCheckOut/blob/main/CHANGELOG.md#r1.1---rc) for the Carrier Billing APIs Family is available.**
-
This is a release candidate. Until the public release there are bug fixes to be expected. The release candidate is suitable for implementors, but it is not recommended to use the API with customers in productive environments.
-* The release **r1.1 - rc** is available in [r1.1](https://github.com/camaraproject/CarrierBillingCheckOut/tree/r1.1), and includes the following APIs:
-- API name: Carrier Billing (Payment) - API Definition v0.3.0-rc.1 with inline documentation:
- - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/CarrierBillingCheckOut/r1.1/code/API_definitions/carrier_billing.yaml&nocors)
- - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/CarrierBillingCheckOut/r1.1/code/API_definitions/carrier_billing.yaml)
- - OpenAPI [YAML spec file](https://github.com/camaraproject/CarrierBillingCheckOut/blob/r1.1/code/API_definitions/carrier_billing.yaml)
-
-- API name: Carrier Billing Refund - API Definition v0.1.0-rc.1 with inline documentation:
- - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/CarrierBillingCheckOut/r1.1/code/API_definitions/carrier_billing_refund.yaml&nocors)
- - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/CarrierBillingCheckOut/r1.1/code/API_definitions/carrier_billing_refund.yaml)
- - OpenAPI [YAML spec file](https://github.com/camaraproject/CarrierBillingCheckOut/blob/r1.1/code/API_definitions/carrier_billing_refund.yaml)
-
-* For changes between r1.1 and v0.2.1 see the [CHANGELOG.md](https://github.com/camaraproject/CarrierBillingCheckOut/blob/main/CHANGELOG.md)
-
-* **The latest available and released version 0.2.1 is available within the [release-0.2.1 branch](https://github.com/camaraproject/CarrierBillingCheckOut/tree/release-v0.2.1)**
- - API name: Carrier Billing (Payment) - API Definition v0.2.1 with inline documentation:
- - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/CarrierBillingCheckOut/release-v0.2.1/code/API_definitions/carrier_billing.yaml&nocors)
- - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/CarrierBillingCheckOut/release-v0.2.1/code/API_definitions/carrier_billing.yaml)
- - OpenAPI [YAML spec file](https://github.com/camaraproject/CarrierBillingCheckOut/blob/release-v0.2.1/code/API_definitions/carrier_billing.yaml)
+* Note: Please be aware that the project will have updates to the main branch. There are no compatibility guarantees associated with code in any branch, including main, until a new release is created. For example, changes may be reverted before a release is created. **For best results, use the latest available release**.
+
+* **The Release [r1.2](https://github.com/camaraproject/CarrierBillingCheckOut/blob/main/CHANGELOG.md#r1.2) for the Carrier Billing APIs Family is available.**
+
This is a public release candidate.
+
+* The release **r1.2** is available in [r1.2](https://github.com/camaraproject/CarrierBillingCheckOut/tree/r1.2), and includes the following APIs:
+- API name: Carrier Billing (Payment) - API Definition v0.3.0 with inline documentation:
+ - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/CarrierBillingCheckOut/r1.2/code/API_definitions/carrier-billing.yaml&nocors)
+ - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/CarrierBillingCheckOut/r1.2/code/API_definitions/carrier-billing.yaml)
+ - OpenAPI [YAML spec file](https://github.com/camaraproject/CarrierBillingCheckOut/blob/r1.2/code/API_definitions/carrier-billing.yaml)
+
+- API name: Carrier Billing Refund - API Definition v0.1.0 with inline documentation:
+ - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/CarrierBillingCheckOut/r1.2/code/API_definitions/carrier-billing-refund.yaml&nocors)
+ - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/CarrierBillingCheckOut/r1.2/code/API_definitions/carrier-billing-refund.yaml)
+ - OpenAPI [YAML spec file](https://github.com/camaraproject/CarrierBillingCheckOut/blob/r1.2/code/API_definitions/carrier-billing-refund.yaml)
+
+* Other releases of this sub project are available in [CarrierBillingCheckout Releases](https://github.com/camaraproject/CarrierBillingCheckout/releases)
+* For changes see [CHANGELOG.md](https://github.com/camaraproject/CarrierBillingCheckout/blob/main/CHANGELOG.md)
## Contributing
* Meetings are held virtually
- * Schedule: Bi-Weekly, Wednesdays 16:00 - 17:00 CET/CEST
+ * Schedule: Bi-Weekly, Wednesdays 15:00 - 16:00 CET/CEST
* [Registration / Join](https://zoom-lfx.platform.linuxfoundation.org/meeting/96513497117?password=ac26d34b-87d2-4d78-aa47-4de1ca14c882)
* Minutes: Access [Meeting minutes](https://wiki.camaraproject.org/display/CAM/CarrierBillingCheckOut)
* Mailing List
diff --git a/code/API_definitions/carrier_billing_refund.yaml b/code/API_definitions/carrier-billing-refund.yaml
similarity index 84%
rename from code/API_definitions/carrier_billing_refund.yaml
rename to code/API_definitions/carrier-billing-refund.yaml
index 40683e2..b290712 100644
--- a/code/API_definitions/carrier_billing_refund.yaml
+++ b/code/API_definitions/carrier-billing-refund.yaml
@@ -52,17 +52,17 @@ info:
# Further info and support
(FAQs will be added in a later version of the documentation)
- version: 0.1.0-rc.1
+ version: 0.1.0
title: Carrier Billing Refunds
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/
+ url: https://github.com/camaraproject/CarrierBillingCheckOut
x-camara-commonalities: 0.4.0
servers:
- - url: "{apiRoot}/carrier-billing-refund/v0.1rc1"
+ - url: "{apiRoot}/carrier-billing-refund/v0.1"
variables:
apiRoot:
default: http://localhost:9091
@@ -385,7 +385,7 @@ components:
sink:
type: string
format: url
- description: The address to which events shall be delivered using the selected protocol.
+ description: The address to which events shall be delivered, using the HTTP protocol.
example: "https://endpoint.example.com/sink"
sinkCredential:
allOf:
@@ -454,7 +454,7 @@ components:
sink:
type: string
format: url
- description: The address to which events shall be delivered using the selected protocol.
+ description: The address to which events shall be delivered, using the HTTP protocol.
example: "https://endpoint.example.com/sink"
sinkCredential:
allOf:
@@ -929,16 +929,20 @@ components:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
- example:
- code: INVALID_ARGUMENT
- status: 400
- message: "Schema validation failed at ..."
+ examples:
+ GENERIC_400_INVALID_ARGUMENT:
+ summary: Generic Invalid Argument
+ description: Invalid Argument. Generic Syntax Exception
+ value:
+ status: 400
+ code: INVALID_ARGUMENT
+ message: Client specified an invalid argument, request body or query param.
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").
+ - 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"
@@ -947,37 +951,41 @@ components:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
- Generic400:
- summary: Invalid Argument
+ GENERIC_400_INVALID_ARGUMENT:
+ summary: Generic Invalid Argument
+ description: Invalid Argument. Generic Syntax Exception
value:
- code: INVALID_ARGUMENT
status: 400
- message: "Invalid Argument ..."
- InvalidDateRange:
- summary: Inconsistent startDate and endDate values
+ code: INVALID_ARGUMENT
+ message: Client specified an invalid argument, request body or query param.
+ GENERIC_400_INVALID_DATE_RANGE:
+ summary: Generic Invalid Date Range
+ description: Inconsistent 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
+ code: CARRIER_BILLING.INVALID_DATE_RANGE
+ message: "Client specified an invalid date range."
+ GENERIC_400_OUT_OF_RANGE:
+ summary: Generic Out Of Range
+ description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested
value:
status: 400
code: OUT_OF_RANGE
- message: "Client specified an invalid range"
- TooManyMatchingRecords:
- summary: Too many matching records found
+ message: Client specified an invalid range.
+ GENERIC_400_TOO_MANY_MATCHING_RECORDS:
+ summary: Generic Too Many Matching Records
+ description: Too many matching records found
value:
status: 400
- code: CARRIER_BILLING_REFUND.TOO_MANY_MATCHING_RECORDS
- message: "Too many matching records found. Specify additional/suitable criteria to limit the number of records"
+ code: CARRIER_BILLING.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").
+ - Schema validation failed ("code": "INVALID_ARGUMENT","message": "Client specified an invalid argument, request body or query param.").
+ - 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").
@@ -990,32 +998,37 @@ components:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
- Generic400:
- summary: Schema validation failed
+ GENERIC_400_INVALID_ARGUMENT:
+ summary: Generic Invalid Argument
+ description: Invalid Argument. Generic Syntax Exception
value:
- code: INVALID_ARGUMENT
status: 400
- message: "Schema validation failed at ..."
- WrongCurrency:
- summary: Currency is unknown or not authorized
+ code: INVALID_ARGUMENT
+ message: Client specified an invalid argument, request body or query param.
+ GENERIC_400_WRONG_CURRENCY:
+ summary: Generic Wrong Currency
+ description: Currency is unknown or not authorized
value:
code: INVALID_ARGUMENT
status: 400
- message: "Currency is unknown or not authorized"
- DuplicateClientCorrelator:
- summary: clientCorrelator still exist
+ message: "Currency is unknown or not authorized."
+ GENERIC_400_DUPLICATE_CLIENT_CORRELATOR:
+ summary: Generic Duplicate Client Correlator
+ description: clientCorrelator still exist
value:
code: INVALID_ARGUMENT
status: 400
- message: "clientCorrelator already exist on server"
- InvalidCredential:
- summary: Invalid sink credential
+ message: "clientCorrelator already exist on server."
+ GENERIC_400_INVALID_CREDENTIAL:
+ summary: Generic Invalid Credential
+ description: Invalid sink credential
value:
status: 400
code: "INVALID_CREDENTIAL"
message: "Only Access token is supported"
- InvalidToken:
- summary: Invalid sink credential access token
+ GENERIC_400_INVALID_TOKEN:
+ summary: Generic Invalid Token
+ description: Invalid sink credential access token
value:
status: 400
code: "INVALID_TOKEN"
@@ -1029,10 +1042,21 @@ components:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
- example:
- code: UNAUTHORIZED
- status: 401
- message: "Authorization failed: ..."
+ examples:
+ GENERIC_401_UNAUTHENTICATED:
+ summary: Generic Unauthenticated
+ description: Request cannot be authenticated
+ value:
+ status: 401
+ code: UNAUTHENTICATED
+ message: Request not authenticated due to missing, invalid, or expired credentials.
+ GENERIC_401_AUTHENTICATION_REQUIRED:
+ summary: Generic Authentication Required
+ description: New authentication is needed, authentication is no longer valid
+ value:
+ status: 401
+ code: AUTHENTICATION_REQUIRED
+ message: New authentication is required.
Generic403:
description: Forbidden
headers:
@@ -1042,17 +1066,20 @@ components:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
- example:
- code: FORBIDDEN
- status: 403
- message: "Operation not allowed: ..."
+ examples:
+ GENERIC_403_PERMISSION_DENIED:
+ description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
+ value:
+ status: 403
+ code: PERMISSION_DENIED
+ message: Client does not have sufficient permissions to perform this action.
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": "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").
+ - 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.").
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
@@ -1061,35 +1088,38 @@ components:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
- Generic403:
- summary: Forbidden
+ GENERIC_403_PERMISSION_DENIED:
+ description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
value:
status: 403
code: PERMISSION_DENIED
- message: "Operation not allowed: ..."
- PhoneNumberCannotBeDeducted:
- summary: Phone Number cannot be deducted from Access Token context (3-legged scenario)
+ message: Client does not have sufficient permissions to perform this action.
+ GENERIC_403_INVALID_TOKEN_CONTEXT:
+ summary: Invalid access token context
+ description: Reflects some inconsistency between information in some field of the API and the related OAuth2 Token
value:
status: 403
code: INVALID_TOKEN_CONTEXT
- message: "User phone number cannot be deducted from Access Token context"
- RefundDenied:
- summary: Refund denied by business
+ message: "User phone number cannot be deducted from Access Token context."
+ GENERIC_403_REFUND_DENIED:
+ summary: Generic Refund Denied
+ description: Refund denied by business
value:
status: 403
code: CARRIER_BILLING_REFUND.REFUND_DENIED
- message: "Refund denied by business"
- PaymentNotEligibleForRefund:
- summary: Payment not eligible for Refund (e.g. Payment conditions agreed do not allow refund)
+ message: "Refund denied by business."
+ GENERIC_403_PAYMENT_NOT_ELIGIBLE_FOR_REFUND:
+ summary: Generic Payment Not Eligible for Refund
+ description: Payment not eligible for Refund (e.g. Payment conditions agreed do not allow refund)
value:
status: 403
code: CARRIER_BILLING_REFUND.PAYMENT_NOT_ELIGIBLE_FOR_REFUND
- message: "Payment not eligible for refund"
+ message: "Payment not eligible for refund."
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": "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"
@@ -1098,18 +1128,19 @@ components:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
- Generic403:
- summary: Forbidden
+ GENERIC_403_PERMISSION_DENIED:
+ description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
value:
status: 403
code: PERMISSION_DENIED
- message: "Operation not allowed: ..."
- InvalidTokenContext:
- summary: Phone Number cannot be deducted from access token context
+ message: Client does not have sufficient permissions to perform this action.
+ GENERIC_403_INVALID_TOKEN_CONTEXT:
+ summary: Invalid access token context
+ description: Reflects some inconsistency between information in some field of the API and the related OAuth2 Token
value:
status: 403
code: INVALID_TOKEN_CONTEXT
- message: "User phone number cannot be deducted from Access Token context"
+ message: "User phone number cannot be deducted from Access Token context."
Generic404:
description: Resource Not Found
headers:
@@ -1119,10 +1150,14 @@ components:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
- example:
- code: NOT_FOUND
- status: 404
- message: "The specified resource is not found"
+ examples:
+ GENERIC_404_NOT_FOUND:
+ summary: Generic Not Found
+ description: Resource is not found
+ value:
+ status: 404
+ code: NOT_FOUND
+ message: The specified resource is not found.
Generic409:
description: Conflict
headers:
@@ -1132,17 +1167,21 @@ components:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
- example:
- status: 409
- code: ALREADY_EXISTS
- message: "A specified resource duplicate entry found"
+ examples:
+ GENERIC_409_ALREADY_EXISTS:
+ summary: Generic Already Exists
+ description: Trying to create an existing resource
+ value:
+ status: 409
+ code: ALREADY_EXISTS
+ message: The resource that a client tried to create already exists.
CreateRefundUnprocessableContent422:
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").
+ - 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:
@@ -1153,32 +1192,37 @@ components:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
- UnauthorizedRefundAmount:
- summary: Unauthorized refund amount requested
+ GENERIC_422_UNAUTHORIZED_REFUND_AMOUNT:
+ summary: Generic Unauthorized Refund Amount
+ description: Unauthorized refund amount requested
value:
status: 422
code: CARRIER_BILLING_REFUND.UNAUTHORIZED_AMOUNT
- message: "Unauthorized amount requested"
- UserMobileAccumulatedThresholdRefundAmountOverpassed:
- summary: Accumulated threshold refund amount for the user's mobile account overpassed
+ message: "Unauthorized amount requested."
+ GENERIC_422_GENERIC_422_USER_MOBILE_ACCUMULATED_THRESHOLD_REFUND_AMOUNT_OVERPASSED:
+ summary: Generic User Mobile Accumulated threshold Refund Amount Overpassed
+ description: Accumulated threshold refund amount for the user's mobile account overpassed
value:
status: 422
code: CARRIER_BILLING_REFUND.USER_AMOUNT_THRESHOLD_OVERPASSED
- message: "Unathorized refund request. Accumulated user mobile payments overpass account amount threshold"
- InvalidPaymentStatus:
- summary: Payment is not in suitable status for refund
+ message: "Unathorized refund request. Accumulated user mobile payments overpass account amount threshold."
+ GENERIC_422_INVALID_PAYMENT_STATUS:
+ summary: Generic Invalid Payment Status
+ description: Payment is not in suitable status for refund
value:
status: 422
code: CARRIER_BILLING_REFUND.INVALID_PAYMENT_STATUS
- message: "Payment is not yet completed"
- TaxesManagementMismatch:
- summary: Property `isTaxIncluded` has not the same value as related Payment
+ message: "Payment is not yet completed."
+ GENERIC_422_TAXES_MANAGEMENT_MISMATCH:
+ summary: Generic Taxes Management Mismatch
+ description: Property `isTaxIncluded` has not the same value as related Payment
value:
status: 422
code: CARRIER_BILLING_REFUND.TAXES_MANAGEMENT_MISMATCH
message: "Inconsistent isTaxIncluded value with regards to related payment."
- RefundDetailsMismatch:
- summary: Refund details provided are inconsistent with regards to the related Payment
+ GENERIC_422_REFUND_DETAILS_MISMATCH:
+ summary: Generic Refund Details Mismatch
+ description: Refund details provided are inconsistent with regards to the related Payment
value:
status: 422
code: CARRIER_BILLING_REFUND.REFUND_DETAILS_MISMATCH
@@ -1192,10 +1236,14 @@ components:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
- example:
- code: GONE
- status: 410
- message: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available
+ examples:
+ GENERIC_410_GONE:
+ summary: Generic Gone
+ description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available
+ value:
+ status: 410
+ code: GONE
+ message: Access to the target resource is no longer available.
Generic429:
description: Too Many Requests
headers:
@@ -1205,10 +1253,14 @@ components:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
- example:
- code: TOO_MANY_REQUESTS
- status: 429
- message: Either out of resource quota or reaching rate limiting.
+ examples:
+ GENERIC_429_TOO_MANY_REQUESTS:
+ summary: Generic Too Many Requests
+ description: API Server request limit is overpassed
+ value:
+ status: 429
+ code: TOO_MANY_REQUESTS
+ message: Either out of resource quota or reaching rate limiting.
Generic500:
description: Server error
headers:
@@ -1218,10 +1270,14 @@ components:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
- example:
- code: SERVER_ERROR
- status: 500
- message: "Server Error"
+ examples:
+ GENERIC_500_INTERNAL:
+ summary: Generic Server Error
+ description: Problem in Server side. Regular Server Exception
+ value:
+ status: 500
+ code: INTERNAL
+ message: Unknown server error. Typically a server bug.
Generic503:
description: Service unavailable
headers:
@@ -1231,10 +1287,14 @@ components:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
- example:
- code: SERVICE_UNAVAILABLE
- status: 503
- message: "Service unavailable"
+ examples:
+ GENERIC_503_UNAVAILABLE:
+ summary: Generic Service Unavailable
+ description: Service is not available. Temporary situation usually related to maintenance process in the server side
+ value:
+ status: 503
+ code: UNAVAILABLE
+ message: Service Unavailable.
Generic504:
description: Request timeout exceeded
headers:
@@ -1244,10 +1304,14 @@ components:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
- example:
- code: REQUEST_TIMEOUT_EXCEEDED
- status: 504
- message: "Request timeout exceeded"
+ examples:
+ GENERIC_504_TIMEOUT:
+ summary: Generic Request Timeout
+ description: API Server Timeout
+ value:
+ status: 504
+ code: TIMEOUT
+ message: Request timeout exceeded.
parameters:
x-correlator:
name: x-correlator
diff --git a/code/API_definitions/carrier_billing.yaml b/code/API_definitions/carrier-billing.yaml
similarity index 84%
rename from code/API_definitions/carrier_billing.yaml
rename to code/API_definitions/carrier-billing.yaml
index 4837fa1..df45ac2 100644
--- a/code/API_definitions/carrier_billing.yaml
+++ b/code/API_definitions/carrier-billing.yaml
@@ -108,17 +108,17 @@ info:
# Further info and support
(FAQs will be added in a later version of the documentation)
- version: 0.3.0-rc.1
+ version: 0.3.0
title: Carrier Billing
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/
+ url: https://github.com/camaraproject/CarrierBillingCheckOut
x-camara-commonalities: 0.4.0
servers:
- - url: "{apiRoot}/carrier-billing/v0.3rc1"
+ - url: "{apiRoot}/carrier-billing/v0.3"
variables:
apiRoot:
default: http://localhost:9091
@@ -499,6 +499,7 @@ paths:
application/json:
schema:
$ref: "#/components/schemas/PhoneNumber"
+ required: true
responses:
"202":
description: Payment confirmation accepted
@@ -592,7 +593,7 @@ components:
sink:
type: string
format: url
- description: The address to which events shall be delivered using the selected protocol.
+ description: The address to which events shall be delivered, using the HTTP protocol.
example: "https://endpoint.example.com/sink"
sinkCredential:
allOf:
@@ -627,7 +628,7 @@ components:
sink:
type: string
format: url
- description: The address to which events shall be delivered using the selected protocol.
+ description: The address to which events shall be delivered, using the HTTP protocol.
example: "https://endpoint.example.com/sink"
sinkCredential:
allOf:
@@ -668,7 +669,7 @@ components:
sink:
type: string
format: url
- description: The address to which events shall be delivered using the selected protocol.
+ description: The address to which events shall be delivered, using the HTTP protocol.
example: "https://endpoint.example.com/sink"
sinkCredential:
allOf:
@@ -907,7 +908,7 @@ components:
sink:
type: string
format: url
- description: The address to which events shall be delivered using the selected protocol.
+ description: The address to which events shall be delivered, using the HTTP protocol.
example: "https://endpoint.example.com/sink"
sinkCredential:
allOf:
@@ -923,7 +924,7 @@ components:
sink:
type: string
format: url
- description: The address to which events shall be delivered using the selected protocol.
+ description: The address to which events shall be delivered, using the HTTP protocol.
example: "https://endpoint.example.com/sink"
sinkCredential:
allOf:
@@ -1351,7 +1352,7 @@ components:
description: Detailed error description
responses:
Generic400:
- description: Invalid input
+ description: Bad Request
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
@@ -1359,16 +1360,20 @@ components:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
- example:
- code: INVALID_ARGUMENT
- status: 400
- message: "Schema validation failed at ..."
+ examples:
+ GENERIC_400_INVALID_ARGUMENT:
+ summary: Generic Invalid Argument
+ description: Invalid Argument. Generic Syntax Exception
+ value:
+ status: 400
+ code: INVALID_ARGUMENT
+ message: Client specified an invalid argument, request body or query param.
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").
- - 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").
+ - 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"
@@ -1377,35 +1382,39 @@ components:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
- Generic400:
- summary: Invalid Argument
+ GENERIC_400_INVALID_ARGUMENT:
+ summary: Generic Invalid Argument
+ description: Invalid Argument. Generic Syntax Exception
value:
- code: INVALID_ARGUMENT
status: 400
- message: "Invalid Argument ..."
- InvalidDateRange:
- summary: Inconsistent startDate and endDate values
+ code: INVALID_ARGUMENT
+ message: Client specified an invalid argument, request body or query param.
+ GENERIC_400_INVALID_DATE_RANGE:
+ summary: Generic Invalid Date Range
+ description: Inconsistent 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
+ message: "Client specified an invalid date range."
+ GENERIC_400_OUT_OF_RANGE:
+ summary: Generic Out Of Range
+ description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested
value:
status: 400
code: OUT_OF_RANGE
- message: "Client specified an invalid range"
- TooManyMatchingRecords:
- summary: Too many matching records found
+ message: Client specified an invalid range.
+ GENERIC_400_TOO_MANY_MATCHING_RECORDS:
+ summary: Generic Too Many Matching Records
+ description: Too many matching records found
value:
status: 400
code: CARRIER_BILLING.TOO_MANY_MATCHING_RECORDS
- message: "Too many matching records found. Specify additional/suitable criteria to limit the number of records"
+ message: "Too many matching records found. Specify additional/suitable criteria to limit the number of records."
PaymentInvalid400:
description: |-
Invalid input.
Common INVALID_ARGUMENT scenarios usually are:
- - Schema validation failed ("code": "INVALID_ARGUMENT","message": "Schema validation failed at ...").
+ - Schema validation failed ("code": "INVALID_ARGUMENT","message": "Client specified an invalid argument, request body or query param.").
- 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").
@@ -1420,32 +1429,37 @@ components:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
- Generic400:
- summary: Schema validation failed
+ GENERIC_400_INVALID_ARGUMENT:
+ summary: Generic Invalid Argument
+ description: Invalid Argument. Generic Syntax Exception
value:
- code: INVALID_ARGUMENT
status: 400
- message: "Schema validation failed at ..."
- WrongCurrency:
- summary: Currency is unknown or not authorized
+ code: INVALID_ARGUMENT
+ message: Client specified an invalid argument, request body or query param.
+ GENERIC_400_WRONG_CURRENCY:
+ summary: Generic Wrong Currency
+ description: Currency is unknown or not authorized
value:
code: INVALID_ARGUMENT
status: 400
- message: "Currency is unknown or not authorized"
- DuplicateClientCorrelator:
- summary: clientCorrelator still exist
+ message: "Currency is unknown or not authorized."
+ GENERIC_400_DUPLICATE_CLIENT_CORRELATOR:
+ summary: Generic Duplicate Client Correlator
+ description: clientCorrelator still exist
value:
code: INVALID_ARGUMENT
status: 400
- message: "clientCorrelator already exist on server"
- InvalidCredential:
- summary: Invalid sink credential
+ message: "clientCorrelator already exist on server."
+ GENERIC_400_INVALID_CREDENTIAL:
+ summary: Generic Invalid Credential
+ description: Invalid sink credential
value:
status: 400
code: "INVALID_CREDENTIAL"
message: "Only Access token is supported"
- InvalidToken:
- summary: Invalid sink credential access token
+ GENERIC_400_INVALID_TOKEN:
+ summary: Generic Invalid Token
+ description: Invalid sink credential access token
value:
status: 400
code: "INVALID_TOKEN"
@@ -1454,9 +1468,8 @@ components:
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").
+ - Schema validation failed ("code": "INVALID_ARGUMENT","message": "Client specified an invalid argument, request body or query param.").
+ - 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").
@@ -1469,32 +1482,30 @@ components:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
- Generic400:
- summary: Schema validation failed
+ GENERIC_400_INVALID_ARGUMENT:
+ summary: Generic Invalid Argument
+ description: Invalid Argument. Generic Syntax Exception
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
+ message: Client specified an invalid argument, request body or query param.
+ GENERIC_400_PAYMENT_ID_REQUIRED:
+ summary: Generic PaymentId required
+ description: paymentId is required
value:
code: INVALID_ARGUMENT
status: 400
- message: "Expected property is missing: paymentId"
- InvalidCredential:
- summary: Invalid sink credential
+ message: "Expected property is missing: paymentId."
+ GENERIC_400_INVALID_CREDENTIAL:
+ summary: Generic Invalid Credential
+ description: Invalid sink credential
value:
status: 400
code: "INVALID_CREDENTIAL"
message: "Only Access token is supported"
- InvalidToken:
- summary: Invalid sink credential access token
+ GENERIC_400_INVALID_TOKEN:
+ summary: Generic Invalid Token
+ description: Invalid sink credential access token
value:
status: 400
code: "INVALID_TOKEN"
@@ -1503,9 +1514,8 @@ components:
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").
+ - Schema validation failed ("code": "INVALID_ARGUMENT","message": "Client specified an invalid argument, request body or query param.").
+ - paymentId is required ("code": "INVALID_ARGUMENT","message": "Expected property is missing: paymentId.").
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
@@ -1514,31 +1524,27 @@ components:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
- Generic400:
- summary: Schema validation failed
+ GENERIC_400_INVALID_ARGUMENT:
+ summary: Generic Invalid Argument
+ description: Invalid Argument. Generic Syntax Exception
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
+ message: Client specified an invalid argument, request body or query param.
+ GENERIC_400_PAYMENT_ID_REQUIRED:
+ summary: Generic PaymentId required
+ description: paymentId is required
value:
code: INVALID_ARGUMENT
status: 400
- message: "Expected property is missing: paymentId"
+ message: "Expected property is missing: paymentId."
ValidatePaymentInvalid400:
description: |-
Invalid input.
In addition to regular INVALID_ARGUMENT scenario other scenarios may exist:
- - authorizationId is not valid ("code": "CARRIER_BILLING.INVALID_AUTHORIZATION_ID","message": "Invalid authorizationId").
- - code is not valid ("code": "CARRIER_BILLING.INVALID_CODE","message": "Invalid code").
- - validation failed ("code": "CARRIER_BILLING.VALIDATION_FAILED","message": "the maximum number of attempts have been consumed for this validation").
+ - authorizationId is not valid ("code": "CARRIER_BILLING.INVALID_AUTHORIZATION_ID","message": "Invalid authorizationId.").
+ - code is not valid ("code": "CARRIER_BILLING.INVALID_CODE","message": "Invalid code.").
+ - validation failed ("code": "CARRIER_BILLING.VALIDATION_FAILED","message": "the maximum number of attempts have been consumed for this validation.").
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
@@ -1547,42 +1553,48 @@ components:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
- Generic400:
- summary: Schema validation failed
+ GENERIC_400_INVALID_ARGUMENT:
+ summary: Generic Invalid Argument
+ description: Invalid Argument. Generic Syntax Exception
value:
- code: INVALID_ARGUMENT
status: 400
- message: "Schema validation failed at ..."
- AuthorizationIdRequired:
- summary: AuthorizationId is required
+ code: INVALID_ARGUMENT
+ message: Client specified an invalid argument, request body or query param.
+ GENERIC_400_AUTHORIZATION_ID_REQUIRED:
+ summary: Generic AuthorizationId Required
+ description: authorizationId is required
value:
code: INVALID_ARGUMENT
status: 400
- message: "Expected property is missing: authorizationId"
- CodeRequired:
- summary: code is required
+ message: "Expected property is missing: authorizationId."
+ GENERIC_400_CODE_REQUIRED:
+ summary: Generic Code Required
+ description: code is required
value:
code: INVALID_ARGUMENT
status: 400
- message: "Expected property is missing: code"
- InvalidAuthorizationId:
- summary: code is not valid
+ message: "Expected property is missing: code."
+ GENERIC_400_INVALID_AUTHORIZATION_ID:
+ summary: Generic Invalid Authorization Id
+ description: authorizationId is not valid
value:
code: CARRIER_BILLING.INVALID_AUTHORIZATION_ID
status: 400
- message: "Invalid authorizationId"
- InvalidCode:
- summary: code is not valid
+ message: "Invalid authorizationId."
+ GENERIC_400_INVALID_CODE:
+ summary: Generic Invalid Code
+ description: code is not valid
value:
code: CARRIER_BILLING.INVALID_CODE
status: 400
- message: "Invalid code"
- ValidationFailed:
- summary: validation failed
+ message: "Invalid code."
+ GENERIC_400_VALIDATION_FAILED:
+ summary: Generic Validation Failed
+ description: validation failed
value:
code: CARRIER_BILLING.VALIDATION_FAILED
status: 400
- message: "the maximum number of attempts have been consumed for this validation"
+ message: "the maximum number of attempts have been consumed for this validation."
Generic401:
description: Unauthorized
headers:
@@ -1592,10 +1604,21 @@ components:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
- example:
- code: UNAUTHORIZED
- status: 401
- message: "Authorization failed: ..."
+ examples:
+ GENERIC_401_UNAUTHENTICATED:
+ summary: Generic Unauthenticated
+ description: Request cannot be authenticated
+ value:
+ status: 401
+ code: UNAUTHENTICATED
+ message: Request not authenticated due to missing, invalid, or expired credentials.
+ GENERIC_401_AUTHENTICATION_REQUIRED:
+ summary: Generic Authentication Required
+ description: New authentication is needed, authentication is no longer valid
+ value:
+ status: 401
+ code: AUTHENTICATION_REQUIRED
+ message: New authentication is required.
Generic403:
description: Forbidden
headers:
@@ -1605,16 +1628,19 @@ components:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
- example:
- code: FORBIDDEN
- status: 403
- message: "Operation not allowed: ..."
+ examples:
+ GENERIC_403_PERMISSION_DENIED:
+ description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
+ value:
+ status: 403
+ code: PERMISSION_DENIED
+ message: Client does not have sufficient permissions to perform this action.
PaymentPermissionDenied403:
description: |-
Client does not have sufficient permission.
In addition to regular PERMISSION_DENIED scenario other scenarios may exist:
- - 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").
+ - Phone Number provided not matching Access Token context ("code": "INVALID_TOKEN_CONTEXT","message": "Phone Number is not consistent with access token.").
+ - Payment denied by business ("code": "CARRIER_BILLING.PAYMENT_DENIED","message": "Payment denied by business.").
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
@@ -1623,30 +1649,32 @@ components:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
- Generic403:
- summary: Forbidden
+ GENERIC_403_PERMISSION_DENIED:
+ description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
value:
status: 403
code: PERMISSION_DENIED
- message: "Operation not allowed: ..."
- PhoneNumberMismatch:
- summary: Phone Number provided not matching Access Token context
+ message: Client does not have sufficient permissions to perform this action.
+ GENERIC_403_INVALID_TOKEN_CONTEXT:
+ summary: Invalid access token context
+ description: Reflects some inconsistency between information in some field of the API and the related OAuth2 Token
value:
status: 403
code: INVALID_TOKEN_CONTEXT
- message: "Phone Number does not match with Access Token context"
- PaymentDenied:
- summary: Payment denied by business
+ message: "Phone Number is not consistent with access token."
+ GENERIC_403_PAYMENT_DENIED:
+ summary: Generic Payment Denied
+ description: Payment denied by business
value:
status: 403
code: CARRIER_BILLING.PAYMENT_DENIED
- message: "Payment denied by business"
+ message: "Payment denied by business."
PaymentConfirmPermissionDenied403:
description: |-
Client does not have sufficient permission.
In addition to regular PERMISSION_DENIED scenario other scenarios may exist:
- - 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").
+ - Phone Number provided not matching Access Token context ("code": "INVALID_TOKEN_CONTEXT","message": "Phone Number is not consistent with access token.").
+ - Payment denied by business ("code": "CARRIER_BILLING.PAYMENT_DENIED","message": "Payment denied by business.").
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
@@ -1655,29 +1683,31 @@ components:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
- Generic403:
- summary: Forbidden
+ GENERIC_403_PERMISSION_DENIED:
+ description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
value:
status: 403
code: PERMISSION_DENIED
- message: "Operation not allowed: ..."
- PhoneNumberMismatch:
- summary: Phone Number provided not matching Access Token context
+ message: Client does not have sufficient permissions to perform this action.
+ GENERIC_403_INVALID_TOKEN_CONTEXT:
+ summary: Invalid access token context
+ description: Reflects some inconsistency between information in some field of the API and the related OAuth2 Token
value:
status: 403
code: INVALID_TOKEN_CONTEXT
- message: "Phone Number does not match with Access Token context"
- PaymentDenied:
- summary: Payment denied by business
+ message: "Phone Number is not consistent with access token."
+ GENERIC_403_PAYMENT_DENIED:
+ summary: Generic Payment Denied
+ description: Payment denied by business
value:
status: 403
code: CARRIER_BILLING.PAYMENT_DENIED
- message: "Payment denied by business"
+ 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 provided not matching Access Token context ("code": "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 is not consistent with access token.").
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
@@ -1686,23 +1716,24 @@ components:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
- Generic403:
- summary: Forbidden
+ GENERIC_403_PERMISSION_DENIED:
+ description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
value:
status: 403
code: PERMISSION_DENIED
- message: "Operation not allowed: ..."
- PhoneNumberMismatch:
- summary: Phone Number provided not matching Access Token context
+ message: Client does not have sufficient permissions to perform this action.
+ GENERIC_403_INVALID_TOKEN_CONTEXT:
+ summary: Invalid access token context
+ description: Reflects some inconsistency between information in some field of the API and the related OAuth2 Token
value:
status: 403
code: INVALID_TOKEN_CONTEXT
- message: "Phone Number does not match with Access Token context"
+ message: "Phone Number is not consistent with access token."
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": "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"
@@ -1711,18 +1742,19 @@ components:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
- Generic403:
- summary: Forbidden
+ GENERIC_403_PERMISSION_DENIED:
+ description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
value:
status: 403
code: PERMISSION_DENIED
- message: "Operation not allowed: ..."
- InvalidTokenContext:
- summary: Phone Number cannot be deducted from access token context
+ message: Client does not have sufficient permissions to perform this action.
+ GENERIC_403_INVALID_TOKEN_CONTEXT:
+ summary: Invalid access token context
+ description: Reflects some inconsistency between information in some field of the API and the related OAuth2 Token
value:
status: 403
code: INVALID_TOKEN_CONTEXT
- message: "User phone number cannot be deducted from access token context"
+ message: "User phone number cannot be deducted from access token context."
Generic404:
description: Resource Not Found
headers:
@@ -1732,10 +1764,14 @@ components:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
- example:
- code: NOT_FOUND
- status: 404
- message: "The specified resource is not found"
+ examples:
+ GENERIC_404_NOT_FOUND:
+ summary: Generic Not Found
+ description: Resource is not found
+ value:
+ status: 404
+ code: NOT_FOUND
+ message: The specified resource is not found.
Generic409:
description: Conflict
headers:
@@ -1745,15 +1781,19 @@ components:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
- example:
- status: 409
- code: ALREADY_EXISTS
- message: "A specified resource duplicate entry found"
+ examples:
+ GENERIC_409_ALREADY_EXISTS:
+ summary: Generic Already Exists
+ description: Trying to create an existing resource
+ value:
+ status: 409
+ code: ALREADY_EXISTS
+ message: The resource that a client tried to create already exists.
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").
+ - 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"
@@ -1762,29 +1802,32 @@ components:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
- Generic409:
- summary: Conflict
+ GENERIC_409_ALREADY_EXISTS:
+ summary: Generic Already Exists
+ description: Trying to create an existing resource
value:
- code: ALREADY_EXISTS
status: 409
- message: "Payment confirmation in progress"
- AlreadyConfirmed:
- summary: paymentId is already confirmed
+ code: ALREADY_EXISTS
+ message: The resource that a client tried to create already exists.
+ GENERIC_409_ALREADY_CONFIRMED:
+ summary: Generic Already Confirmed
+ description: paymentId is already confirmed
value:
code: CARRIER_BILLING.PAYMENT_CONFIRMED
status: 409
- message: "Payment has been confirmed"
- AlreadyCancelled:
- summary: paymentId is already cancelled
+ message: "Payment has been confirmed."
+ GENERIC_409_ALREADY_CANCELLED:
+ summary: Generic Already Cancelled
+ description: paymentId is already cancelled
value:
code: CARRIER_BILLING.PAYMENT_CANCELLED
status: 409
- message: "Payment has been cancelled"
+ 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").
+ - 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"
@@ -1793,24 +1836,27 @@ components:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
- Generic409:
- summary: Conflict
+ GENERIC_409_ALREADY_EXISTS:
+ summary: Generic Already Exists
+ description: Trying to create an existing resource
value:
- code: ALREADY_EXISTS
status: 409
- message: "Payment cancellation in progress"
- AlreadyConfirmed:
- summary: paymentId is already confirmed
+ code: ALREADY_EXISTS
+ message: The resource that a client tried to create already exists.
+ GENERIC_409_ALREADY_CONFIRMED:
+ summary: Generic Already Confirmed
+ description: paymentId is already confirmed
value:
code: CARRIER_BILLING.PAYMENT_CONFIRMED
status: 409
- message: "Payment has been confirmed"
- AlreadyCancelled:
- summary: paymentId is already cancelled
+ message: "Payment has been confirmed."
+ GENERIC_409_ALREADY_CANCELLED:
+ summary: Generic Already Cancelled
+ description: paymentId is already cancelled
value:
code: CARRIER_BILLING.PAYMENT_CANCELLED
status: 409
- message: "Payment has been cancelled"
+ message: "Payment has been cancelled."
Generic410:
description: Gone
headers:
@@ -1820,17 +1866,21 @@ components:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
- example:
- code: GONE
- status: 410
- message: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available
+ examples:
+ GENERIC_410_GONE:
+ summary: Generic Gone
+ description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available
+ value:
+ status: 410
+ code: GONE
+ message: Access to the target resource is no longer available.
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").
+ - 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"
@@ -1839,24 +1889,27 @@ components:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
- PhoneNumberRequired:
- summary: Phone Number is required
+ GENERIC_422_PHONE_NUMBER_REQUIRED:
+ summary: Generic Phone Number Required
+ description: 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
+ message: "Phone Number is required."
+ GENERIC_422_UNAUTHORIZED_AMOUNT:
+ summary: Generic Unauthorized Amount
+ description: 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
+ message: "Unauthorized amount requested."
+ GENERIC_422_USER_MOBILE_ACCUMULATED_THRESHOLD_AMOUNT_OVERPASSED:
+ summary: Generic User Mobile Accumulated threshold Amount Overpassed
+ description: 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"
+ 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.
@@ -1870,12 +1923,13 @@ components:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
- PhoneNumberRequired:
- summary: Phone Number is required
+ GENERIC_422_PHONE_NUMBER_REQUIRED:
+ summary: Generic Phone Number Required
+ description: 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"
+ message: "Phone Number is required."
Generic429:
description: Too Many Requests
headers:
@@ -1885,10 +1939,14 @@ components:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
- example:
- code: TOO_MANY_REQUESTS
- status: 429
- message: Either out of resource quota or reaching rate limiting.
+ examples:
+ GENERIC_429_TOO_MANY_REQUESTS:
+ summary: Generic Too Many Requests
+ description: API Server request limit is overpassed
+ value:
+ status: 429
+ code: TOO_MANY_REQUESTS
+ message: Either out of resource quota or reaching rate limiting.
Generic500:
description: Server error
headers:
@@ -1898,10 +1956,14 @@ components:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
- example:
- code: SERVER_ERROR
- status: 500
- message: "Server Error"
+ examples:
+ GENERIC_500_INTERNAL:
+ summary: Generic Server Error
+ description: Problem in Server side. Regular Server Exception
+ value:
+ status: 500
+ code: INTERNAL
+ message: Unknown server error. Typically a server bug.
Generic503:
description: Service unavailable
headers:
@@ -1911,10 +1973,14 @@ components:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
- example:
- code: SERVICE_UNAVAILABLE
- status: 503
- message: "Service unavailable"
+ examples:
+ GENERIC_503_UNAVAILABLE:
+ summary: Generic Service Unavailable
+ description: Service is not available. Temporary situation usually related to maintenance process in the server side
+ value:
+ status: 503
+ code: UNAVAILABLE
+ message: Service Unavailable.
Generic504:
description: Request timeout exceeded
headers:
@@ -1924,10 +1990,14 @@ components:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
- example:
- code: REQUEST_TIMEOUT_EXCEEDED
- status: 504
- message: "Request timeout exceeded"
+ examples:
+ GENERIC_504_TIMEOUT:
+ summary: Generic Request Timeout
+ description: API Server Timeout
+ value:
+ status: 504
+ code: TIMEOUT
+ message: Request timeout exceeded.
parameters:
x-correlator:
name: x-correlator
diff --git a/documentation/API_documentation/carrier-billing-API-Readiness-Checklist.md b/documentation/API_documentation/carrier-billing-API-Readiness-Checklist.md
index 75c79b3..c6128a4 100644
--- a/documentation/API_documentation/carrier-billing-API-Readiness-Checklist.md
+++ b/documentation/API_documentation/carrier-billing-API-Readiness-Checklist.md
@@ -1,16 +1,16 @@
# API Readiness Checklist
-Checklist for Carrier Billing v0.3.0-rc.1 in r1.1.
+Checklist for Carrier Billing v0.3.0 in r1.2
| Nr | API release assets | alpha | release-candidate | initial
public | stable
public | Status | Comments |
|----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|:----:|
-| 1 | API definition | M | M | M | M | Y | [link](/code/API_definitions/carrier_billing.yaml) |
+| 1 | API definition | M | M | M | M | Y | [link](/code/API_definitions/carrier-billing.yaml) |
| 2 | Design guidelines from Commonalities applied | O | M | M | M | Y | |
| 3 | Guidelines from ICM applied | O | M | M | M | Y | |
| 4 | API versioning convention applied | M | M | M | M | Y | |
-| 5 | API documentation | M | M | M | M | Y | link |
-| 6 | User stories | O | O | O | M | Y | link |
-| 7 | Basic API test cases & documentation | O | M | M | M | tbd | link |
+| 5 | API documentation | M | M | M | M | Y | [link](/code/API_definitions/carrier-billing.yaml) |
+| 6 | User stories | O | O | O | M | Y | [link](/documentation/API_documentation/Carrier Billing User Story.md) |
+| 7 | Basic API test cases & documentation | O | M | M | M | Y | [link](/code/Test_definitions) |
| 8 | Enhanced API test cases & documentation | O | O | O | M | N | link |
| 9 | Test result statement | O | O | O | M | N | link |
| 10 | API release numbering convention applied | M | M | M | M | Y | |
diff --git a/documentation/API_documentation/Carrier Billing User Story.md b/documentation/API_documentation/carrier-billing-User-Story.md
similarity index 99%
rename from documentation/API_documentation/Carrier Billing User Story.md
rename to documentation/API_documentation/carrier-billing-User-Story.md
index 826e298..b32f4d7 100644
--- a/documentation/API_documentation/Carrier Billing User Story.md
+++ b/documentation/API_documentation/carrier-billing-User-Story.md
@@ -1,52 +1,52 @@
-**User Story: Make a Payment request in one step**
-
-
-| **Item** | **Details** |
-| ---- | ------- |
-| ***Summary*** | As an application developer belonging to an enterprise, I want to request (using my application server/backend service) a payment (one-time fee -in initial phase- or recurring -in a later phase- ) to be billed against a customer's carrier bill, so that I can offer customers payment alternatives. |
-| ***Roles, Actors and Scope*** | **Roles:** Customer:User
**Actors:** Application service providers, hyperscalers, application developers.
**Scope:** *Request Payment on Carrier Bill* \- Initiate Carrier Billing approval process with Customer from Carrier Channels (SMS/App) |
-| ***Pre-conditions*** |The preconditions are listed below:
- The Customer:User has Carrier Billing activated as payment method.
- The Customer:User has initiated payment via Carrier Billing from application/portal/product channel
- The PaymentRequester has verified that associated carrier billing service belongs to the Customer:User (Generally as part of adding a new payment method, 2-Factor-Authorization or equivalent)
|
-| ***Activities/Steps*** | **Starts when:** The customer application server makes a request to the Carrier Billing service (API) to trigger the payment.
**Ends when:** The payment is completed and the customer application customer can query details of that payment.
|
-| ***Post-conditions*** | After customer application server performs the payment, payment details can be queried. |
-| ***Exceptions*** | Several exceptions might occur during the Carrier Billing API operations:
- Unauthorized: Not valid credentials (e.g. use of already expired access token).
- Invalid input: Not valid input data to invoke operation (e.g. merchant information not provided or unknown).
- Denied by Carrier: Any user/business condition and/or regulation that forbids the perform of the payment
- Conflict: Internal configuration policies don't allow for Payment Execution/Cancellation.
|
-
-
-**User Story: Make a Payment request in two steps**
-
-
-| **Item** | **Details** |
-| ---- | ------- |
-| ***Summary*** | As an application developer belonging to an enterprise, I want to request (using my application server/backend service) a payment (one-time fee -in initial phase- or recurring -in a later phase- ) to be billed against a customer's carrier bill, so that I can offer customers payment alternatives. The payment process will be split in 2 parts:
- Payment preparation request (that did not trigger the payment but only prepare it)
- Payment confirmation or cancellation. The payment confirmation triggers the payment itself. Optionally, as per business needs, payment confirmation may require a payment validation in advance (i.e. an optional step between payment preparation and payment confirmation)
|
-| ***Roles, Actors and Scope*** | **Roles:** Customer:User
**Actors:** Application service providers, hyperscalers, application developers.
**Scope:** *Request Payment on Carrier Bill* \- Initiate Carrier Billing 2-steps approval process with Customer from Carrier Channels (SMS/App) |
-| ***Pre-conditions*** |The preconditions are listed below:
- The Customer:User has Carrier Billing activated as payment method.
- The Customer:User has initiated 2-steps payment via Carrier Billing from application/portal/product channel
- The PaymentRequester has verified that associated carrier service belongs to the Customer:User (Generally as part of adding a new payment method, 2FA or equivalent)
|
-| ***Activities/Steps*** | **Starts when:** The customer application server makes a request to the Carrier Billing service (API) to trigger a 2-steps payment.
**Intermediate steps:** The customer application server makes a request to confirm or cancel the payment preparation
**Ends when:** If payment confirmation is provided the payment is completed. If a payment cancellation is provided (explicit cancellation) or if neither a confirmation or cancellation is received after a predefined business delay (implicitly by expiration), the payment preparation is cancelled.
For both cases the customer application can retrieve and/or query details of that payment
|
-| ***Post-conditions*** | After customer application server performs the payment, payment details can be queried. A payment can stay in preparation status only for a predefined business delay. |
-| ***Exceptions*** | Several exceptions might occur during the Carrier Billing API operations:
- Unauthorized: Not valid credentials (e.g. use of already expired access token).
- Invalid input: Not valid input data to invoke operation like for example:
merchant information not provided or unknown,
payment identifier not existing or not linked to the customer:user,
payment confirmation for an expired payment,
payment cancellation request for an already confirmed payment). - Denied by Carrier: Any user/business condition and/or regulation that forbids the perform of the payment. Payment preparation as payment confirmation could be denied
- Conflict: Internal configuration policies don't allow for Payment Execution/Cancellation.
|
-
-
-**User Story: Retrieve a Payment from its identifier**
-
-
-| **Item** | **Details** |
-| ---- | ------- |
-| ***Summary*** | As an application developer belonging to an enterprise, I want to get details of one performed payment (from its id) by means of that application. |
-| ***Roles, Actors and Scope*** | **Roles:** Customer:User
**Actors:** Application service providers, hyperscalers, application developers.
**Scope:** *Request Payments Details done against Carrier Billing* |
-| ***Pre-conditions*** |The preconditions are listed below:
- The Customer:User has performed payments via application, both success and failed
- The Customer:User has payment identification.
|
-| ***Activities/Steps*** | **Starts when:** The customer application server makes a request to the Carrier Billing service (API) to get payments details performed via that application providing payment identifier.
**Ends when:** Response is received from Carrier Billing service showing the payment details |
-| ***Post-conditions*** | Requester receives a complete representation of the payment. |
-| ***Exceptions*** | Several exceptions might occur during the Carrier Billing API operations:
- Unauthorized: Not valid credentials (e.g. use of already expired access token).
- Invalid input: Not valid payment identifier to invoke operation.
- Denied by Carrier: Any user/business condition and/or regulation that forbids the retrieval of the payment
|
-
-
-**User Story: Retrieve a Payment list**
-
-
-| **Item** | **Details** |
-| ---- | ------- |
-| ***Summary*** | As an application developer belonging to an enterprise, I want to get a list of performed payments from criteria (using my application server/backend service), by means of that application. |
-| ***Roles, Actors and Scope*** | **Roles:** Customer:User
**Actors:** Application service providers, hyperscalers, application developers.
**Scope:** *Request Payments list done against Carrier Billing* |
-| ***Pre-conditions*** |The preconditions are listed below:
- The Customer:User has performed payments via application, both success and failed
- The requester provides a list of criteria(s) to select payment (Customer/user identifier, payment status)
|
-| ***Activities/Steps*** | **Starts when:** The customer application server makes a request to the Carrier Billing service (API) to get payment/payments details performed via that application
**Ends when:** Response is received from Carrier Billing service showing the details |
-| ***Post-conditions*** | N/A |
-| ***Exceptions*** | Several exceptions might occur during the Carrier Billing API operations:
- Unauthorized: Not valid credentials (e.g. use of already expired access token).
- Denied by Carrier: Any user/business condition and/or regulation that forbids the retrieval of the payment
|
-
-
+**User Story: Make a Payment request in one step**
+
+
+| **Item** | **Details** |
+| ---- | ------- |
+| ***Summary*** | As an application developer belonging to an enterprise, I want to request (using my application server/backend service) a payment (one-time fee -in initial phase- or recurring -in a later phase- ) to be billed against a customer's carrier bill, so that I can offer customers payment alternatives. |
+| ***Roles, Actors and Scope*** | **Roles:** Customer:User
**Actors:** Application service providers, hyperscalers, application developers.
**Scope:** *Request Payment on Carrier Bill* \- Initiate Carrier Billing approval process with Customer from Carrier Channels (SMS/App) |
+| ***Pre-conditions*** |The preconditions are listed below:
- The Customer:User has Carrier Billing activated as payment method.
- The Customer:User has initiated payment via Carrier Billing from application/portal/product channel
- The PaymentRequester has verified that associated carrier billing service belongs to the Customer:User (Generally as part of adding a new payment method, 2-Factor-Authorization or equivalent)
|
+| ***Activities/Steps*** | **Starts when:** The customer application server makes a request to the Carrier Billing service (API) to trigger the payment.
**Ends when:** The payment is completed and the customer application customer can query details of that payment.
|
+| ***Post-conditions*** | After customer application server performs the payment, payment details can be queried. |
+| ***Exceptions*** | Several exceptions might occur during the Carrier Billing API operations:
- Unauthorized: Not valid credentials (e.g. use of already expired access token).
- Invalid input: Not valid input data to invoke operation (e.g. merchant information not provided or unknown).
- Denied by Carrier: Any user/business condition and/or regulation that forbids the perform of the payment
- Conflict: Internal configuration policies don't allow for Payment Execution/Cancellation.
|
+
+
+**User Story: Make a Payment request in two steps**
+
+
+| **Item** | **Details** |
+| ---- | ------- |
+| ***Summary*** | As an application developer belonging to an enterprise, I want to request (using my application server/backend service) a payment (one-time fee -in initial phase- or recurring -in a later phase- ) to be billed against a customer's carrier bill, so that I can offer customers payment alternatives. The payment process will be split in 2 parts:
- Payment preparation request (that did not trigger the payment but only prepare it)
- Payment confirmation or cancellation. The payment confirmation triggers the payment itself. Optionally, as per business needs, payment confirmation may require a payment validation in advance (i.e. an optional step between payment preparation and payment confirmation)
|
+| ***Roles, Actors and Scope*** | **Roles:** Customer:User
**Actors:** Application service providers, hyperscalers, application developers.
**Scope:** *Request Payment on Carrier Bill* \- Initiate Carrier Billing 2-steps approval process with Customer from Carrier Channels (SMS/App) |
+| ***Pre-conditions*** |The preconditions are listed below:
- The Customer:User has Carrier Billing activated as payment method.
- The Customer:User has initiated 2-steps payment via Carrier Billing from application/portal/product channel
- The PaymentRequester has verified that associated carrier service belongs to the Customer:User (Generally as part of adding a new payment method, 2FA or equivalent)
|
+| ***Activities/Steps*** | **Starts when:** The customer application server makes a request to the Carrier Billing service (API) to trigger a 2-steps payment.
**Intermediate steps:** The customer application server makes a request to confirm or cancel the payment preparation
**Ends when:** If payment confirmation is provided the payment is completed. If a payment cancellation is provided (explicit cancellation) or if neither a confirmation or cancellation is received after a predefined business delay (implicitly by expiration), the payment preparation is cancelled.
For both cases the customer application can retrieve and/or query details of that payment
|
+| ***Post-conditions*** | After customer application server performs the payment, payment details can be queried. A payment can stay in preparation status only for a predefined business delay. |
+| ***Exceptions*** | Several exceptions might occur during the Carrier Billing API operations:
- Unauthorized: Not valid credentials (e.g. use of already expired access token).
- Invalid input: Not valid input data to invoke operation like for example:
merchant information not provided or unknown,
payment identifier not existing or not linked to the customer:user,
payment confirmation for an expired payment,
payment cancellation request for an already confirmed payment). - Denied by Carrier: Any user/business condition and/or regulation that forbids the perform of the payment. Payment preparation as payment confirmation could be denied
- Conflict: Internal configuration policies don't allow for Payment Execution/Cancellation.
|
+
+
+**User Story: Retrieve a Payment from its identifier**
+
+
+| **Item** | **Details** |
+| ---- | ------- |
+| ***Summary*** | As an application developer belonging to an enterprise, I want to get details of one performed payment (from its id) by means of that application. |
+| ***Roles, Actors and Scope*** | **Roles:** Customer:User
**Actors:** Application service providers, hyperscalers, application developers.
**Scope:** *Request Payments Details done against Carrier Billing* |
+| ***Pre-conditions*** |The preconditions are listed below:
- The Customer:User has performed payments via application, both success and failed
- The Customer:User has payment identification.
|
+| ***Activities/Steps*** | **Starts when:** The customer application server makes a request to the Carrier Billing service (API) to get payments details performed via that application providing payment identifier.
**Ends when:** Response is received from Carrier Billing service showing the payment details |
+| ***Post-conditions*** | Requester receives a complete representation of the payment. |
+| ***Exceptions*** | Several exceptions might occur during the Carrier Billing API operations:
- Unauthorized: Not valid credentials (e.g. use of already expired access token).
- Invalid input: Not valid payment identifier to invoke operation.
- Denied by Carrier: Any user/business condition and/or regulation that forbids the retrieval of the payment
|
+
+
+**User Story: Retrieve a Payment list**
+
+
+| **Item** | **Details** |
+| ---- | ------- |
+| ***Summary*** | As an application developer belonging to an enterprise, I want to get a list of performed payments from criteria (using my application server/backend service), by means of that application. |
+| ***Roles, Actors and Scope*** | **Roles:** Customer:User
**Actors:** Application service providers, hyperscalers, application developers.
**Scope:** *Request Payments list done against Carrier Billing* |
+| ***Pre-conditions*** |The preconditions are listed below:
- The Customer:User has performed payments via application, both success and failed
- The requester provides a list of criteria(s) to select payment (Customer/user identifier, payment status)
|
+| ***Activities/Steps*** | **Starts when:** The customer application server makes a request to the Carrier Billing service (API) to get payment/payments details performed via that application
**Ends when:** Response is received from Carrier Billing service showing the details |
+| ***Post-conditions*** | N/A |
+| ***Exceptions*** | Several exceptions might occur during the Carrier Billing API operations:
- Unauthorized: Not valid credentials (e.g. use of already expired access token).
- Denied by Carrier: Any user/business condition and/or regulation that forbids the retrieval of the payment
|
+
+
diff --git a/documentation/API_documentation/carrier-billing-refund-API-Readiness-Checklist.md b/documentation/API_documentation/carrier-billing-refund-API-Readiness-Checklist.md
index 4d80d77..650ec51 100644
--- a/documentation/API_documentation/carrier-billing-refund-API-Readiness-Checklist.md
+++ b/documentation/API_documentation/carrier-billing-refund-API-Readiness-Checklist.md
@@ -1,6 +1,6 @@
# API Readiness Checklist
-Checklist for Carrier Billing Refund v0.1.0-rc.1 in r1.1
+Checklist for Carrier Billing Refund v0.1.0 in r1.2
| Nr | API release assets | alpha | release-candidate | initial
public | stable
public | Status | Comments |
|----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|:----:|
@@ -8,9 +8,9 @@ Checklist for Carrier Billing Refund v0.1.0-rc.1 in r1.1
| 2 | Design guidelines from Commonalities applied | O | M | M | M | Y | |
| 3 | Guidelines from ICM applied | O | M | M | M | Y | |
| 4 | API versioning convention applied | M | M | M | M | Y | |
-| 5 | API documentation | M | M | M | M | Y | link |
-| 6 | User stories | O | O | O | M | N | link |
-| 7 | Basic API test cases & documentation | O | M | M | M | tbd | link |
+| 5 | API documentation | M | M | M | M | Y | [link](/code/API_definitions/carrier-billing-refund.yaml) |
+| 6 | User stories | O | O | O | M | Y | [link](/documentation/API_documentation/Carrier Billing Refund User Story.md) |
+| 7 | Basic API test cases & documentation | O | M | M | M | Y | [link](/code/Test_definitions) |
| 8 | Enhanced API test cases & documentation | O | O | O | M | N | link |
| 9 | Test result statement | O | O | O | M | N | link |
| 10 | API release numbering convention applied | M | M | M | M | Y | |
diff --git a/documentation/API_documentation/Carrier Billing Refund User Story.md b/documentation/API_documentation/carrier-billing-refund-User-Story.md
similarity index 100%
rename from documentation/API_documentation/Carrier Billing Refund User Story.md
rename to documentation/API_documentation/carrier-billing-refund-User-Story.md