openapi: 3.0.3 info: title: Global System for Mobile Communications GSMA Camara Project Endpoint Discovery Application Payment API version: 0.1.0-wip description: The Application Discovery API extends beyond the capabilities of the Simple Edge Discovery API by not only locating the nearest Edge Cloud Zone but also directly linking to the application endpoints within those Edge Cloud Zones. contact: email: sp-edc@lists.camaraproject.org license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: '{apiRoot}/{basePath}' variables: apiRoot: default: https://localhost:443 description: API root. basePath: default: application-endpoint-discovery/vwip description: Base path for the Application Endpoint Discovery. tags: - name: Payment description: Operations to obtain information about payments paths: /payments: 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' components: responses: 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. 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. PaymentReadPermissionDenied403: description: "Client does not have sufficient permission.\nIn addition to regular PERMISSION_DENIED scenario other scenarios may exist:\n - 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. GetPaymentsInvalid400: description: "Invalid input. In addition to regular INVALID_ARGUMENT scenario other scenarios may exist:\n - Inconsistent startDate and endDate values (\"code\": \"CARRIER_BILLING.INVALID_DATE_RANGE\",\"message\": \"Client specified an invalid date range\").\n - Request out of range (\"code\": \"OUT_OF_RANGE\",\"message\": \"Client specified an invalid range\").\n - 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. 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. 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. 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. parameters: 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 MerchantIdentifier: description: Merchant identifier to filter the results in: query name: merchantIdentifier required: false schema: type: string 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 x-correlator: name: x-correlator in: header description: Correlation id for the different services schema: 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 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 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 schemas: 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 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' 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' 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 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 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 PaymentDetails: type: array description: Detailed description of the concepts/items considered within a specific payment procedure. minItems: 1 items: $ref: '#/components/schemas/PaymentItem' PaymentAmountForCharge: type: object required: - chargingInformation properties: chargingInformation: $ref: '#/components/schemas/ChargingInformation' chargingMetaData: $ref: '#/components/schemas/ChargingMetaData' paymentDetails: $ref: '#/components/schemas/PaymentDetails' 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 securitySchemes: openId: description: OpenID Provider Configuration Information. type: openIdConnect openIdConnectUrl: .well-known/openid-configuration externalDocs: description: Product documentation at CAMARA. url: https://github.com/camaraproject/EdgeCloud