openapi: 3.0.3 info: description: |- Service Enabling Payments against OB 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.2, only one-off payments are covered**. Recurrent payments (a.k.a. payment subscriptions) are not covered so far. The API provides several endpoints/operations: - An endpoint to request a 1-STEP Payment, named `createPayment`. - A set of endpoints to request a 2-STEP Payment: - One endpoint to setup the payment reservation, named `preparePayment`. - A couple of endpoints to confirm/cancel such payment reservation, named `confirmPayment` and `cancelPayment` respectively. - A set of endpoints to retrieve information about a list of payments or a specific payment (identified by its specific `paymentId`), named `retrievePayments` and `retrievePayment` respectively. - A callback endpoint where API Server can send notifications about a payment procedure, as defined within `createPayment` and `preparePayment` operations, towards the `webhook.notificationUrl` when provided by API client. The usage of the API is based on Payment resource, which can be created (in 1-STEP or 2-STEP Payment process), confirmed/cancelled (for 2-STEP Payment process), and queried/retrieved (list of payments or a specific payment). Before starting to use the API, the developer needs to know about the below specified details: - **Payment service endpoint**: The URL pointing to the RESTful resource of the payment API. As 1-STEP and 2-STEP processes are managed, 2 separate tags _`One Step Payment`_ and _`Two Step Payment`_ have been defined to explicitly distinguish them in the API specification. A third tag _`Payment`_ is defined for common operations in both processes (query/retrieve list of payments or a specific payment). - **1-STEP & 2-STEP Payment**: - **1-STEP Payment**: The request intent is to charge an amount to the mobile line. When the server receives the request, it will check the user account associated with this line and, if nothing prevents it, the amount is charged and will be either bill in next invoice or removed from current line credit/balance. - **2-STEP Payment**: The first call is to request a payment preparation, which implies an amount reservation. The amount is not charged and the server has to be ready to get a confirmation or a cancellation to perform the payment. Only when the confirmation is done, payment is charged. Depending on business rules of the Telco operator, a `prepared` payment could expire after a defined delay. - **Notification URL**: Developers may provide a callback URL (`webhook.notificationUrl` param) on which status change notifications, regarding the payment, can be received from the Telco Operator. This is an optional parameter. Following diagram shows the API resources operation sequencing: ![PaymentSequence](https://raw.githubusercontent.com/camaraproject/CarrierBillingCheckOut/main/documentation/API_documentation/resources/Carrier_Billing_sequence_diagram.png) Follow picture provides information about the payment state engine (state description & transition): ![Payment State Engine](https://raw.githubusercontent.com/camaraproject/CarrierBillingCheckOut/main/documentation/API_documentation/resources/Carrier_Billing_State_Engine.JPG) State transitions: **1-STEP Payment** If `createPayment` is a **SYNC** process: - Response contains `paymentId` and status=`succeeded`. - In case of any error scenario `paymentId` is not created. If `createPayment` is an **ASYNC** process: - Response contains `paymentId` and status=`processing`. After completion: - When payment is successfully completed then status=`succeeded`. - When payment is not successfully performed then status=`denied`. - 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 status=`reserved`. - **Case B** - `validationInfo` is provided in response. - Response contains `paymentId` and status=`pending_validation`. - In case of any error scenario `paymentId` is not created. If `preparePayment` is an **ASYNC** process: - **Case A** - `validationInfo` is NOT provided in response. - Response contains `paymentId` and status=`processing`. After completion: - When payment preparation is successfully completed then status=`reserved`. - When payment preparation is not successfully performed then status=`denied`. - **Case B** - `validationInfo` is provided in response. - Response contains `paymentId` and status=`processing`. After completion: - When payment preparation is successfully completed then status=`pending_validation`. [1] - When payment preparation is not successfully performed then status=`denied`. - In case of any error scenario `paymentId` is not created. [OPTIONAL] VALIDATE STEP [1] After `validatePayment`, status=`reserved` OR `denied`, depending whether it was successful or not. SECOND STEP After `confirmPayment`, status=`succeeded` OR `denied`, depending whether it was successful or not. After `cancelPayment`, status=`cancelled`. # Further info and support (FAQs will be added in a later version of the documentation) version: 0.2.1 title: Carrier Billing termsOfService: http://swagger.io/terms/ contact: email: project-email@sample.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html externalDocs: description: Product documentation at Camara url: https://github.com/camaraproject/ servers: - url: "{apiRoot}/{basePath}" variables: apiRoot: default: http://localhost:9091 description: API root basePath: default: carrier-billing/v0 description: Base path for the carrier billing API 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#/webhook/notificationUrl}": 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" "500": $ref: "#/components/responses/Generic500" "503": $ref: "#/components/responses/Generic503" "504": $ref: "#/components/responses/Generic504" responses: "201": description: Created headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/PaymentCreated" "400": $ref: "#/components/responses/PaymentInvalid400" "401": $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/PaymentPermissionDenied403" "409": $ref: "#/components/responses/Generic409" "500": $ref: "#/components/responses/Generic500" "503": $ref: "#/components/responses/Generic503" "504": $ref: "#/components/responses/Generic504" get: security: - openId: - carrier-billing: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/TransactionOperationStatus" - $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: 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: 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#/webhook/notificationUrl}": 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" "500": $ref: "#/components/responses/Generic500" "503": $ref: "#/components/responses/Generic503" "504": $ref: "#/components/responses/Generic504" responses: "201": description: Created headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/BodyAmountReservationTransactionForReserve" "400": $ref: "#/components/responses/PaymentInvalid400" "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" "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: 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: 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" 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" "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: 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/Generic403" "404": $ref: "#/components/responses/Generic404" "409": $ref: "#/components/responses/PaymentCancelConflict409" "500": $ref: "#/components/responses/Generic500" "503": $ref: "#/components/responses/Generic503" "504": $ref: "#/components/responses/Generic504" components: securitySchemes: openId: type: openIdConnect openIdConnectUrl: https://example.com/.well-known/openid-configuration notificationsBearerAuth: type: http scheme: bearer bearerFormat: "{$request.body#/webhook/notificationAuthToken}" schemas: CreatePayment: type: object required: - amountTransaction properties: amountTransaction: $ref: "#/components/schemas/AmountTransactionInput" webhook: allOf: - $ref: "#/components/schemas/Webhook" - description: Information to manage payment notifications PaymentCreated: type: object required: - amountTransaction - paymentId - paymentCreationDate properties: paymentId: type: string description: Unique Identifier of the payment example: "AK234rfweSBuWGFUEWFGWEVWRV" amountTransaction: $ref: "#/components/schemas/AmountTransaction" 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). webhook: allOf: - $ref: "#/components/schemas/Webhook" - description: Information to manage payment notifications PaymentArray: description: A list of payment(s) type: array minItems: 0 items: $ref: "#/components/schemas/Payment" Payment: type: object required: - amountTransaction - paymentId - paymentCreationDate properties: paymentId: type: string description: Unique Identifier of the payment example: "AK234rfweSBuWGFUEWFGWEVWRV" amountTransaction: $ref: "#/components/schemas/AmountTransaction" 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). webhook: allOf: - $ref: "#/components/schemas/Webhook" - description: Information to manage payment notifications Webhook: type: object required: - notificationUrl properties: notificationUrl: type: string description: Callback URL to allow asynchronous delivery of payment related events example: "https://myservice.com/payment/events" notificationAuthToken: type: string description: Authentification token for callback endpoint example: "c8974e592c2fa383d4a3960714" AmountTransaction: required: - phoneNumber - paymentAmount - referenceCode - transactionOperationStatus type: object properties: phoneNumber: type: string description: Identifies the mobile account to be charged. Phone number in E.164 format (starting with country code). Optionally prefixed with '+'. 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" transactionOperationStatus: type: string description: Specifies the payment status (`processing`, `pending_validation`, `denied`, `reserved`, `succeeded`, `cancelled`). example: "processing" 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. Phone number in E.164 format (starting with country code). Optionally 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. 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. Phone number in E.164 format (starting with country code). Optionally prefixed with '+'. 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 - paymentCreationDate type: object properties: paymentId: type: string description: Unique Identifier of the payment example: "AK234rfweSBuWGFUEWFGWEVWRV" amountTransaction: $ref: "#/components/schemas/AmountReservationTransactionForReserve" 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. webhook: allOf: - $ref: "#/components/schemas/Webhook" - description: Information to manage payment notifications BodyAmountReservationTransactionForReserveInput: required: - amountTransaction type: object properties: amountTransaction: $ref: "#/components/schemas/AmountReservationTransactionForReserveInput" webhook: allOf: - $ref: "#/components/schemas/Webhook" - description: Information to manage payment notifications AmountReservationTransactionForReserve: required: - paymentAmount - referenceCode - transactionOperationStatus type: object properties: phoneNumber: type: string description: Identifies the mobile account to be charged. Phone number in E.164 format (starting with country code). Optionally prefixed with '+'. 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" transactionOperationStatus: type: string description: Specifies the payment status (`processing`, `pending_validation`, `denied`, `reserved`, `succeeded`, `cancelled`). example: "processing" 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. Phone number in E.164 format (starting with country code). Optionally 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. 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: - amount - currency - description properties: amount: type: number format: float multipleOf: 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 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 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 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: Invalid input headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: code: INVALID_ARGUMENT status: 400 message: "Schema validation failed at ..." 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: Generic400: summary: Invalid Argument value: code: INVALID_ARGUMENT status: 400 message: "Invalid Argument ..." InvalidDateRange: summary: Inconsistent startDate and endDate values value: status: 400 code: CARRIER_BILLING.INVALID_DATE_RANGE message: "Client specified an invalid date range" OutOfRange: summary: Request out of range value: status: 400 code: OUT_OF_RANGE message: "Client specified an invalid range" TooManyMatchingRecords: summary: 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": "Schema validation failed at ..."). - Currency is unknown or not authorized ("code": "INVALID_ARGUMENT","message": "Currency is unknown or not authorized"). - clientCorrelator still exist ("code": "INVALID_ARGUMENT","message": "clientCorrelator already exist on server"). headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" examples: Generic400: summary: Schema validation failed value: code: INVALID_ARGUMENT status: 400 message: "Schema validation failed at ..." WrongCurrency: summary: Currency is unknown or not authorized value: code: INVALID_ARGUMENT status: 400 message: "Currency is unknown or not authorized" DuplicateClientCorrelator: summary: clientCorrelator still exist value: code: INVALID_ARGUMENT status: 400 message: "clientCorrelator already exist on server" Payment2StepInvalid400: description: |- Invalid input. Common INVALID_ARGUMENT scenarios usually are: - Schema validation failed ("code": "INVALID_ARGUMENT","message": "Schema validation failed at ..."). - Phone Number is required ("code": "INVALID_ARGUMENT","message": "Expected property is missing: phoneNumber"). - paymentId is required ("code": "INVALID_ARGUMENT","message": "Expected property is missing: paymentId"). headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" examples: Generic400: summary: Schema validation failed value: code: INVALID_ARGUMENT status: 400 message: "Schema validation failed at ..." phoneNumberRequired: summary: Phone Number is required value: code: INVALID_ARGUMENT status: 400 message: "Expected property is missing: phoneNumber" paymentIdRequired: summary: paymentId is required value: code: INVALID_ARGUMENT status: 400 message: "Expected property is missing: paymentId" ValidatePaymentInvalid400: description: |- Invalid input. 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: Generic400: summary: Schema validation failed value: code: INVALID_ARGUMENT status: 400 message: "Schema validation failed at ..." AuthorizationIdRequired: summary: AuthorizationId is required value: code: INVALID_ARGUMENT status: 400 message: "Expected property is missing: authorizationId" CodeRequired: summary: code is required value: code: INVALID_ARGUMENT status: 400 message: "Expected property is missing: code" InvalidAuthorizationId: summary: code is not valid value: code: CARRIER_BILLING.INVALID_AUTHORIZATION_ID status: 400 message: "Invalid authorizationId" InvalidCode: summary: code is not valid value: code: CARRIER_BILLING.INVALID_CODE status: 400 message: "Invalid code" ValidationFailed: summary: 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" example: code: UNAUTHORIZED status: 401 message: "Authorization failed: ..." Generic403: description: Forbidden headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: code: FORBIDDEN status: 403 message: "Operation not allowed: ..." PaymentPermissionDenied403: description: |- Client does not have sufficient permission. In addition to regular PERMISSION_DENIED scenario other scenarios may exist: - Phone Number is required ("code": "CARRIER_BILLING.PHONE_NUMBER_REQUIRED","message": "Phone Number is required"). - Phone Number provided not matching Access Token context ("code": "CARRIER_BILLING.INVALID_TOKEN_CONTEXT","message": "Phone Number does not match with Access Token context"). - Unauthorized amount requested ("code": "CARRIER_BILLING.UNAUTHORIZED_AMOUNT","message": "Unauthorized amount requested"). - Accumulated threshold amount for the user's mobile account overpassed ("code": "CARRIER_BILLING.USER_AMOUNT_THRESHOLD_OVERPASSED","message": "Unathorized payment request. Accumulated user mobile payments overpass account amount threshold"). - 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: Generic403: summary: Forbidden value: status: 403 code: PERMISSION_DENIED message: "Operation not allowed: ..." PhoneNumberRequired: summary: Phone Number is required value: status: 403 code: CARRIER_BILLING.PHONE_NUMBER_REQUIRED message: "Phone Number not provided and cannot be obtained from Access Token context" PhoneNumberMismatch: summary: Phone Number provided not matching Access Token context value: status: 403 code: CARRIER_BILLING.INVALID_TOKEN_CONTEXT message: "Phone Number does not match with Access Token context" UnauthorizedAmount: summary: Unauthorized amount requested value: status: 403 code: CARRIER_BILLING.UNAUTHORIZED_AMOUNT message: "Unauthorized amount requested" UserMobileAccumulatedThresholdAmountOverpassed: summary: Accumulated threshold amount for the user's mobile account overpassed value: status: 403 code: CARRIER_BILLING.USER_AMOUNT_THRESHOLD_OVERPASSED message: "Unathorized payment request. Accumulated user mobile payments overpass account amount threshold" PaymentDenied: summary: 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: $ref: "#/components/schemas/ErrorInfo" examples: Generic403: summary: Forbidden value: status: 403 code: PERMISSION_DENIED message: "Operation not allowed: ..." PaymentDenied: summary: Payment denied by business value: status: 403 code: CARRIER_BILLING.PAYMENT_DENIED message: "Payment denied by business" PaymentReadPermissionDenied403: description: |- Client does not have sufficient permission. In addition to regular PERMISSION_DENIED scenario other scenarios may exist: - Phone Number cannot be deducted from access token context ("code": "CARRIER_BILLING.INVALID_TOKEN_CONTEXT","message": "User phone number cannot be deducted from access token context"). headers: x-correlator: $ref: '#/components/headers/x-correlator' content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" examples: Generic403: summary: Forbidden value: status: 403 code: PERMISSION_DENIED message: "Operation not allowed: ..." InvalidTokenContext: summary: Phone Number cannot be deducted from access token context value: status: 403 code: CARRIER_BILLING.INVALID_TOKEN_CONTEXT message: "User phone number cannot be deducted from access token context" Generic404: description: Resource Not Found headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: code: NOT_FOUND status: 404 message: "The specified resource is not found" Generic409: description: Conflict headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: status: 409 code: ALREADY_EXISTS message: "A specified resource duplicate entry found" PaymentConfirmConflict409: description: |- Conflict. In addition of regular ALREADY_EXISTS scenario other scenarios may exist: - paymentId is already confirmed ("code": "CARRIER_BILLING.PAYMENT_CONFIRMED","message": "Payment has been confirmed"). - paymentId is already cancelled ("code": "CARRIER_BILLING.PAYMENT_CANCELLED","message": "Payment has been cancelled"). headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" examples: Generic409: summary: Conflict value: code: ALREADY_EXISTS status: 409 message: "Payment confirmation in progress" AlreadyConfirmed: summary: paymentId is already confirmed value: code: CARRIER_BILLING.PAYMENT_CONFIRMED status: 409 message: "Payment has been confirmed" AlreadyCancelled: summary: paymentId is already cancelled value: code: CARRIER_BILLING.PAYMENT_CANCELLED status: 409 message: "Payment has been cancelled" PaymentCancelConflict409: description: |- Conflict. In addition of regular ALREADY_EXISTS scenario other scenarios may exist: - paymentId is already confirmed ("code": "CARRIER_BILLING.PAYMENT_CONFIRMED","message": "Payment has been confirmed"). - paymentId is already cancelled ("code": "CARRIER_BILLING.PAYMENT_CANCELLED","message": "Payment has been cancelled"). headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" examples: Generic409: summary: Conflict value: code: ALREADY_EXISTS status: 409 message: "Payment cancellation in progress" AlreadyConfirmed: summary: paymentId is already confirmed value: code: CARRIER_BILLING.PAYMENT_CONFIRMED status: 409 message: "Payment has been confirmed" AlreadyCancelled: summary: paymentId is already cancelled value: code: CARRIER_BILLING.PAYMENT_CANCELLED status: 409 message: "Payment has been cancelled" Generic500: description: Server error headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: code: SERVER_ERROR status: 500 message: "Server Error" Generic503: description: Service unavailable headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: code: SERVICE_UNAVAILABLE status: 503 message: "Service unavailable" Generic504: description: Request timeout exceeded headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: code: REQUEST_TIMEOUT_EXCEEDED status: 504 message: "Request timeout exceeded" parameters: x-correlator: name: x-correlator in: header description: Correlation id for the different services schema: type: string Page: name: page in: query description: Requested index to indicate the start of the resources to be provided in the response schema: type: integer default: 1 PerPage: name: perPage in: query description: Requested number of resources to be provided in response schema: type: integer default: 10 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 TransactionOperationStatus: description: List of payment status to be considered for the query in: query name: transactionOperationStatus 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