DEV Community

Cover image for Build your own mini ATMs using Aadhaar and Eko APIs
Eko Developers for Eko Developer Community

Posted on

Build your own mini ATMs using Aadhaar and Eko APIs

We all have seen this even before digital era - the best way to authenticate uneducated people's identity has been - their thumbprint. This can be the key to their participation in this digital age as well. Currently they cannot withdraw cash from ATM because they don't know how to read/type. Well, they can share PIN with someone to get assistance but is that safe?
Can they use the old and reliable way to authenticate their identity - their thumbprint? With AePS and Eko APIs, you can build a system where they can withdraw cash from their Aadhaar-linked bank account with just their thumbprint.

Eko recently held its monthly community meetup to teach how to build a cash withdrawal system using Aadhaar. This is what we learned in the meetup. You can watch the recording of the event here.

What is Eko?

Eko offers a range of financial transactions such as domestic money transfers, cash payouts, bill payments, etc. for individuals who may not have access to traditional banking options or don't want to use them. These transactions can be performed by visiting a nearby shopkeepers who have partnered with Eko. In addition, Eko APIs are also open for developers to build on top of its ecosystem.

What is AePS?

Aadhar enabled Payment System

AePS is a payment platform in India that allows customers to carry out banking transactions using their Aadhaar number and fingerprint authentication.

With AePS, people can use their Aadhaar number and biometric information to access their bank accounts, make cash deposits and withdrawals, and transfer funds from one account to another.

AePS is considered to be a secure, reliable, and convenient payment system, particularly for those who don't have easy access to traditional banking services. It is widely used in rural areas of India, where people often lack proper identification documents and face difficulties in accessing formal banking channels.

History of AePS

Summarising the history of AePS as mentioned here:

AePS was built to speed track Financial Inclusion in the country by RBI. AePS was a result of a work by a working group made from members of RBI, Unique Identification Authority of India, NPCI, Institute for Development and Research in Banking Technology and some special invitees representing banks and research institutions.

The only inputs required for a customer to do a transaction under this scenario are

  • Bank Name
  • Aadhaar Number
  • Fingerprint captured during enrollment.

What can you do with AePS?

  • Cash Deposit
  • Cash Withdrawal
  • Balance Enquiry
  • Mini Statement
  • Aadhaar to Aadhaar Fund Transfer

Business case : Why build AePS-based system

tl;dr: Earn commission from each transaction and make an impact

  • Many people do not have enough education to operate standard ATMs. 23% people in India do not have basic literacy.
  • In many areas, ATMs are still far away, making it inconvenient to get cash from ATMs
  • 140Cr people in India have Aadhar. And Aadhaar is a robust mechanism to verify identity of any Indian citizen

This is an opportunity to fill that gap and provide financial services to these customers enabling them to transact through your network of mini ATMs. These ATMs don't have to be machines, they can be simply a retailer near to your customer who can authenticate the customers and pay them cash. Eko APIs as intermediary handle the settlement needed between the customer's bank, your account and the retailer(your network who helps with transaction).

With Eko APIs, building such system becomes easier and a commission is rewarded to the developer for AePS washout transaction.

This is not only a big opportunity to make money but also to make an impact in lives of these people who cannot access basic financial services because of the lack of education or infrastructure

Build the AePS system once, install it where you can get the customers, and earn on each transaction. This could be a great side-income with most of your effort being one time when you build the system.

You may also want to scale and increase your earnings by expanding your business. You can do so by bringing on-board business partners or employees who can connect with your target audience and utilize your system for transactions.

How to integrate AePS API?

You only need to integrate couple of APIs to build the complete system.

This is how the transaction flow looks like

  1. Customer authenticates themselves using fingerprint scanner
  2. Bank deducts the amount from the customer's Aadhaar-linked bank account
  3. You pay the customer in cash
  4. Bank settles the amount in your bank account via Eko

1. Onboard a customer

