swagger: '2.0' info: version: 1.0.0 title: eGov Payment Gateway Service. description: > This module acts as a liaison between eGov apps and external payment gateways. It facilitates payments, refunds and look up of transactions' status. contact: name: Egovernments Foundation email: contact@egovernments.org schemes: - https basePath: /egov-pg-service x-common-path: >- https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-0-0.yml paths: ######################################### /payments/v1/_search: post: summary: Retrieves the current status of a payment description: | Returns the current status of a payment in our systems; this does not guarantee live payment gateway status. parameters: - $ref: >- https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-0-0.yml#/parameters/requestInfo - $ref: >- https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-0-0.yml#/parameters/tenantId - name: txnId in: query description: >- Transaction id generated by the service during creation. required: false type: string - name: billId in: query description: Unique module based ID for which the transaction is being initiated, if billId is used, module should be included. required: false type: string format: varchar - name: user_uuid in: query description: User ID of the user as registered in user service, for whom the transaction was carried out. required: false type: string format: varchar - name: module in: query required: false description: Module name to which the billId belongs to. type: string - name: moduleId in: query required: false description: Unique identifier in the module for which the transaction is being initiated type: string - name: receipt in: query required: false description: Receipt ID generated for this payment type: string - name: txnStatus in: query required: false description: Current status of the transaction type: string responses: '200': description: Successful response schema: $ref: '#/definitions/TransactionResponse' '400': description: Invalid input. schema: $ref: >- https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-0-0.yml#/definitions/ErrorRes tags: - Payment ######################################### /payments/v1/_create: post: summary: Initiates a new payment transaction. description: Initiates a new payment transaction, on successful validation, a redirect is issued to the payment gateway. parameters: - name: TransactionRequest in: "body" description: Details of the payment and RequestInfo meta data. required: true schema: $ref: '#/definitions/TransactionRequest' responses: '302': description: Payment Initiated successfully, gateway redirection triggered. '400': description: Payment initiation failed. schema: $ref: >- https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-0-0.yml#/definitions/ErrorRes tags: - Payment ######################################### /payments/v1/_update: post: summary: Update an existing payment. description: Updates an existing payment transaction, to be used only by payment gateways to update status of payments. Verifies the authenticity of the request with the payment gateway. Forward all query params received from payment gateway parameters: - name: RequestInfo in: "body" description: Details of the payment response obtained from the payment gateway. schema: $ref: '#/definitions/RequestInfoWrapper' responses: '200': description: Payment Status transaction updated successfully schema: $ref: '#/definitions/TransactionResponse' '400': description: Payment status update failed schema: $ref: >- https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-0-0.yml#/definitions/ErrorRes tags: - Payment ######################################### definitions: Transaction: type: object description: Details of the payment object. properties: tenantId: type: string description: The unique identifier for Service - this is equivalent to jurisdiction_id in Open311. As the platform intends to be multi tenanted - this is always required minLength: 2 maxLength: 50 txnAmount: type: string description: Transaction Amount, preferably rounded off to two decimal places minLength: 1 billId: type: string description: Unique bill ID associated with the transaction module: type: string description: Module business code for which the transaction is being initiated, ex PT, WS, PGR etc moduleId: type: string description: Unique identifier in the module for which the transaction is being initiated productInfo: type: string description: Brief description for which the transaction is being carried out. gateway: type: string description: Gateway to be used, from the available list, such as PAYTM, PHONEPE. callbackUrl: type: string description: URL to which control has to be redirected to from the gateway txnId: type: string readOnly: true description: Transaction ID of the payment, generated by the gateway service user: $ref: '#/definitions/User' txnStatus: type: string readOnly: true description: Current status of the transaction enum: - SUCCESS - FAILURE - PENDING txnStatusMsg: type: string readOnly: true description: Brief status message for the transaction gatewayTxnId: type: string readOnly: true description: Transaction ID returned by the gateway, for reference gatewayPaymentMode: type: string readOnly: true description: Mode of payment used at the gateway gatewayStatusCode: type: string readOnly: true description: Payment Gateway Specific RAW status code gatewayStatusMsg: type: string readOnly: true description: Payment Gateway Specific RAW status message receipt: type: string readOnly: true description: Receipt ID generated for this payment auditDetails: $ref: 'https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-0-0.yml#/definitions/AuditDetails' required: - tenantId - txnAmount - billId - module - moduleId - productInfo - gateway - callbackUrl User: type: object readOnly: true properties: tenantId: type: string description: Unique Identifier of the tenant to which user primarily belongs uuid: type: string description: UUID for the user. userName: type: string description: The unique username used of the user - this will be used for user login. This needs to be unique within the tenant. minLength: 4 maxLength: 64 name: type: string description: The full name of the user. minLength: 3 maxLength: 100 mobileNumber: type: string description: Mobile number of the user maxLength: 10 emailId: type: string description: Email address of the user maxLength: 128 required: - uuid - userName - name - mobileNumber - tenantId ######################################### TransactionRequest: description: >- The payment object, containing all necessary information for initiating a payment and the request body metadata properties: requestInfo: $ref: >- https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-0-0.yml#/definitions/RequestInfo Transaction: $ref: '#/definitions/Transaction' RequestInfoWrapper: description: >- Wrapper for Request Info properties: requestInfo: $ref: >- https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-0-0.yml#/definitions/RequestInfo TransactionResponse: description: >- The payment seatch response object, representing the status of the payment properties: responseInfo: $ref: >- https://raw.githubusercontent.com/egovernments/egov-services/master/docs/common/contracts/v1-0-0.yml#/definitions/ResponseInfo Transaction: type: array items: $ref: '#/definitions/Transaction' #########################################