Developing a MiniApp for the Klutch Credit Card

The Klutch card is a programmable credit card that allows you to control and automate your spending. Here you can code your own feature, or MiniApp as we call it, and add it to our marketplace within the Klutch app.

Klutch has a public API with an SDK that allows any developer to create their own MiniApp to be added to the Kutch marketplace. MiniApps on the marketplace can be used by any Klutch cardholder.

In this article, we will show you how to create your own MiniApp with a simple example.

Documentation

Let’s start by first explaining how to interact with the Klutch API.

The Developer portal is the main source of knowledge.

There you can find:

• quickstart guide explaining all the tools that Klutch provides
• api references with all graphql queries and mutations, including the postman collection and the authorization explanation
• react native components to help you build the design of your MiniApp panels
• tools to simulate your MiniApp functioning in the sandbox environment

Klutch’s Github is also a great place to start, here you can find repositories about:

• MiniApps that the Klutch team has open-sourced
• klutch-js is our Javascript SDK
• klitch-components contains the react native components to design the MiniApp panels
• klutch-cli helps developers creating their own MiniApps

In summary, how does the MiniApp work?

MiniApps are composed of different types of panels: Home Panels, that lives on the home tab of the Klutch app; Transaction Panels that live in the transaction details page; and Full screen Panels that occupy the entire screen and can be accessed either by opening the MiniApp directly from the MiniApp Gallery tab or by clicking on one of the other panels.

First, you will build the full screen panel templates for your MiniApp using a restricted react native template. These are screens within the MiniApp itself where the main functionality of your MiniApp resides. You can use the entire phone screen to display information and change configurations of your MiniApp. You can use the full screen panels to give users the ability to input information for your MiniApp and provide more detail for the information you show on the other panels.

Other than the full screen panels screens, you can create panels that can be rendered on the home tab and/or the transaction tab of the Klutch app.

You also might want to build your own MiniApp’s server by exposing a webhook endpoint where Klutch will notify it of every event it is interested in, and then you can interact with our public api to update your templates or panels.

Example: Single-Use Card

Setup video

Klutch created a MiniApp that allows users to create a new virtual card for a single transaction. After the transaction happens, the said virtual card is automatically terminated to prevent future transactions.

First, the user will install your MiniApp from the Klutch marketplace within the Klutch App. See below an example screenshot of the marketplace.

MiniApp marketplace

If a user is interested in your MiniApp, they click on it to go to its details page. Here the user will find more information you provided about your MiniApp: its icon, name, short description, long description, and examples of panels all created by you, the MiniApp Developer.

MiniApp detail page

If a user wants to use your MiniApp, they will click the “Install” button to add it to their card. At the moment the MiniApp is installed, Klutch sends a webhook to the MiniApp server saying that a new user has just installed your MiniApp. After that, they will be able to open the MiniApp to view the full screen panels. The MiniApp developer decides if their MiniApp also wants to have panels on the home tab and/or the transaction tab. In this case, the developer chose to have a home panel to allow the user to create a single-use card from the home tab. When the MiniApp is installed, the server requests that a home panel be installed on the user’s home screen. On the backend, when the user does a transaction with the single-use card they created, Klutch will send a new event on the webhook about this transaction to the server. Once the server recognizes the transaction is made using the single-use card, it will make an API call on the backend to cancel that card.

Start building your MiniApp for the Klutch Card

Now let’s show you step-by-step how to code your own MiniApp for the Klutch App.

• Sign up for the Klutch developer portal
• Install klutch-cli
• Run klutch login and log with your credentials
• Run klutch init to initiate your miniapp

initializing miniapp

The CLI will build the directory of templates, keys, and json config file you will need for your MiniApp.

Frontend

Inside the templates folder, you will find files that you can use to code on top of. The Main.jsx is the full screen panel template (the first screen the user sees when they click in open). The Home.jsx is the home panel template that is displayed on the home tab. Transaction.jsx is the transaction panel template that the user sees on that specific transaction’s detail page.

https://github.com/KlutchCard/miniapps/tree/miniappArticle/miniappArticle/templates

Please note that there are some restrictions on components you can use to build your template. You can use any of the Klutch components and some other basic components.

Next step is use the CLI to locally debug and test your MiniApp and its panel templates.

Backend

Your backend can be written in any language, in our example we are using NodeJS (Typescript).

Create a backend directory (in our case, inside the MiniApp folder). Our backend consists of a web server that has two main purposes: 1. Serve as the webhook endpoint for Klutch events (this is the endpoint that will be called by Klutch’s servers when a transaction happens) and 2. Serve as an endpoint for calls directly from the Klutch App (that will be called from the app when the users use our MiniApp panels).

https://github.com/KlutchCard/miniapps/tree/miniappArticle/miniappArticle/backend

The webhook payload schemas are described on this link.

PLEASE NOTE: Klutch uses JWT as an authentication method to our servers and validates the call using the public key you created when running klutch init.

You can find the MiniAppId, on developer-portal.

Debugging locally

Run the backend locally and add the server URL to the klutch.json file. IMPORTANT: Please note that this will only work if your mobile and your server are connected to the same wifi network.

Within the root of the MiniApp project, run klutch debug and use your mobile phone to scan the QR code.

At first, you will only see the full screen panel (Main.jsx template), to add the home and transaction panels, you can create them by calling the addPanel API endpoint on the server or by calling context.createPanel from the template.

Publishing to our sandbox

First, deploy the backend and add the server URL to the klutch.json file.

In addition to the templates, use the images folder to add media for your MiniApp like your app icon and screenshots of your full screen panels.

Run klutch publish to upload your templates, images and public key.

Next Steps

Once you are satisfied with your MiniApp, please reach out to us on the slack channel and we will let you know how to publish your MiniApp to our production environment so everyone can use it!