openapi: 3.1.0 info: title: Eko Platform Services APIs version: 3.0.0 license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html x-logo: url: https://ekoin.netlify.app/images/logo.svg description: |- This is a **work-in-progress** OpenAPI specification for the EPS developer platform. # Introduction This API definition is intended to to be a good starting point for describing your API in [OpenAPI/Swagger format](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md). It also demonstrates features of [create-openapi-repo](https://github.com/Redocly/create-openapi-repo) tool and [Redoc](https://github.com/Redocly/Redoc) documentation engine. So beyond the standard OpenAPI syntax we use a few [vendor extensions](https://github.com/Redocly/Redoc/blob/master/docs/redoc-vendor-extensions.md). # OpenAPI Specification The goal of The OpenAPI Specification is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interfaces have done for lower-level programming, OpenAPI removes the guesswork in calling the service. servers: - url: https://staging.eko.in/ekoapi/v{version} description: Staging URL variables: version: default: '3' enum: - '1' - '3' description: The API version - url: https://api.eko.in/ekoicici/v{version} description: Production URL variables: version: default: '3' enum: - '1' - '3' description: The API version tags: - name: Agent Management description: Onboard your agents/users and manage services for them. - name: Customers description: Create and verify customers. Perform recurring transactions and add multiple recipients to the same customer. - name: Customer KYC description: Upgrade customer KYC status and enable higher amount of transactions per month. - name: Recipients description: Manage recipients for your customers to transfer money to. - name: Transaction description: Money Transfer APIs. - name: Banks description: Get bank information. - name: Token description: Accept real-time cash-payment for your digital services. - name: Partner Account description: Settle your funds into your bank account. - name: Fund Settlement description: sample description - name: AePS Fund Settlement description: sample description externalDocs: description: Read the detailed guides on Eko Developer Portal url: https://developers.eko.in paths: /user/services: get: summary: Get Services description: | Return a list of services available for your users 1. This API returns a unique service_code for each service 2. This service_code needs to be used while activating the service for your users 3. The services available are: * AePS Cashout * eKYC * Cash Deposit into SBI/KVB branches * CDM service at KVB operationId: getUserServices tags: - Agent Management parameters: - $ref: '#/components/parameters/initiator_id' - $ref: '#/components/parameters/developer_key' - $ref: '#/components/parameters/secret-key' - $ref: '#/components/parameters/secret-key-timestamp' responses: '200': description: '' headers: {} deprecated: false security: [] /user/request/otp: put: summary: Request OTP description: | Send an OTP to your agent/user to verify their mobile number * Mobile number of the user is an important parameter that needs to be captured during onboarding of a user. * Every mobile number needs to be verified via OTP. * You will not receive the OTP on the mobile number on UAT platform operationId: putUserRequestOtp tags: - Agent Management requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: initiator_id: type: integer format: int64 required: - initiator_id example: initiator_id: 9962981729 parameters: - $ref: '#/components/parameters/developer_key' - $ref: '#/components/parameters/secret-key' - $ref: '#/components/parameters/secret-key-timestamp' responses: '200': description: '' headers: {} deprecated: false security: [] /user/verify: put: summary: Verify User Mobile Number description: Verify your agent/user's mobile number via OTP operationId: EkoapiV1UserVerify_PUT tags: - Agent Management parameters: - $ref: '#/components/parameters/developer_key' - $ref: '#/components/parameters/secret-key' - $ref: '#/components/parameters/secret-key-timestamp' responses: '200': description: '' headers: {} deprecated: false security: [] /user/onboard: put: summary: Onboard User description: | Onboard a new agent/user on the platform. We verify the PAN number provided by you in this step and match the name returned in PAN verification and the name coming in API. So please do enter valid PAN number and it should be of the same merchant/user whose name you are providing. The name matching is only for the production, on staging we won't be matching the name from PAN verification and in the request. operationId: putUserOnboard tags: - Agent Management parameters: - $ref: '#/components/parameters/developer_key' - $ref: '#/components/parameters/secret-key' - $ref: '#/components/parameters/secret-key-timestamp' responses: '200': description: '' headers: {} deprecated: false security: [] /user/service/activate: put: summary: Activate Service description: | Activate a particular service for your agent/user. ### Mandatory Parameyters for AePS Activation: For the AePS activation, you need to pass user_code, initiator_id, service_code = 43 or 1, modelname, devicenumber, office_address, address_as_per_proof, pan_card as mandatory and either of voter_card_front and voter_card_back or aadhar_front and aadhar_back. Either of Voter Card or Aadhaar Card is required. If you are sending voter card send in the parameters voter_card_front and voter_card_back. If you are sending Aadhaar card send in the parameters aadhar_front and aadhar_back. By activating AePS for merchants using the new service code = 43, they will be able to conduct AePS transactions instantly. If we find any mismatch in documents, the merchant’s AePS business will be paused. We will communicate the same to you within 24 working hours of merchant activation and ask for re-uploading updated documents. Post re-upload, the business will continue as usual. Note - We highly recommend to activate all new AePS merchants using the new service code = 43 to benefit from seamless integration. Please note that if you do not change service code = 1, all your merchants will be on-boarded using the current flow with a 7 working day TAT for merchant activation. ### AePS Activation TAT After activation, the user state goes into pending state and it will take 3 business days for any user to get activated for AePS. ### Please Note: 1. In case of AePS service activation, the user_code is the unique code received in response to the Onboard User API 2. Either of Voter Card or Aadhaar Card is required. 3. If you are sending voter card send in the parameters voter_card_front and voter_card_back. If you are sending aadhaar card send int the parameters aadhar_front and aadhar_back 4. The file size for the documents for AePS activation should be less than 1MB. 5. We accept the images in JPEG, JPG and PDF format, not in PNG. PNG images are rejected from the partner bank. operationId: putUserServiceActivate tags: - Agent Management parameters: - $ref: '#/components/parameters/developer_key' - $ref: '#/components/parameters/secret-key' - $ref: '#/components/parameters/secret-key-timestamp' responses: '200': description: '' headers: {} deprecated: false security: [] /user/services/user_code:{user_code}: get: summary: User Services Enquiry description: | Returns the status of each service associated with your agent/user. operationId: GetUserServices tags: - Agent Management parameters: - name: user_code in: path required: true schema: type: integer example: 20310003 - $ref: '#/components/parameters/initiator_id' - $ref: '#/components/parameters/developer_key' - $ref: '#/components/parameters/secret-key' - $ref: '#/components/parameters/secret-key-timestamp' responses: '200': description: '' headers: {} deprecated: false security: [] /onboard: put: summary: Onboard_PUT description: https://api.eko.in:25002/ekoicici/v1/user/onboard operationId: Onboard_PUT tags: - Customers parameters: - $ref: '#/components/parameters/developer_key' - $ref: '#/components/parameters/secret-key' - $ref: '#/components/parameters/secret-key-timestamp' responses: '200': description: '' headers: {} deprecated: false security: [] /customers/mobile_number:{mobile_number}: get: summary: Get customer information description: Get a customer's basic profile information operationId: EkoapiV1CustomersMobileNumber9004073059_GET tags: - Customers parameters: - name: mobile_number in: path required: true schema: type: integer format: int64 example: 9004073059 - $ref: '#/components/parameters/initiator_id' - $ref: '#/components/parameters/developer_key' - $ref: '#/components/parameters/secret-key' - $ref: '#/components/parameters/secret-key-timestamp' responses: '200': description: '' headers: {} deprecated: false security: [] components: parameters: initiator_id: name: initiator_id in: query description: Your registered mobile number required: true schema: type: integer format: int64 example: 9962981729 developer_key: name: developer_key in: header description: Your static API key ([See Guide](auth)) required: true schema: type: string minLength: 20 maxLength: 50 example: becbbce45f79c6f5109f848acd540567 secret-key: name: secret-key in: header description: Your dynamically generated security key, unique for every request required: true schema: type: string minLength: 40 maxLength: 60 example: MC6dKW278tBef+AuqL/5rW2K3WgOegF0ZHLW/FriZQw= secret-key-timestamp: name: secret-key-timestamp in: header description: The current timestamp used to generate secret-key required: true schema: type: integer format: int64 example: 1516705204593