openapi: 3.0.3 info: description: |- Service Enabling Payments against Operator Carrier Billing Systems # Introduction 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 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 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 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.5rc1, only one-off payments are covered**. Recurrent payments (a.k.a. payment subscriptions) are not covered so far. The API provides several endpoints/operations: - An endpoint to request a 1-STEP Payment, named `createPayment`. - 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 `sink` when provided by API client. The usage of the API is based on Payment resource, which can be created (in 1-STEP or 2-STEP Payment process), confirmed/cancelled (for 2-STEP Payment process), and queried/retrieved (list of payments or a specific payment). 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 (`sink` param) on which status change notifications, regarding the payment, can be received from the Telco Operator. This is an optional parameter. Following diagram shows the API resources operation sequencing: ![PaymentSequence](https://raw.githubusercontent.com/camaraproject/CarrierBillingCheckOut/r3.2/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/r3.2/documentation/API_documentation/resources/Carrier_Billing_State_Engine.JPG) State transitions: **1-STEP Payment** If `createPayment` is a **SYNC** process: - Response contains `paymentId` and paymentStatus=`succeeded`. - In case of any error scenario `paymentId` is not created. If `createPayment` is an **ASYNC** process: - Response contains `paymentId` and paymentStatus=`processing`. After completion: - When payment is successfully completed then paymentStatus=`succeeded`. - When payment is not successfully performed then paymentStatus=`denied`. - In case of any error scenario `paymentId` is not created. **2-STEP Payment** FIRST STEP If `preparePayment` is a **SYNC** process: - **Case A** - `validationInfo` is NOT provided in response. - Response contains `paymentId` and paymentStatus=`reserved`. - **Case B** - `validationInfo` is provided in response. - Response contains `paymentId` and paymentStatus=`pending_validation`. - In case of any error scenario `paymentId` is not created. If `preparePayment` is an **ASYNC** process: - **Case A** - `validationInfo` is NOT provided in response. - Response contains `paymentId` and paymentStatus=`processing`. After completion: - When payment preparation is successfully completed then paymentStatus=`reserved`. - When payment preparation is not successfully performed then paymentStatus=`denied`. - **Case B** - `validationInfo` is provided in response. - Response contains `paymentId` and paymentStatus=`processing`. After completion: - When payment preparation is successfully completed then paymentStatus=`pending_validation`. [1] - When payment preparation is not successfully performed then paymentStatus=`denied`. - In case of any error scenario `paymentId` is not created. [OPTIONAL] VALIDATE STEP [1] After `validatePayment`, paymentStatus=`reserved` OR `denied`, depending whether it was successful or not. SECOND STEP After `confirmPayment`, paymentStatus=`succeeded` OR `denied`, depending whether it was successful or not. After `cancelPayment`, paymentStatus=`cancelled`. # Generic Clarification about optional parameters Regarding optional parameters, they can be conditionally mandatory for a Telco Operator to implement them based on business scenarios or applicable regulations in a given market. NOTE: Within a given market, in a multi Telco Operator ecosystem, the set of optional parameters to be implemented MUST be aligned among involved Telco Operators. # Authorization and authentication The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile. The specific authorization flows to be used will be agreed upon during the onboarding process, happening between the API consumer and the API provider, taking into account the declared purpose for accessing the API, whilst also being subject to the prevailing legal framework dictated by local legislation. In cases where personal data is processed by the API and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design. # Identifying the phone number from the access token This API requires the API consumer to identify a phone number as the subject of the API as follows: - When the API is invoked using a two-legged access token, the subject will be identified from the optional `phoneNumber` field, which therefore MUST be provided. - When a three-legged access token is used however, this optional identifier MUST NOT be provided, as the subject will be uniquely identified from the access token. This approach simplifies API usage for API consumers using a three-legged access token to invoke the API by relying on the information that is associated with the access token and was identified during the authentication process. ## Error handling: - If the subject cannot be identified from the access token and the optional `phoneNumber` field is not included in the request, then the server will return an error with the `422 MISSING_IDENTIFIER` error code. - If the subject can be identified from the access token and the optional `phoneNumber` field is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same phone number is identified by these two methods, as the server is unable to make this comparison. # Additional CAMARA error responses The list of error codes in this API specification is not exhaustive. Therefore the API specification may not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`. Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified in the `API Readiness Checklist` document associated to this API version. As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API. # Further info and support (FAQs will be added in a later version of the documentation) version: wip title: Carrier Billing license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html x-camara-commonalities: wip externalDocs: description: Product documentation at Camara url: https://github.com/camaraproject/CarrierBillingCheckOut servers: - url: "{apiRoot}/carrier-billing/vwip" variables: apiRoot: default: http://localhost:9091 description: API root, defined by the service provider tags: - name: One Step Payment description: Operations to manage One Step Payment procedure - name: Two Step Payment description: Operations to manage Two Step Payment procedure - name: Payment description: Operations to obtain information about payments paths: /payments: post: security: - openId: - carrier-billing:payments:create tags: - One Step Payment summary: Create a new Payment operationId: createPayment description: Create a new payment for subsequent charging to an end user. Carrier Billing Server will apply the charging according to business configuration for the end user. parameters: - $ref: "#/components/parameters/x-correlator" requestBody: description: Amount transaction content: application/json: schema: $ref: "#/components/schemas/CreatePayment" required: true callbacks: notifications: "{$request.body#/sink}": post: security: - {} - notificationsBearerAuth: [] tags: - Payment Notifications summary: Carrier Billing payment notifications operationId: createPaymentNotification 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/cloudevents+json: schema: $ref: "#/components/schemas/CloudEvent" required: true responses: "204": description: Successful notification headers: x-correlator: $ref: "#/components/headers/x-correlator" "400": $ref: "#/components/responses/Generic400" "401": $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/Generic403" "410": $ref: "#/components/responses/Generic410" "429": $ref: "#/components/responses/Generic429" responses: "201": description: Created headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/PaymentCreated" "400": $ref: "#/components/responses/PaymentInvalid400" "401": $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/PaymentPermissionDenied403" "404": $ref: "#/components/responses/IdentifierNotFound404" "409": $ref: "#/components/responses/Generic409" "422": $ref: "#/components/responses/PaymentUnprocessable422" "429": $ref: "#/components/responses/Generic429" get: security: - openId: - carrier-billing:payments:read tags: - Payment summary: Get a list of payments operationId: retrievePayments description: |- Retrieve a list of payments and their details based on some filtering criteria. Regardless the payment criteria provided, response MUST be always limited to payments performed by the API client (i.e same oAuth credentials) triggering this request. This is to guarantee no API client can check payments performed by other, therefore avoiding any legal or privacy topic. When Access Token is issued for a given user phone number, the list of payments returned would be only the ones associated to that user phone number and API client. When Access Token is not associated to a user phone number, therefore only associated to API client the list of payments returned would be all the ones managed by that API client. Considerations regarding `paymentCreationDate.gte`, `paymentCreationDate.lte`: - If both included, return payments in that date range - If no one included, no filtering by date range is applied - If only settled `paymentCreationDate.gte`, `paymentCreationDate.lte` is considered current date-time - If only settled `paymentCreationDate.lte`, every payment existing in the Operator billing system until such date is returned parameters: - $ref: "#/components/parameters/x-correlator" - $ref: "#/components/parameters/Page" - $ref: "#/components/parameters/PerPage" - $ref: "#/components/parameters/StartPaymentCreationDate" - $ref: "#/components/parameters/EndPaymentCreationDate" - $ref: "#/components/parameters/Order" - $ref: "#/components/parameters/PaymentStatus" - $ref: "#/components/parameters/MerchantIdentifier" responses: "200": description: OK headers: x-correlator: $ref: "#/components/headers/x-correlator" Content-Last-Key: $ref: "#/components/headers/Content-Last-Key" X-Total-Count: $ref: "#/components/headers/X-Total-Count" content: application/json: schema: $ref: "#/components/schemas/PaymentArray" "400": $ref: "#/components/responses/GetPaymentsInvalid400" "401": $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/Generic403" "429": $ref: "#/components/responses/Generic429" /payments/{paymentId}: get: security: - openId: - carrier-billing:payments:read tags: - Payment summary: Get payment details operationId: retrievePayment description: |- Retrieve payment details for a given payment. When Access Token is issued for a given user phone number, the payment details would be returned in case the `paymentId` is associated to that user phone number and API client, otherwise `404 NOT_FOUND` will be returned. When Access Token is not associated to a user phone number, the payment details are returned in case the API client managed that payment. parameters: - name: paymentId in: path description: Payment identifier that was obtained from the create payment operation required: true schema: type: string - $ref: "#/components/parameters/x-correlator" responses: "200": description: OK headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/Payment" "400": $ref: "#/components/responses/Generic400" "401": $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/Generic403" "404": $ref: "#/components/responses/Generic404" "429": $ref: "#/components/responses/Generic429" /payments/prepare: post: security: - openId: - carrier-billing:payments:create tags: - Two Step Payment summary: Prepare (reserve) a payment operationId: preparePayment description: Prepare a new payment procedure. Carrier Billing Server will apply the charging according to business configuration for the end user. parameters: - $ref: "#/components/parameters/x-correlator" requestBody: description: Amount transaction content: application/json: schema: $ref: "#/components/schemas/BodyAmountReservationTransactionForReserveInput" required: true callbacks: notifications: "{$request.body#/sink}": post: security: - {} - notificationsBearerAuth: [] tags: - Payment Notifications summary: Carrier Billing payment notifications operationId: preparePaymentNotification 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/cloudevents+json: schema: $ref: "#/components/schemas/CloudEvent" required: true responses: "204": description: Successful notification headers: x-correlator: $ref: "#/components/headers/x-correlator" "400": $ref: "#/components/responses/Generic400" "401": $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/Generic403" "410": $ref: "#/components/responses/Generic410" "429": $ref: "#/components/responses/Generic429" responses: "201": description: Created headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/BodyAmountReservationTransactionForReserve" "400": $ref: "#/components/responses/Payment2StepPrepareInvalid400" "401": $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/PaymentPermissionDenied403" "404": $ref: "#/components/responses/IdentifierNotFound404" "409": description: Conflict headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 409 code: enum: - ALREADY_EXISTS examples: GENERIC_409_ALREADY_EXISTS: summary: Generic Already Exists description: Trying to create an existing resource value: code: ALREADY_EXISTS status: 409 message: "Another session is created for the same UE" "422": $ref: "#/components/responses/PaymentUnprocessable422" "429": $ref: "#/components/responses/Generic429" /payments/{paymentId}/validate: post: security: - openId: - carrier-billing:payments:write tags: - Two Step Payment summary: Validate a payment operationId: validatePayment description: Validate a given payment with a code, identified by its paymentId. This process is applicable for 2-STEP, when optionally required by business case. parameters: - name: paymentId in: path description: The payment identifier returned when the payment preparation was created. schema: type: string required: true - $ref: "#/components/parameters/x-correlator" requestBody: description: Payment Validation content: application/json: schema: $ref: "#/components/schemas/ValidatePayment" required: true responses: "204": description: Validation Succeeded headers: x-correlator: $ref: "#/components/headers/x-correlator" "400": $ref: "#/components/responses/ValidatePaymentInvalid400" "401": $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/Generic403" "404": $ref: "#/components/responses/Generic404" "409": description: Conflict headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 409 code: enum: - ALREADY_EXISTS examples: GENERIC_409_ALREADY_EXISTS: summary: Conflict description: paymentId already validated value: code: ALREADY_EXISTS status: 409 message: "Payment already validated" "429": $ref: "#/components/responses/Generic429" /payments/{paymentId}/confirm: post: security: - openId: - carrier-billing:payments:write tags: - Two Step Payment summary: Confirm a payment operationId: confirmPayment description: Confirm a reservation of a given payment, identified by its paymentId. parameters: - name: paymentId in: path description: The payment identifier returned when the payment preparation was created. schema: type: string required: true - $ref: "#/components/parameters/x-correlator" requestBody: description: capture PhoneNumber for payment operation content: application/json: schema: $ref: "#/components/schemas/PhoneNumber" required: true responses: "202": description: Payment confirmation accepted headers: x-correlator: $ref: "#/components/headers/x-correlator" "400": $ref: "#/components/responses/Payment2StepInvalid400" "401": $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/PaymentConfirmPermissionDenied403" "404": $ref: "#/components/responses/Identifier2StepNotFound404" "409": $ref: "#/components/responses/PaymentConfirmConflict409" "422": $ref: "#/components/responses/PaymentSecondStepUnprocessable422" "429": $ref: "#/components/responses/Generic429" /payments/{paymentId}/cancel: post: security: - openId: - carrier-billing:payments:write tags: - Two Step Payment summary: Cancel a payment operationId: cancelPayment description: Cancel a reservation of a given payment, identified by its paymentId. parameters: - name: paymentId in: path description: The payment identifier returned when the payment preparation was created. required: true schema: type: string - $ref: "#/components/parameters/x-correlator" requestBody: description: capture PhoneNumber for payment operation content: application/json: schema: $ref: "#/components/schemas/PhoneNumber" required: true responses: "202": description: Payment Cancellation Accepted headers: x-correlator: $ref: "#/components/headers/x-correlator" "400": $ref: "#/components/responses/Payment2StepInvalid400" "401": $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/PaymentCancelPermissionDenied403" "404": $ref: "#/components/responses/Identifier2StepNotFound404" "409": $ref: "#/components/responses/PaymentCancelConflict409" "422": $ref: "#/components/responses/PaymentSecondStepUnprocessable422" "429": $ref: "#/components/responses/Generic429" components: securitySchemes: openId: type: openIdConnect openIdConnectUrl: https://example.com/.well-known/openid-configuration notificationsBearerAuth: type: http scheme: bearer bearerFormat: "{$request.body#/sinkCredential.credentialType}" schemas: XCorrelator: type: string pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$ example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46" CreatePayment: type: object required: - amountTransaction properties: amountTransaction: $ref: "#/components/schemas/AmountTransactionInput" sink: type: string format: uri pattern: ^https:\/\/.+$ description: The address to which events shall be delivered, using the HTTP protocol. example: "https://endpoint.example.com/sink" sinkCredential: allOf: - description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target. - $ref: "#/components/schemas/SinkCredential" PaymentCreated: type: object required: - amountTransaction - paymentId - paymentStatus - paymentCreationDate properties: paymentId: type: string description: Unique Identifier of the payment example: "AK234rfweSBuWGFUEWFGWEVWRV" amountTransaction: $ref: "#/components/schemas/AmountTransaction" paymentStatus: type: string description: Specifies the payment status (`processing`, `pending_validation`, `denied`, `reserved`, `succeeded`, `cancelled`). example: "processing" paymentCreationDate: type: string format: date-time description: Date time when the payment is created in server database. This is a technical information. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. paymentDate: type: string format: date-time description: Date time when the payment is effectively performed. This is a business information. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. sink: type: string format: uri pattern: ^https:\/\/.+$ description: The address to which events shall be delivered, using the HTTP protocol. example: "https://endpoint.example.com/sink" PaymentArray: description: A list of payment(s) type: array minItems: 0 items: $ref: "#/components/schemas/Payment" Payment: type: object required: - amountTransaction - paymentId - paymentStatus - paymentCreationDate properties: paymentId: type: string description: Unique Identifier of the payment example: "AK234rfweSBuWGFUEWFGWEVWRV" amountTransaction: $ref: "#/components/schemas/AmountTransaction" paymentStatus: type: string description: Specifies the payment status (`processing`, `pending_validation`, `denied`, `reserved`, `succeeded`, `cancelled`). example: "processing" paymentCreationDate: type: string format: date-time description: Date time when the payment is created in server database. This is a technical information. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. paymentDate: type: string format: date-time description: Date time when the payment is effectively performed. This is a business information. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. sink: type: string format: uri pattern: ^https:\/\/.+$ description: The address to which events shall be delivered, using the HTTP protocol. example: "https://endpoint.example.com/sink" SinkCredential: type: object properties: credentialType: type: string enum: - PLAIN - ACCESSTOKEN - REFRESHTOKEN description: "The type of the credential. Only `ACCESSTOKEN` is supported so far." discriminator: propertyName: credentialType mapping: PLAIN: "#/components/schemas/PlainCredential" ACCESSTOKEN: "#/components/schemas/AccessTokenCredential" REFRESHTOKEN: "#/components/schemas/RefreshTokenCredential" required: - credentialType PlainCredential: type: object description: A plain credential as a combination of an identifier and a secret. allOf: - $ref: "#/components/schemas/SinkCredential" - type: object required: - identifier - secret properties: identifier: description: The identifier might be an account or username. type: string secret: description: The secret might be a password or passphrase. type: string AccessTokenCredential: type: object description: An access token credential. allOf: - $ref: "#/components/schemas/SinkCredential" - type: object properties: accessToken: description: REQUIRED. An access token is a previously acquired token granting access to the target resource. type: string accessTokenExpiresUtc: type: string format: date-time description: REQUIRED. An absolute (UTC) timestamp at which the token shall be considered expired. Token expiration should occur after the expiration of the requested payment, allowing the client to be notified of any changes during the payment's existence. If the token expires while the payment is still active, the client will stop receiving notifications. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. accessTokenType: description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). type: string enum: - bearer required: - accessToken - accessTokenExpiresUtc - accessTokenType RefreshTokenCredential: type: object description: An access token credential with a refresh token. allOf: - $ref: "#/components/schemas/SinkCredential" - type: object properties: accessToken: description: REQUIRED. An access token is a previously acquired token granting access to the target resource. type: string accessTokenExpiresUtc: type: string format: date-time description: REQUIRED. An absolute (UTC) timestamp at which the token shall be considered expired. Token expiration should occur after the expiration of the requested payment, allowing the client to be notified of any changes during the payment's existence. If the token expires while the payment is still active, the client will stop receiving notifications. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. accessTokenType: description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). type: string enum: - bearer refreshToken: description: REQUIRED. An refresh token credential used to acquire access tokens. type: string refreshTokenEndpoint: type: string format: uri description: REQUIRED. A URL at which the refresh token can be traded for an access token. required: - accessToken - accessTokenExpiresUtc - accessTokenType - refreshToken - refreshTokenEndpoint AmountTransaction: required: - phoneNumber - paymentAmount - referenceCode type: object properties: phoneNumber: type: string description: |- Identifies the mobile account to be charged. A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. pattern: '^\+[1-9][0-9]{4,14}$' example: "+34671999000" clientCorrelator: type: string description: Uniquely identifies this create payment request. If there is a communication failure during the payment request, using the same clientCorrelator when retrying the request allows the operator to avoid applying the same charge twice. This field SHOULD be present. Same value as indicated in the request. example: "req-12f2pgh448gh2hvrfrv" paymentAmount: $ref: "#/components/schemas/PaymentAmountForCharge" referenceCode: type: string description: Merchant generated payment reference to uniquely identify the request, for instance, in the case of disputes. Same value as the one provided in the request. example: "ref-pay-834tfr2rA3v8r8vr3rv" resourceURL: type: string description: URI of the created resource (same as in the Location header) example: "urn:payments:AK234rfweSBuWGFUEWFGWEVWRV" serverReferenceCode: type: string description: Reference to the charge or refund, provided by the server, and meaningful to the server’s backend system for the purpose of reconciliation. example: "ref-pay-834tfr2rA3v8r8vr3rv-serv" AmountTransactionInput: type: object required: - paymentAmount - referenceCode properties: phoneNumber: type: string description: |- Identifies the mobile account to be charged. A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. Additional Considerations: - Take a look to section `# Identifying the phone number from the access token` regarding the use of this field. pattern: '^\+[1-9][0-9]{4,14}$' example: "+34671999000" clientCorrelator: type: string description: Uniquely identifies this create payment request. If there is a communication failure during the payment request, using the same clientCorrelator when retrying the request allows the operator to avoid applying the same charge twice. This field SHOULD be present. example: "req-12f2pgh448gh2hvrfrv" paymentAmount: $ref: "#/components/schemas/PaymentAmountForCharge" referenceCode: type: string description: Merchant generated payment reference to uniquely identify the request, for instance, in the case of disputes. example: "ref-pay-834tfr2rA3v8r8vr3rv" PaymentAmountForCharge: type: object required: - chargingInformation properties: chargingInformation: $ref: "#/components/schemas/ChargingInformation" chargingMetaData: $ref: "#/components/schemas/ChargingMetaData" paymentDetails: $ref: "#/components/schemas/PaymentDetails" PhoneNumber: type: object properties: phoneNumber: type: string description: |- Identifies the mobile account to be charged. A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. Additional Considerations: - Take a look to section `# Identifying the phone number from the access token` regarding the use of this field. pattern: '^\+[1-9][0-9]{4,14}$' example: "+34671999000" ValidatePayment: type: object required: - authorizationId - code properties: authorizationId: type: string description: Unique authorization identifier for a specific payment. example: "Fn34o8g239v3wrb3t" code: type: string description: Code received via SMS to validate and authorize a specific payment, only needed when business case requires it. Sending of this code is outside this specification. example: "352673" BodyAmountReservationTransactionForReserve: required: - amountTransaction - paymentId - paymentStatus - paymentCreationDate type: object properties: paymentId: type: string description: Unique Identifier of the payment example: "AK234rfweSBuWGFUEWFGWEVWRV" amountTransaction: $ref: "#/components/schemas/AmountReservationTransactionForReserve" paymentStatus: type: string description: Specifies the payment status (`processing`, `pending_validation`, `denied`, `reserved`, `succeeded`, `cancelled`). example: "processing" paymentCreationDate: type: string format: date-time description: Date time when the payment is created in server database. This is a technical information. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. validationInfo: allOf: - $ref: "#/components/schemas/ValidationInfo" - description: Information to perform otp validation. Only needed when business case requires it. Sending of OTP is outside the scope of this specification. sink: type: string format: uri pattern: ^https:\/\/.+$ description: The address to which events shall be delivered, using the HTTP protocol. example: "https://endpoint.example.com/sink" BodyAmountReservationTransactionForReserveInput: required: - amountTransaction type: object properties: amountTransaction: $ref: "#/components/schemas/AmountReservationTransactionForReserveInput" sink: type: string format: uri pattern: ^https:\/\/.+$ description: The address to which events shall be delivered, using the HTTP protocol. example: "https://endpoint.example.com/sink" sinkCredential: allOf: - description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target. - $ref: "#/components/schemas/SinkCredential" AmountReservationTransactionForReserve: required: - phoneNumber - paymentAmount - referenceCode type: object properties: phoneNumber: type: string description: |- Identifies the mobile account to be charged. A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. pattern: '^\+[1-9][0-9]{4,14}$' example: "+34671999000" clientCorrelator: type: string description: Uniquely identifies this payment request. If there is a communication failure during the payment request, using the same clientCorrelator when retrying the request allows the operator to avoid applying the same charge twice. This field SHOULD be present. Same value as indicated in the request. example: "req-12f2pgh448gh2hvrfrv" paymentAmount: $ref: "#/components/schemas/PaymentAmountForReserve" referenceCode: type: string description: Merchant generated payment reference to uniquely identify the request, for example, in the case of disputes. Same value as the one provided in the request. example: "ref-pay-834tfr2rA3v8r8vr3rv" resourceURL: type: string description: URI of the created resource (same as in the Location header) example: "urn:payments:AK234rfweSBuWGFUEWFGWEVWRV" serverReferenceCode: type: string description: Reference to the charge or refund, provided by the server, and meaningful to the server’s backend system for the purpose of reconciliation. example: "ref-pay-834tfr2rA3v8r8vr3rv-serv" AmountReservationTransactionForReserveInput: type: object required: - paymentAmount - referenceCode properties: phoneNumber: type: string description: |- Identifies the mobile account to be charged. A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. Additional Considerations: - Take a look to section `# Identifying the phone number from the access token` regarding the use of this field. pattern: '^\+[1-9][0-9]{4,14}$' example: "+34671999000" clientCorrelator: type: string description: Uniquely identifies this create payment request. If there is a communication failure during the payment request, using the same clientCorrelator when retrying the request allows the operator to avoid applying the same charge twice. This field SHOULD be present. example: "req-12f2pgh448gh2hvrfrv" paymentAmount: $ref: "#/components/schemas/PaymentAmountForReserve" referenceCode: type: string description: Merchant generated payment reference to uniquely identify the request, for instance, in the case of disputes. example: "ref-pay-834tfr2rA3v8r8vr3rv" PaymentAmountForReserve: type: object required: - chargingInformation properties: chargingInformation: $ref: "#/components/schemas/ChargingInformation" chargingMetaData: $ref: "#/components/schemas/ChargingMetaData" paymentDetails: $ref: "#/components/schemas/PaymentDetails" PaymentDetails: type: array description: Detailed description of the concepts/items considered within a specific payment procedure. minItems: 1 items: $ref: "#/components/schemas/PaymentItem" PaymentItem: type: object required: - id - amount - currency - description properties: id: type: string description: |- Unique payment item identifier. Relevant to uniquely identify an item within a given payment when `paymentDetails` are provided and also to correlate information when a refund regarding this item is performed, by means of using `refundDetails`. example: "3goug3uvu32v3b" amount: type: number format: float multipleOf: 0.001 minimum: 0.001 description: Specific amount to be charged or reserved referred to a specific item. example: 100 currency: type: string description: Currency code in which amount is expressed as defined in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html). example: "EUR" description: type: string description: Description text to be used for information and billing text referred to a specific item. example: "FIFA EA Sports 24" isTaxIncluded: type: boolean default: false description: If true, the `amount` is tax included, if false the `amount` is provided without tax. In both cases, `taxAmount` could be indicated to provide tax amount. taxAmount: type: number format: float multipleOf: 0.001 minimum: 0 description: | The tax amount charged by the merchant. Indicated when the merchant is the one applying taxes. This field also provides an indicator to the downstream billing system. example: 21 ChargingInformation: type: object required: - amount - currency - description properties: amount: type: number format: float multipleOf: 0.001 minimum: 0.001 description: Amount to be charged or reserved. example: 100 currency: type: string description: Currency code in which amount is expressed as defined in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html). example: "EUR" description: type: string description: Description text to be used for information and billing text example: "FIFA EA Sports 24" isTaxIncluded: type: boolean default: false description: If true, the `amount` is tax included, if false the `amount` is provided without tax. In both cases, `taxAmount` could be indicated to provide tax amount. taxAmount: type: number format: float multipleOf: 0.001 minimum: 0 description: | The tax amount charged by the merchant. Indicated when the merchant is the one applying taxes. This field also provides an indicator to the downstream billing system. example: 21 ChargingMetaData: type: object properties: merchantName: type: string description: Indicates the merchant name. Allows aggregators/partners to specify the actual merchant name example: "EA Sports" merchantIdentifier: type: string description: Indicates the merchant identifier. Allows aggregators/partners to specify the actual merchant identifier example: "eas-12345" fee: type: number format: float multipleOf: 0.01 description: Percentage of the amount to be received by the requester example: 10 purchaseCategoryCode: type: string description: A category defining the type of service, product or media being purchased example: "games" channel: type: string description: The channel over which the requester is interacting with the merchant (e.g. WAP, Web, SMS...) example: "web" serviceId: type: string description: The identifier of the partner/merchant service being purchased example: "games-online" productId: type: string description: The product identifier to be combined with the `serviceId` to uniquely identify the product being purchased. For example if the `serviceId` relates to a VOD service, the `productId` can specify the movie rented example: "138235321" ValidationInfo: type: object required: - action properties: action: type: string enum: - open - validate description: Action to be done regarding otp validation. discriminator: propertyName: action mapping: open: "#/components/schemas/Open" validate: "#/components/schemas/Validate" example: action: validate authorizationId: "Fn34o8g239v3wrb3t" Open: allOf: - $ref: "#/components/schemas/ValidationInfo" - type: object description: Information for otp validation by means of browseable URL. required: - validationURL properties: validationURL: type: string description: Backend generated Public URL to perform otp validation. Sending of OTP is outside the scope of this specification. example: "https://my-payment-service.com/validate/358y24t2g4f2397g45" Validate: allOf: - $ref: "#/components/schemas/ValidationInfo" - type: object description: Information for otp validation by means of received otp. required: - authorizationId properties: authorizationId: type: string description: Unique authorization identifier for a given payment to perform otp validation. Sending of OTP is outside the scope of this specification. Validation of this `authorizationId` is performed by means of `validatePayment` endpoint. example: "Fn34o8g239v3wrb3t" CloudEvent: description: The notification format required: - id - source - specversion - type - time properties: id: type: string description: Identifier of this event, that must be unique in the source context. minLength: 1 example: "sd5e-uy52-88t4-za66" source: $ref: "#/components/schemas/Source" type: type: string description: Type of event as defined in each CAMARA API minLength: 25 example: "org.camaraproject.carrier-billing.v0.payment-reserved" specversion: type: string description: Version of the specification to which this event conforms (must be 1.0 if it conforms to cloudevents 1.0.2 version) minLength: 3 example: "1.0" datacontenttype: type: string description: 'media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs' example: "application/json" data: type: object description: Event details payload described in each CAMARA API and referenced by its type time: $ref: "#/components/schemas/DateTime" discriminator: propertyName: "type" mapping: org.camaraproject.carrier-billing.v0.payment-pending-validation: "#/components/schemas/EventPaymentPendingValidation" 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" org.camaraproject.carrier-billing.v0.payment-denied: "#/components/schemas/EventPaymentDenied" Source: type: string format: uri-reference minLength: 1 description: |- Identifies the context in which an event happened - be a non-empty `URI-reference` like: - URI with a DNS authority: * https://github.com/cloudevents * mailto:cncf-wg-serverless@lists.cncf.io - Universally-unique URN with a UUID: * urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 - Application-specific identifier: * /cloudevents/spec/pull/123 * 1-555-123-4567 example: "https://notificationSendServer12.supertelco.com" DateTime: type: string format: date-time description: Timestamp when the occurrence happened. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. example: "2023-11-03T12:27:10Z" EventPaymentPendingValidation: description: Event structure for payment pending validation allOf: - $ref: "#/components/schemas/CloudEvent" - type: object properties: data: $ref: "#/components/schemas/PaymentPendingValidation" 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" EventPaymentDenied: description: Event structure for payment denied allOf: - $ref: "#/components/schemas/CloudEvent" - type: object properties: data: $ref: "#/components/schemas/PaymentDenied" PaymentPendingValidation: allOf: - description: Event detail structure for org.camaraproject.carrier-billing.v0.payment-pending-validation event - $ref: "#/components/schemas/BasicEvent" 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](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. 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" PaymentDenied: allOf: - description: Event detail structure for org.camaraproject.carrier-billing.v0.payment-denied event - $ref: "#/components/schemas/BasicEvent" - type: object properties: denialReason: type: string description: Indicates the business reason for denying the payment. example: "User is blocked due to pending debt" BasicEvent: type: object description: Data type to provide basic payment event information required: - paymentId - status - description properties: paymentId: type: string description: Unique Identifier of the payment example: "AK234rfweSBuWGFUEWFGWEVWRV" status: type: string enum: - succeeded - failed description: |- 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. example: "Payment Notification" ErrorInfo: type: object required: - status - code - message properties: status: type: integer description: HTTP response status code code: type: string description: A human-readable code to describe the error message: type: string description: A human-readable description of what the event represents responses: Generic400: description: Bad Request headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 400 code: enum: - INVALID_ARGUMENT examples: GENERIC_400_INVALID_ARGUMENT: summary: Generic Invalid Argument description: Invalid Argument. Generic Syntax Exception value: status: 400 code: INVALID_ARGUMENT message: Client specified an invalid argument, request body or query param. GetPaymentsInvalid400: description: |- Invalid input. In addition to regular INVALID_ARGUMENT scenario other scenarios may exist: - Inconsistent paymentCreationDate.gte and paymentCreationDate.lte values ("code": "CARRIER_BILLING.INVALID_DATE_RANGE","message": "Client specified an invalid date range"). - Request out of range ("code": "OUT_OF_RANGE","message": "Client specified an invalid range"). - Too many matching records found ("code": "CARRIER_BILLING.TOO_MANY_MATCHING_RECORDS","message": "Too many matching records found. Specify additional/suitable criteria to limit the number of records."). headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 400 code: enum: - INVALID_ARGUMENT - OUT_OF_RANGE - CARRIER_BILLING.INVALID_DATE_RANGE - CARRIER_BILLING.TOO_MANY_MATCHING_RECORDS examples: GENERIC_400_INVALID_ARGUMENT: summary: Generic Invalid Argument description: Invalid Argument. Generic Syntax Exception value: status: 400 code: INVALID_ARGUMENT message: Client specified an invalid argument, request body or query param. GENERIC_400_INVALID_DATE_RANGE: summary: Generic Invalid Date Range description: Inconsistent paymentCreationDate.gte and paymentCreationDate.lte values value: status: 400 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. 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." PaymentInvalid400: description: |- Invalid input. Common INVALID_ARGUMENT scenarios usually are: - 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"). - Invalid sink credential access token ("code": "INVALID_TOKEN","message": "Only bearer token is supported"). - Invalid sink ("code": "INVALID_SINK","message": "sink not valid for the specified protocol"). headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 400 code: enum: - INVALID_ARGUMENT - INVALID_CREDENTIAL - INVALID_TOKEN - INVALID_SINK examples: GENERIC_400_INVALID_ARGUMENT: summary: Generic Invalid Argument description: Invalid Argument. Generic Syntax Exception value: status: 400 code: INVALID_ARGUMENT message: Client specified an invalid argument, request body or query param. GENERIC_400_WRONG_CURRENCY: summary: Generic Wrong Currency description: Currency is unknown or not authorized value: code: INVALID_ARGUMENT status: 400 message: "Currency is unknown or not authorized." GENERIC_400_DUPLICATE_CLIENT_CORRELATOR: summary: Generic Duplicate Client Correlator description: clientCorrelator still exist value: code: INVALID_ARGUMENT status: 400 message: "clientCorrelator already exist on server." GENERIC_400_INVALID_CREDENTIAL: summary: Generic Invalid Credential description: Invalid sink credential value: status: 400 code: "INVALID_CREDENTIAL" message: "Only Access token is supported" GENERIC_400_INVALID_TOKEN: summary: Generic Invalid Token description: Invalid sink credential access token value: status: 400 code: "INVALID_TOKEN" message: "Only bearer token is supported" GENERIC_400_INVALID_SINK: summary: Generic Invalid Sink description: Invalid sink value value: status: 400 code: INVALID_SINK message: "sink not valid for the specified protocol" Payment2StepPrepareInvalid400: description: |- Invalid input. Common INVALID_ARGUMENT scenarios usually are: - 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"). - Invalid sink credential access token ("code": "INVALID_TOKEN","message": "Only bearer token is supported"). - Invalid sink ("code": "INVALID_SINK","message": "sink not valid for the specified protocol"). headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 400 code: enum: - INVALID_ARGUMENT - INVALID_CREDENTIAL - INVALID_TOKEN - INVALID_SINK examples: GENERIC_400_INVALID_ARGUMENT: summary: Generic Invalid Argument description: Invalid Argument. Generic Syntax Exception value: status: 400 code: INVALID_ARGUMENT message: Client specified an invalid argument, request body or query param. GENERIC_400_PAYMENT_ID_REQUIRED: summary: Generic PaymentId required description: paymentId is required value: code: INVALID_ARGUMENT status: 400 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" GENERIC_400_INVALID_TOKEN: summary: Generic Invalid Token description: Invalid sink credential access token value: status: 400 code: "INVALID_TOKEN" message: "Only bearer token is supported" GENERIC_400_INVALID_SINK: summary: Generic Invalid Sink description: Invalid sink value value: status: 400 code: INVALID_SINK message: "sink not valid for the specified protocol" Payment2StepInvalid400: description: |- Invalid input. Common INVALID_ARGUMENT scenarios usually are: - 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" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 400 code: enum: - INVALID_ARGUMENT examples: GENERIC_400_INVALID_ARGUMENT: summary: Generic Invalid Argument description: Invalid Argument. Generic Syntax Exception value: status: 400 code: INVALID_ARGUMENT message: Client specified an invalid argument, request body or query param. 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." 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."). headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 400 code: enum: - INVALID_ARGUMENT - CARRIER_BILLING.INVALID_AUTHORIZATION_ID - CARRIER_BILLING.INVALID_CODE - CARRIER_BILLING.VALIDATION_FAILED examples: GENERIC_400_INVALID_ARGUMENT: summary: Generic Invalid Argument description: Invalid Argument. Generic Syntax Exception value: status: 400 code: INVALID_ARGUMENT message: Client specified an invalid argument, request body or query param. GENERIC_400_AUTHORIZATION_ID_REQUIRED: summary: Generic AuthorizationId Required description: authorizationId is required value: code: INVALID_ARGUMENT status: 400 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." 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." GENERIC_400_INVALID_CODE: summary: Generic Invalid Code description: code is not valid value: code: CARRIER_BILLING.INVALID_CODE status: 400 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." Generic401: description: Unauthorized headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 401 code: enum: - UNAUTHENTICATED examples: GENERIC_401_UNAUTHENTICATED: description: Request cannot be authenticated and a new authentication is required value: status: 401 code: UNAUTHENTICATED message: Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required. Generic403: description: Forbidden headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 403 code: enum: - PERMISSION_DENIED examples: GENERIC_403_PERMISSION_DENIED: description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security value: status: 403 code: PERMISSION_DENIED message: Client does not have sufficient permissions to perform this action. PaymentPermissionDenied403: description: |- Client does not have sufficient permission. In addition to regular PERMISSION_DENIED scenario other scenarios may exist: - Payment denied by business ("code": "CARRIER_BILLING.PAYMENT_DENIED","message": "Payment denied by business."). headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 403 code: enum: - PERMISSION_DENIED - CARRIER_BILLING.PAYMENT_DENIED examples: GENERIC_403_PERMISSION_DENIED: description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security value: status: 403 code: PERMISSION_DENIED message: Client does not have sufficient permissions to perform this action. 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." PaymentConfirmPermissionDenied403: description: |- Client does not have sufficient permission. In addition to regular PERMISSION_DENIED scenario other scenarios may exist: - Payment denied by business ("code": "CARRIER_BILLING.PAYMENT_DENIED","message": "Payment denied by business."). headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 403 code: enum: - PERMISSION_DENIED - CARRIER_BILLING.PAYMENT_DENIED examples: GENERIC_403_PERMISSION_DENIED: description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security value: status: 403 code: PERMISSION_DENIED message: Client does not have sufficient permissions to perform this action. 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." PaymentCancelPermissionDenied403: description: |- Client does not have sufficient permission. headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 403 code: enum: - PERMISSION_DENIED examples: GENERIC_403_PERMISSION_DENIED: description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security value: status: 403 code: PERMISSION_DENIED message: Client does not have sufficient permissions to perform this action. Generic404: description: Resource Not Found headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 404 code: enum: - NOT_FOUND examples: GENERIC_404_NOT_FOUND: summary: Generic Not Found description: Resource is not found value: status: 404 code: NOT_FOUND message: The specified resource is not found. IdentifierNotFound404: description: Phone Number Not Found headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 404 code: enum: - IDENTIFIER_NOT_FOUND examples: GENERIC_404_IDENTIFIER_NOT_FOUND: description: Some identifier cannot be matched to a device. In this API it refers to a phoneNumber. value: status: 404 code: IDENTIFIER_NOT_FOUND message: phoneNumber not found. Identifier2StepNotFound404: description: |- Resource Not Found. In addition to regular NOT_FOUND scenario other scenarios may exist: - Phone Number not found ("code": "IDENTIFIER_NOT_FOUND","message": "phoneNumber not found."). headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 404 code: enum: - NOT_FOUND - IDENTIFIER_NOT_FOUND examples: GENERIC_404_NOT_FOUND: description: Resource is not found value: status: 404 code: NOT_FOUND message: The specified resource is not found. GENERIC_404_IDENTIFIER_NOT_FOUND: description: Some identifier cannot be matched to a device. In this API it refers to a phoneNumber. value: status: 404 code: IDENTIFIER_NOT_FOUND message: phoneNumber not found. Generic409: description: Conflict headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 409 code: enum: - ALREADY_EXISTS examples: GENERIC_409_ALREADY_EXISTS: summary: Generic Already Exists description: Trying to create an existing resource value: status: 409 code: ALREADY_EXISTS message: The resource that a client tried to create already exists. 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: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 409 code: enum: - ALREADY_EXISTS - CARRIER_BILLING.PAYMENT_CONFIRMED - CARRIER_BILLING.PAYMENT_CANCELLED 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. 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." 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." 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: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 409 code: enum: - ALREADY_EXISTS - CARRIER_BILLING.PAYMENT_CONFIRMED - CARRIER_BILLING.PAYMENT_CANCELLED 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. 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." 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." Generic410: description: Gone headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 410 code: enum: - GONE examples: GENERIC_410_GONE: summary: Generic Gone description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available value: status: 410 code: GONE message: Access to the target resource is no longer available. PaymentUnprocessable422: description: |- Client indicates content that is understable by the Server but unable to be processed. Scenarios that may exist: - Service not applicable for the provided identifier ("code": "SERVICE_NOT_APPLICABLE","message": "The service is not available for the provided identifier.") - An identifier is not included in the request and the device or phone number identification cannot be derived from the 3-legged access token ("code": "MISSING_IDENTIFIER","message": "The phone number cannot be identified.") - An explicit identifier is provided when a device or phone number has already been identified from the access token ("code": "UNNECESSARY_IDENTIFIER","message": "The phone number is already identified by the access token.") - 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": "Unauthorized payment request. Accumulated user mobile payments overpass account amount threshold."). headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 422 code: enum: - SERVICE_NOT_APPLICABLE - MISSING_IDENTIFIER - UNNECESSARY_IDENTIFIER - CARRIER_BILLING.UNAUTHORIZED_AMOUNT - CARRIER_BILLING.USER_AMOUNT_THRESHOLD_OVERPASSED examples: GENERIC_422_SERVICE_NOT_APPLICABLE: description: Service not applicable for the provided identifier value: status: 422 code: SERVICE_NOT_APPLICABLE message: The service is not available for the provided identifier. GENERIC_422_MISSING_IDENTIFIER: description: An identifier is not included in the request and the device or phone number identification cannot be derived from the 3-legged access token value: status: 422 code: MISSING_IDENTIFIER message: The phone number cannot be identified. GENERIC_422_UNNECESSARY_IDENTIFIER: description: An explicit identifier is provided when a device or phone number has already been identified from the access token value: status: 422 code: UNNECESSARY_IDENTIFIER message: The phone number is already identified by the access token. GENERIC_422_UNAUTHORIZED_AMOUNT: summary: Generic Unauthorized Amount description: Unauthorized amount requested value: status: 422 code: CARRIER_BILLING.UNAUTHORIZED_AMOUNT 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: "Unauthorized payment request. Accumulated user mobile payments overpass account amount threshold." PaymentSecondStepUnprocessable422: description: |- Client indicates content that is understable by the Server but unable to be processed. Scenarios that may exist: - Service not applicable for the provided identifier ("code": "SERVICE_NOT_APPLICABLE","message": "The service is not available for the provided identifier.") - An identifier is not included in the request and the device or phone number identification cannot be derived from the 3-legged access token ("code": "MISSING_IDENTIFIER","message": "The phone number cannot be identified.") - An explicit identifier is provided when a device or phone number has already been identified from the access token ("code": "UNNECESSARY_IDENTIFIER","message": "The phone number is already identified by the access token.") headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 422 code: enum: - SERVICE_NOT_APPLICABLE - MISSING_IDENTIFIER - UNNECESSARY_IDENTIFIER examples: GENERIC_422_SERVICE_NOT_APPLICABLE: description: Service not applicable for the provided identifier value: status: 422 code: SERVICE_NOT_APPLICABLE message: The service is not available for the provided identifier. GENERIC_422_MISSING_IDENTIFIER: description: An identifier is not included in the request and the device or phone number identification cannot be derived from the 3-legged access token value: status: 422 code: MISSING_IDENTIFIER message: The phone number cannot be identified. GENERIC_422_UNNECESSARY_IDENTIFIER: description: An explicit identifier is provided when a device or phone number has already been identified from the access token value: status: 422 code: UNNECESSARY_IDENTIFIER message: The phone number is already identified by the access token. Generic429: description: Too Many Requests headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: allOf: - $ref: "#/components/schemas/ErrorInfo" - type: object properties: status: enum: - 429 code: enum: - TOO_MANY_REQUESTS examples: GENERIC_429_TOO_MANY_REQUESTS: summary: Generic Too Many Requests description: Access to the API has been temporarily blocked due to rate or spike arrest limits being reached value: status: 429 code: TOO_MANY_REQUESTS message: Rate limit reached. parameters: x-correlator: name: x-correlator in: header description: Correlation id for the different services schema: $ref: "#/components/schemas/XCorrelator" Page: name: page in: query description: Requested index to indicate the start of the resources to be provided in the response schema: type: integer default: 1 PerPage: name: perPage in: query description: Requested number of resources to be provided in response schema: type: integer default: 10 StartPaymentCreationDate: description: Initial `paymentCreationDate` for running the query. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. in: query name: paymentCreationDate.gte required: false schema: format: date-time type: string EndPaymentCreationDate: description: End `paymentCreationDate` for running the query. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. in: query name: paymentCreationDate.lte required: false schema: format: date-time type: string Order: description: Used to return the sorted results in descending (default) or ascending order, based on `paymentCreationDate` property in: query name: order required: false schema: default: desc enum: - desc - asc type: string PaymentStatus: description: List of payment status to be considered for the query in: query name: paymentStatus required: false schema: type: array items: type: string enum: - processing - pending_validation - denied - reserved - succeeded - cancelled MerchantIdentifier: description: Merchant identifier to filter the results in: query name: merchantIdentifier required: false schema: type: string headers: x-correlator: description: Correlation id for the different services schema: $ref: "#/components/schemas/XCorrelator" Content-Last-Key: description: Indicates the index of the last result provided in the response schema: type: integer X-Total-Count: description: Total number of items matching criteria schema: type: integer