mattfaz / actual-tap

Accept Tap-to-Pay transactions from mobile devices and automatically create transactions in Actual Budget

Actual Tap

Mobile Tap & Go transactions added automatically to Actual Budget

Contents

• Overview
• Mapping
• Run the App
• iOS Setup
• Android Setup
• Todo
• Nginx

Overview

Actual Tap is a Fastify API and Nuxt3 app that utilises the Actual Budget API Client to create transactions.

Primary purpose of Actual Tap is to receive a POST request from mobile devices (e.g. iOS Shortcuts) when a Tap to Pay transactions is made.

It has been designed with the following process in mind:

1. Device is tapped to make a purchase
2. Device triggers a POST request containing transaction information (Merchant Name & Amount)
   • Recommedned apps are Shortcuts (iOS) or Tasker (Android)
3. Actual Tap receives request and checks if Merchant Name is mapped in database table
   • if found, retrieve correct Payee name, Category, and Account
   • if not found, add as a new payee to be mapped later
4. Add transaction to Actual Budget

Mapping

Generally a transaction will contain a Merchant name such as 'Target Corp, SF, CA, USA'. However you don't necesarily want this as the payee name in Actual Budget, instead you might simply want 'Target'.

As well as being an API to receive your transaction information Actual Tap provides a webapp where you can map the Merchant Names it receives to a desired Payee Name, Category, and Account.

Generally people shop at the same places frequentely, as such once you've mapped the Merchant name it should be added to Actual Budget correctly for future transactions.

Run the app

Notes: This is in active / heavy development, issues, pull requests, feature requests etc. are welcome.

Prerequisites:

• Postgresql database setup
  • User and database created

Running in Docker:

• Create a copy of .env.sample in the root of the project and name it .env
  • $ cp .env.sample .env
• Update the environment variables in the new .env file
• Run: docker-compose up

Running locally with npm:

• Create a copy of .env.sample in the root of the project and name it .env
  • $ cp .env.sample .env
• Create a copy of .env.sample in the /frontend folder of the project and name it .env:
  • $ cp /frontend/.env.sample /frontend/.env
• Update both .env files with the same API_KEY
• Install backend: $ cd /backend && npm install
• Install frontend: $ cd /frontend && npm install
• Run both frontend & backend form their directories: $ npm run dev

iOS Setup

1. Open Shortcuts app
2. Select Automations
3. Create new Automation to Run Immediately
4. When:
   • I tap any of x Wallet passes or payment cards
5. Do:
   • Receive transaction as input
   • Get numbers from Amount (transaction variable)
   • Get contents of URL:
     • URL = your subdomain
     • Headers = { api-key: <your_api_key>}
     • Body = JSON { merchant: <merchant_variable>, amount: <numbers_variable> }

Android Setup

TBC

TODO:

• Add documentation / images for mobile setup
• Improve security header
• Improve error handling
• Improve logging
• Make web app mobile responsive
• Improve fuzzy matching
• Update all related transactions when Payee is updated
• Theme to default to user preference (light / dark)

Nginx

Below is the .conf file I use within the Linuxserver.io SWAG container. Note: The below configuration denies all requests that are not POST to the /transaction endpoint. Web app (frontend) access I achieve using Wireguard.

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    # Update below with your subdomain name
    server_name at.*;
    include /config/nginx/ssl.conf;
    client_max_body_size 0;

    location /transaction {
        # Allow only POST request to the /transaction endpoint
        limit_except POST {
            deny all;
        }

	    # Proxy headers
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_pass_header Content-Type;

        # Update below with your host details
        set $upstream_app 192.168.0.25;
        set $upstream_port 9991;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
    }
}