PUT /ekoapi/v1/user/onboard


  "initiator_id": 9962981729
  "pan_number": "BFUPM3499K",
  "mobile': 9123354235,
  "first_name': "Tina",
  "last_name: "Chawla",
  "email": "",
  "residence_address": {
    "line": "Eko India",
  "dob": "1992-05-10",
  "shop_name": "Akanksha Stores"

Enter fullscreen mode Exit fullscreen mode

API reference

As a first step, you need to onboard a customer for the first-time with their basic KYC info such as pan_number and mobile no. Once this is done, you can perform AePS transaction. You don't need to call this API again for later AePS transactions.

2. Withdraw cash transaction

POST /ekoapi/v2/aeps

--data-raw '{
    "service_type": 2,
    "initiator_id": "9962981729",
    "user_code": "20810200",
    "customer_id": "9999999999",
    "bank_code": "HDFC",
    "amount": "100",
    "client_ref_id": "202105311125123456",
    "pipe": "0",
    "aadhar": "YrvFh+QFLmHXPjUP1/fU=",//hashed value of Aadhar
    "notify_customer": "0",
    "piddata": "<?xml version=\"1.0\"?><PidData>...</PidData>"//Data from fingerprint scanner
Enter fullscreen mode Exit fullscreen mode

API Reference

You can use this API for the transaction which authenticates the user and deducts the amount from user's bank account. On success, you can handover the cash to user. This happens instantly. Once you have the success or failure confirmation, this transaction is finished from user's perspective. But you might need to perform some more actions to get your earning transferred to your account.


If you try these, you are likely to get authentication error. To fix that, you'll need to authenticate your API requests

3. Enquire transaction status

Sometimes, transactions do not succeed instantly due to different reasons such as mismatch in authentication details, low balance account, etc. In such cases, you might want to enquire about the transaction status later to see if they succeeded or failed. You can use this API for these transaction inquiries

GET /ekoapi/v2/transactions/{id} | API Reference

Now that you're able to perform the transaction, how do you get the money you gave to the customer. You need to perform the settlement transaction for that.

4. Settle funds into your bank account

a. Add your settlement bank account

Once you have done transactions for multiple customer, you'd want to get the transaction money in your bank account. For that, you need to add your bank account where Eko can settle the amount. You don't need to call this again unless you want to add another bank accont for settlement.

PUT /ekoapi/v1/agent/user_code:{user_code}/settlementaccount

// --data-raw 
  "initiator_id": 7411111111,
  "bank_id": 108,
  "ifsc": "SBIN0000001",
  "service_code" : 39,
  "account": "34567891234"
Enter fullscreen mode Exit fullscreen mode

API Reference

You need to perform this transaction once so that the money can be routed to you as per the settlement policies.

b. Retrieve settlement ammount

GET /ekoapi/v1/agent/user_code:{user_code}/settlementaccounts?initiator_id=9962981729&service_code=39'
Enter fullscreen mode Exit fullscreen mode

API reference

With this API, you can check the total AePS transactions amount you have given to customers and the remaining amount that can be settled to your account. You may want to call this API before you start the settlement.

c. Initiate settlement

You need to call this API each time you want to settle the AePS transaction amount into your bank account. Usually you'd want to do this on biweekly or weekly basis but you can also perform this on a daily basis.

POST /ekoapi/v1/agent/user_code:{user_code}/settlement


  "initiator_id" : 7411111111,
  "service_code" : 39,
  "amount" : 100,
  "recipient_id": 1824,
  "payment_mode": 5,
  "client_ref_id": "Settlemet0000001"

Enter fullscreen mode Exit fullscreen mode

API reference

And with this transaction, the complete lifecycle of the payment is finished. You paid the customer after verifying their identity, the bank deducted the amount from customer's bank account, you got paid the amount in your bank account. You'll also receive commission you have earned on top of the transaction amount.


It is easy to build AePS system using Eko APIs that works as a mini ATM. This can be a source of income for entrepreneurs and developers, at the same time this brings financial inclusion for people who do not have access to normal banking services.

If you have questions, feel free to ask on Eko developers community on Discord.


Top comments (0)