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.3, only one-off payments are covered**. Recurrent payments (a.k.a. payment subscriptions) are not covered so far. The API provides several endpoints/operations: - An endpoint to request a 1-STEP Payment, named `createPayment`. - 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/main/documentation/API_documentation/resources/Carrier_Billing_sequence_diagram.png) Follow picture provides information about the payment state engine (state description & transition): ![Payment State Engine](https://raw.githubusercontent.com/camaraproject/CarrierBillingCheckOut/main/documentation/API_documentation/resources/Carrier_Billing_State_Engine.JPG) State transitions: **1-STEP Payment** If `createPayment` is a **SYNC** process: - Response contains `paymentId` and 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 on how a client requests an access token. Please refer to Identify and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the Profile. Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation. It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control. # Further info and support (FAQs will be added in a later version of the documentation) version: 0.3.1 title: Global System for Mobile Communications GSMA Camara Project 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/CarrierBillingCheckOut x-camara-commonalities: 0.4.0 servers: - url: "{apiRoot}/carrier-billing/v0.3" 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: Payment description: Operations to obtain information about payments - name: Two Step Payment description: Operations to manage Two Step Payment procedure paths: /payments: post: security: - openId: - carrier-billing:payments:create tags: - One Step Payment summary: Global System for Mobile Communications 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" "500": $ref: "#/components/responses/Generic500" "503": $ref: "#/components/responses/Generic503" 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" "409": $ref: "#/components/responses/Generic409" "422": $ref: "#/components/responses/PaymentUnprocessable422" "500": $ref: "#/components/responses/Generic500" "503": $ref: "#/components/responses/Generic503" "504": $ref: "#/components/responses/Generic504" get: security: - openId: - carrier-billing:payments:read tags: - Payment summary: Global System for Mobile Communications 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/PaymentReadPermissionDenied403" "500": $ref: "#/components/responses/Generic500" "503": $ref: "#/components/responses/Generic503" "504": $ref: "#/components/responses/Generic504" /payments/{paymentId}: get: security: - openId: - carrier-billing:payments:read tags: - Payment summary: Global System for Mobile Communications 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" "401": $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/PaymentReadPermissionDenied403" "404": $ref: "#/components/responses/Generic404" "500": $ref: "#/components/responses/Generic500" "503": $ref: "#/components/responses/Generic503" "504": $ref: "#/components/responses/Generic504" /payments/prepare: post: security: - openId: - carrier-billing:payments:create tags: - Two Step Payment summary: Global System for Mobile Communications 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" "500": $ref: "#/components/responses/Generic500" "503": $ref: "#/components/responses/Generic503" 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" "409": description: Conflict headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: code: ALREADY_EXISTS status: 409 message: "Another session is created for the same UE" "422": $ref: "#/components/responses/PaymentUnprocessable422" "500": $ref: "#/components/responses/Generic500" "503": $ref: "#/components/responses/Generic503" "504": $ref: "#/components/responses/Generic504" /payments/{paymentId}/validate: post: security: - openId: - carrier-billing:payments:write tags: - Two Step Payment summary: Global System for Mobile Communications 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" "409": description: Conflict headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" examples: Generic409: summary: Conflict value: code: ALREADY_EXISTS status: 409 message: "Payment already validated" "500": $ref: "#/components/responses/Generic500" "503": $ref: "#/components/responses/Generic503" "504": $ref: "#/components/responses/Generic504" /payments/{paymentId}/confirm: post: security: - openId: - carrier-billing:payments:write tags: - Two Step Payment summary: Global System for Mobile Communications 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/Generic404" "409": $ref: "#/components/responses/PaymentConfirmConflict409" "422": $ref: "#/components/responses/PaymentSecondStepUnprocessable422" "500": $ref: "#/components/responses/Generic500" "503": $ref: "#/components/responses/Generic503" "504": $ref: "#/components/responses/Generic504" /payments/{paymentId}/cancel: post: security: - openId: - carrier-billing:payments:write tags: - Two Step Payment summary: Global System for Mobile Communications 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/Generic404" "409": $ref: "#/components/responses/PaymentCancelConflict409" "422": $ref: "#/components/responses/PaymentSecondStepUnprocessable422" "500": $ref: "#/components/responses/Generic500" "503": $ref: "#/components/responses/Generic503" "504": $ref: "#/components/responses/Generic504" components: securitySchemes: openId: type: openIdConnect openIdConnectUrl: https://example.com/.well-known/openid-configuration notificationsBearerAuth: type: http scheme: bearer bearerFormat: "{$request.body#/sinkCredential.credentialType}" schemas: CreatePayment: type: object required: - amountTransaction properties: amountTransaction: $ref: "#/components/schemas/AmountTransactionInput" sink: type: string format: url 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 and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). 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 and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). sink: type: string format: url 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" 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 and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). 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 and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). sink: type: string format: url 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" 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 instant at which the token shall be considered expired. accessTokenType: description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). type: string enum: - bearer required: - accessToken - accessTokenExpiresUtc - accessTokenType RefreshTokenCredential: type: object description: An access token credential with a refresh token. allOf: - $ref: "#/components/schemas/SinkCredential" - type: object properties: accessToken: description: REQUIRED. An access token is a previously acquired token granting access to the target resource. type: string accessTokenExpiresUtc: type: string format: date-time description: REQUIRED. An absolute UTC instant at which the token shall be considered expired. accessTokenType: description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). type: string enum: - bearer refreshToken: description: REQUIRED. An refresh token credential used to acquire access tokens. type: string refreshTokenEndpoint: type: string format: uri description: REQUIRED. A URL at which the refresh token can be traded for an access token. required: - accessToken - accessTokenExpiresUtc - accessTokenType - refreshToken - refreshTokenEndpoint AmountTransaction: required: - phoneNumber - 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: - When phoneNumber is not indicated, it can be inferred from authorization context (i.e. token), otherwise `HTTP 403` will be answered. - When phoneNumber is indicated, authorization context will be consistent, otherwise `HTTP 403` will be answered. pattern: '^\+[1-9][0-9]{4,14}$' example: "+34671999000" clientCorrelator: type: string 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: - When phoneNumber is not indicated, it can be inferred from authorization context (i.e. token), otherwise `HTTP 403` will be answered. - When phoneNumber is indicated, authorization context will be consistent, otherwise `HTTP 403` will be answered. pattern: '^\+[1-9][0-9]{4,14}$' example: "+34671999000" ValidatePayment: type: object 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 and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). 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: url 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" BodyAmountReservationTransactionForReserveInput: required: - amountTransaction type: object properties: amountTransaction: $ref: "#/components/schemas/AmountReservationTransactionForReserveInput" sink: type: string format: url 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: - When phoneNumber is not indicated, it can be inferred from authorization context (i.e. token), otherwise `HTTP 403` will be answered. - When phoneNumber is indicated, authorization context will be consistent, otherwise `HTTP 403` will be answered. pattern: '^\+[1-9][0-9]{4,14}$' example: "+34671999000" clientCorrelator: type: string 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. Must adhere to RFC 3339. 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 and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). format: date-time example: "2023-11-03T12:27:08.312Z" PaymentCancelled: allOf: - description: Event detail structure for org.camaraproject.carrier-billing.v0.payment-cancelled event - $ref: "#/components/schemas/BasicEvent" 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: - code - message - status properties: code: type: string description: Code given to this error status: type: integer description: HTTP response status code message: type: string description: Detailed error description responses: Generic400: description: Bad Request headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" 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."). headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" 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 startDate and endDate 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"). headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" 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" 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"). headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" 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" 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: $ref: "#/components/schemas/ErrorInfo" 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: $ref: "#/components/schemas/ErrorInfo" 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: $ref: "#/components/schemas/ErrorInfo" 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: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" 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 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" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" 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_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 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." 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 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" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" 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_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 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." 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 is not consistent with access token."). headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" 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_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 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."). headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" 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_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." Generic404: description: Resource Not Found headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" 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: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" 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: $ref: "#/components/schemas/ErrorInfo" 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: $ref: "#/components/schemas/ErrorInfo" 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: $ref: "#/components/schemas/ErrorInfo" 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."). headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" examples: 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 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." 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." PaymentSecondStepUnprocessable422: description: |- Client indicates content that is understable by the Server but unable to be processed. Scenarios that may exist: - Phone Number is required ("code": "CARRIER_BILLING.PHONE_NUMBER_REQUIRED","message": "Phone Number is required"). headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" examples: 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 is required." Generic429: description: Too Many Requests headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" 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: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" 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: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" 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: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" 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 in: header description: Correlation id for the different services schema: type: string Page: name: page in: query description: Requested index to indicate the start of the resources to be provided in the response schema: type: integer default: 1 PerPage: name: perPage in: query description: Requested number of resources to be provided in response schema: type: integer default: 10 StartPaymentCreationDate: description: Initial `paymentCreationDate` for running the query. It must follow RFC 3339 and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z) in: query name: paymentCreationDate.gte required: false schema: format: date-time type: string EndPaymentCreationDate: description: End `paymentCreationDate` for running the query. It must follow RFC 3339 and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z) in: query name: 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: type: string Content-Last-Key: description: Indicates the index of the last result provided in the response schema: type: integer X-Total-Count: description: Total number of items matching criteria schema: type: integer