openapi: 3.0.3 info: description: | Prepaid recharge service can be used to recharge/topup Omantel Prepaid (Hayyak) Customers. # Introduction The API is used by service providers to collect recharge amount from the customer (Cash or credit card) and send recharge request to Omantel for adding specified amount in customer's main monetory account balance. # API Functionality This API allows to clients to recharge Omantel Prepaid (Hayyak) customers, as well as to check eligibility. The API provides several endpoints/operations: - An endpoint to initiate the recharge transaction. - A set of endpoints to retrieve recharge details, history of recharges. - An endpoint to check customer's eligibility for recharge. version: 1.0.0 title: Prepaid Recharge service servers: - url: https://apigw.omantel.om variables: apiRoot: default: https://apigw.omantel.om description: API root basePath: default: /prepaid/v1 description: Base path for the bill payment API tags: - name: Recharges description: Operations to manage recharge procedure - name: Recharge Inquiry description: Operations to query recharges paths: /prepaid/v1/recharges: post: security: - oAuth2ClientCredentials: [] tags: - Recharges summary: Recharge Prepaid Customer operationId: recharge description: Add specified amount to the main monetory account of the prepaid customer. requestBody: description: Recharge transaction required: true content: application/json: schema: $ref: "#/components/schemas/CreateRecharge" examples: RechargeByCash: summary: Prepaid recharge by cash value: rechargeTransaction: clientCorrelatorId: 'CREF1234567890' referenceCode: 'ReceiptNo12345' mobileNumber: '9689250xxxx' rechargeInfo: amount: 25.00 currency: 'OMR' description: 'Recharge of 25 Omani Riyals' rechargeMetaData: merchantName: 'Infoline' channel: 'MobileApp' paymentMethod: 'cash' RechargeByCC: summary: Recharge by credit card value: rechargeTransaction: clientCorrelatorId: 'CREF1234567890' referenceCode: 'ReceiptNo12345' mobileNumber: '925069XX' rechargeInfo: amount: 25.00 currency: 'OMR' description: 'Recharge of 25 Omani Riyals' rechargeMetaData: merchantName: 'Infoline' channel: 'MobileApp' paymentMethod: 'credit_card' creditCardDetails: authorizationCode: '12345' callbacks: eventNotifications: "{$request.body#/webhook.notificationUrl}/eventNotifications": $ref: "#/paths/~1eventNotifications" responses: 201: description: Created content: application/json: schema: $ref: "#/components/schemas/RechargeCreated" 400: description: Invalid input 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: currency" DuplicateClientCorrelator: summary: clientCorrelator still exist value: code: INVALID_ARGUMENT status: 400 message: "clientCorrelator already exist on server" 401: $ref: "#/components/responses/Generic401" 403: description: Forbidden content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" examples: Generic403: summary: Forbidden value: status: 403 code: PERMISSION_DENIED message: "Operation not allowed: ..." mobileNumberRequired: summary: Phone Number not provided and cannot be obtained from Authorization context value: status: 403 code: CARRIER_BILLING.PHONE_NUMBER_REQUIRED message: "Phone Number is required" mobileNumberMismatch: summary: Phone Number provided not matching Authorization context value: status: 403 code: CARRIER_BILLING.INVALID_TOKEN_CONTEXT message: "Phone Number does not match with Authorization 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" 409: $ref: "#/components/responses/Generic409" 500: $ref: "#/components/responses/Generic500" 503: $ref: "#/components/responses/Generic503" 504: $ref: "#/components/responses/Generic504" get: security: - oAuth2ClientCredentials: [] tags: - Recharge Inquiry summary: Get a list of recharges posted to this service operationId: retrieveRecharges description: Retrieve a list of recharges posted and their details based on some filtering criteria. parameters: - $ref: "#/components/parameters/clientCorrelatorId" - $ref: "#/components/parameters/fromDate" - $ref: "#/components/parameters/toDate" - $ref: "#/components/parameters/Page" - $ref: "#/components/parameters/PerPage" - $ref: "#/components/parameters/Seek" responses: 200: description: OK headers: 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/RechargeArray" 400: description: Invalid input content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" examples: OutOfRange: summary: Request out of range value: status: 400 code: OUT_OF_RANGE message: "Client specified an invalid range" 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" /prepaid/v1/recharges/{rechargeId}: get: security: - oAuth2ClientCredentials: [] tags: - Recharge Inquiry summary: Get recharge details for the specified recharge ID operationId: retrieveRechargeDetail description: Retrieve recharge details for the specified recharge ID. parameters: - name: rechargeId in: path description: Recharge identifier that was obtained from the recharge request (Omantel generated `rechargeId`) required: true schema: type: string responses: 200: description: OK content: application/json: schema: $ref: "#/components/schemas/Recharge" 401: $ref: "#/components/responses/Generic401" 403: $ref: "#/components/responses/Generic403" 404: $ref: "#/components/responses/Generic404" 500: $ref: "#/components/responses/Generic500" 503: $ref: "#/components/responses/Generic503" 504: $ref: "#/components/responses/Generic504" /eventNotifications: post: tags: - Recharge Notifications summary: Recharge notifications operationId: rechargeNotification description: | Important: this endpoint is to be exposed by the API client, accepting requests in the defined format. The Omantel will call this endpoint whenever any recharge related event occurs. requestBody: description: Creates a new carrier recharge notification content: application/json: schema: $ref: "#/components/schemas/EventNotification" required: true responses: "204": description: Successful notification "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" components: schemas: CreateRecharge: type: object required: - rechargeTransaction properties: rechargeTransaction: $ref: "#/components/schemas/RechargeTransaction" webhook: $ref: "#/components/schemas/Webhook" RechargeCreated: type: object required: - rechargeTransaction - rechargeId properties: rechargeId: type: string description: | Unique Identifier of the recharge created in Omantel Charging System. It can be used to query status of the transaction transactionOperationStatus: type: string description: Specifies the payment status (`processing`, `denied`, `succeeded`, `failed`). rechargeTransaction: $ref: "#/components/schemas/RechargeTransaction" rechargeCreationDate: type: string format: date-time description: Date time, in ISO-8601 extended local date format, when the recharge is created in server database. This is a technical information. Time-offset from UTC may be used to match local OB time. rechargeDate: type: string format: date-time description: Date time, in ISO-8601 extended local date format, when the recharge is effectively performed. This is a business information. Time-offset from UTC may be used to match local OB time. webhook: $ref: "#/components/schemas/Webhook" Recharge: type: object required: - rechargeTransaction - rechargeId properties: rechargeId: type: string description: Unique Identifier of the payment transactionOperationStatus: type: string description: Specifies the payment status (`processing`, `denied`, `succeeded`, `failed`). rechargeTransaction: $ref: "#/components/schemas/RechargeTransaction" rechargeCreationDate: type: string format: date-time description: Date time, in ISO-8601 extended local date format, when the payment is created in server database. This is a technical information. Time-offset from UTC may be used to match local OB time. rechargeDate: type: string format: date-time description: Date time, in ISO-8601 extended local date format, when the payment is effectively performed. This is a business information. Time-offset from UTC may be used to match local OB time. webhook: $ref: "#/components/schemas/Webhook" Webhook: type: object required: - notificationUrl properties: notificationUrl: type: string description: Callback URL to allow asynchronous delivery of payment related events notificationAuthToken: type: string example: "c8974e592c2fa383d4a3960714" description: Authentification token for callback endpoint RechargeTransaction: type: object required: - clientCorrelatorId - mobileNumber - referenceCode properties: clientCorrelatorId: type: string description: | Uniquely identifies this recharge request. If there is a communication failure during the recharge request, using the same `clientCorrelatorId` when retrying the request allows Omantel to avoid applying the recharge twice. This field SHOULD be present to avoid duplicate recharges. referenceCode: type: string description: Merchant generated recharge reference to uniquely identify the request, for instance, in the case of disputes. mobileNumber: type: string description: | Phone number of the customer. It must be a prepaid (Hayyak) active mobile number. example: "92xxxxxx" rechargeInfo: $ref: "#/components/schemas/RechargeInfo" RechargeInfo: type: object required: - rechargeInformation properties: rechargeInformation: $ref: "#/components/schemas/RechargeInformation" rechargeMetaData: $ref: "#/components/schemas/RechargeMetaData" amountDetails: $ref: "#/components/schemas/AmountDetails" mobileNumber: type: object properties: mobileNumber: type: string description: Identifies the mobile account to be recharged. Phone number in E.164 format (starting with country code). Optionally prefixed with '+'. AmountDetails: type: array description: Detailed description of the concepts/items considered within a specific recharge procedure. minItems: 1 items: $ref: "#/components/schemas/RechargeItem" RechargeItem: type: object required: - amount - currency - description properties: amount: type: number format: float description: Specific amount to be charged or reserved referred to a specific item. 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). description: type: string description: Description text to be used for information and billing text referred to a specific item. isVatIncluded: type: boolean default: false description: If true, the `amount` is VAT included, if false the `amount` is provided without VAT. In both cases, `vatAmount` could be indicated to provide VAT amount. vatAmount: type: number format: float 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. 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 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. RechargeInformation: type: object required: - amount - currency - description properties: amount: type: number format: float description: Amount to be recharged. 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). description: type: string description: Description text to be used for information and billing text isVatIncluded: type: boolean default: false description: If true, the `amount` is VAT included, if false the `amount` is provided without VAT. In both cases, `vatAmount` could be indicated to provide VAT amount. vatAmount: type: number format: float 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. 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 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. RechargeMetaData: type: object properties: merchantName: type: string description: Indicates the merchant name. Allows aggregators/partners to specify the actual merchant name merchantIdentifier: type: string description: Indicates the merchant identifier. Allows aggregators/partners to specify the actual merchant identifier fee: type: number format: float description: Percentage of the amount to be received by the requester currency: type: string description: Currency code in which fee is expressed as defined in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html). purchaseCategoryCode: type: string description: A category defining the type of service, product or media being purchased channel: type: string description: The channel over which the requester is interacting with the merchant (e.g. WAP, Web, SMS...) serviceId: type: string description: The identifier of the partner/merchant service being purchased 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 invoiceNumber: type: string description: Invoice Number paymentMethod: $ref: '#/components/schemas/PaymentMethod' creditCardDetails: $ref: '#/components/schemas/CreditCardDetails' PaymentMethod: type: string description: The method used by the customer to pay the bill. enum: - cash - credit_card - debit_card example: credit_card CreditCardDetails: type: object properties: cardNumber: type: string description: | The credit/debit card number. If agreed with Omantel to share dummy card details then use `1234567890123456` as card number. example: '1234567890123456' cardHolderName: type: string description: The name of the cardholder. example: 'John Doe' cardType: type: string description: The type of the credit/debit card. enum: - Visa - MasterCard - AmericanExpress - Discover example: Visa expiryMonth: type: integer format: int32 description: The expiry month of the card. example: 12 expiryYear: type: integer format: int32 description: The expiry year of the card. example: 2023 cvv: type: string description: The CVV of the card. example: '123' authorizationCode: type: string description: The authorization code for the transaction. If customer has paid by Credit Card, please specify authorization code . example: 'ABC1234' required: - authorizationCode ErrorInfo: type: object required: - code - message - status properties: code: type: string description: Code given to this error status: type: string description: HTTP response status code message: type: string description: Detailed error description EventNotification: type: object description: Generic data type for event notification structure required: - event properties: eventSubscriptionid: type: string description: subscription identifier event: $ref: "#/components/schemas/Event" Event: type: object description: Generic data type for event structure required: - eventType - eventTime - eventDetail properties: eventid: type: string format: uuid description: Identifier of the event from the server where the event was reported eventType: type: string description: | Type of event. Different types considered so far: - `PAYMENT_COMPLETED`: Notification indication about payment completion. - `PAYMENT_FAILED`: Notification about payment failure. eventTime: type: string format: date-time description: Date time, in ISO-8601 extended local date format, when the event occurred. Time-offset from UTC may be used to match local OB time. eventDetail: $ref: "#/components/schemas/EventDetail" EventDetail: type: object description: Data type to provide event detail information properties: rechargeId: type: string description: Unique Identifier of the payment clientCorrelatorId: type: string description: Client generated Unique Identifier of the payment status: type: string enum: - succeeded - failed description: | Status of the procedure, according to `eventType` param. 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. paymentDate: type: string description: Date when the payment is effectively performed, both in 1-step and 2-step scenarios. This is a business information. format: date-time required: - rechargeId - status - description RechargeArray: description: A list of payment(s) type: array minItems: 0 items: $ref: "#/components/schemas/Recharge" Customer: type: object description: Customer details of the specified input properties: customerName: type: string description: Customer Name customerStatus: type: string description: | Current status of the contract. It could be any one of the following:ACTIVE, PENDING, NEW. example: ACTIVE customerType: type: number description: Customer type. Possible values are 9 - GSM POSTPAID, 11 - GSM FAX, 12 - GSM DATA, 14 - GSM PREPAID, 200/203 – PSTN customerAccountNumber: type: string description: Customer Account Number can be used to pay bils acctCategory: type: string description: Account category of the contract. Example - Business – Large, Business – Medium, Business – Small, Government, Residential, Service, Special Services, Roaming Test Cards, Residential Staff, Test Numbers, Network Support collectionIndicator: type: string description: Indicate whether the contract is in collections or not. ACCOUNT IN COLLECTIONS, ACCOUNT NOT IN COLLECTIONS custAddr1: type: string description: Customer address 1 custAddr2: type: string description: Customer address 2 custAddr3: type: string description: Customer address 3 totalDues: type: number description: Total due amount (in Omani Riyals) associated with the account example: 25.0 responses: Generic400: description: Invalid input content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: code: INVALID_ARGUMENT status: 400 message: "Schema validation failed at ..." Generic401: description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: code: UNAUTHORIZED status: 401 message: "Authorization failed: ..." Generic403: description: Forbidden content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: code: FORBIDDEN status: 403 message: "Operation not allowed: ..." Generic404: description: Resource Not Found content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: code: NOT_FOUND status: 404 message: "The specified resource is not found" Generic409: description: Conflict content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: status: 409 code: ALREADY_EXISTS message: "A specified resource duplicate entry found" Generic500: description: Server error content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: code: SERVER_ERROR status: 500 message: "Server Error" Generic503: description: Service unavailable content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: code: SERVICE_UNAVAILABLE status: 503 message: "Service unavailable" Generic504: description: Request timeout exceeded content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: code: REQUEST_TIMEOUT_EXCEEDED status: 504 message: "Request timeout exceeded" parameters: mobileNumber: name: mobileNumber in: query description: Phone number of the customer example: "92xxxxxx" schema: type: string fixedlineNumber: name: fixedlineNumber in: query description: Fixed line number of the customer example: "IA123456" schema: type: string internetAccount: name: internetAccount in: query description: Internet Account of the customer example: "24xxxxxx" schema: type: string customerAccountNumber: name: customerAccountNumber in: query description: Account number of the customer example: "12345678" schema: type: string clientCorrelatorId: name: clientCorrelatorId in: query schema: type: string description: | Client call can specify it to find individual transaction by its own unque ID. Service will return matching record only. If `clientCorrelatorId` is specified in the request, then service will consider only `clientCorrelatorId` and return matching transaction only, and will ignore all other parameters. fromDate: name: fromDate in: query description: Results should be taken from this transaction date example: "2023-01-15" schema: type: string format: date toDate: name: toDate in: query description: Results should be taken up-to this transaction date example: "2023-01-31" schema: type: string format: date Page: name: page in: query description: Requested index to indicate the start of the resources to be provided in the response schema: type: integer PerPage: name: perPage in: query description: Requested number of resources to be provided in response schema: type: integer Seek: name: seek in: query description: Index of last result read to create the next/previous number of results. This query parameter is used for pagination in systems with more than 1000 records. `seek` parameter offers finer control than `page` and could be used one or another as an alternative. If both are used in combination (not recommended) `seek` would mark the index starting from the page number specified by `page` and `perPage` [index = (page * perPage) + seek]. schema: type: integer headers: 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: oAuth2ClientCredentials: type: oauth2 flows: clientCredentials: tokenUrl: https://apigw.omantel.om/oauth2/accesstoken scopes: {}