The Client Library is a convenient wrapper around our Data Provider APIs to simplify integration with your application.

Our Data Provider APIs are a collection of HTTP REST APIs enabling compatibility with any standard HTTP client for sending requests and handling responses. Our Client Library is a convenient wrapper around the Data Provider APIs and adds methods for common data capture patterns. Functioning as a Capacitor Plugin, the Client Library simplifies application integration work with convenient methods for authorization, licensing, capture, and upload.

Initialization

To initialize, inject the TikiService and pass in your system's unique identifier for the user.

Authorization

The library will request a short-lived token using the customer's public Provider ID and User ID. Our Data Provider APIs require a valid JWT (JSON Web Token), requirements for requesting a Provider Authorization Token without the Client Library can be found under Account Management - Authorization. The Client Library includes logic for automatically refreshing authorization tokens upon expiration.

With Vue >=3.0.0

<script setup lang="ts">
  import { inject } from "vue";
  import { type TikiService } from "@mytiki/data-provider";
  
  const tiki: TikiService | undefined = inject("Tiki");
  tiki?.initialize(providerId, userId).then(() => console.log("Tiki Initialized"));
</script>

With Vue 2.7.15

<script setup lang="ts">
  import { inject } from "vue";
  import { type TikiService } from "@mytiki/data-provider-vue2";
  
  const tiki: TikiService | undefined = inject("Tiki");
  tiki?.initialize(providerId, userId).then(() => console.log("Tiki Initialized"));
</script>

Our Gmail and Outlook integrations utilize additional vendor-specific OAuth2 implementations for authorization; more on this under Data Capture - Email Receipt Extraction .

Data Licensing

Capturing and uploading receipt data to our platform requires a valid user data license agreement (UDLA). A UDLA is an explicit agreement in addition to your standard app terms of service that defines: a) the user as the owner of the data, b) the terms around how it will be licensed, used, and c) the compensation offered in exchange.

The Client Library includes a templated, pre-qualified agreement. Use the library to either explicitly request user consent or allow the library to automatically show the license agreement flow upon first data upload.

await TikiService.license();

Data Capture

The Client Library includes optional methods for: a) scanning physical receipts using the mobile device camera, and b) extracting receipts from connected email accounts.

Physical Receipt Scanning

The Capacitor camera plugin is employed to open the camera and capture images for receipt scanning. Users have the flexibility to capture multiple images for scanning lengthy receipts. These image are temporarily stored in memory and combined before the upload process.

Utilize the TikiService.scan() method to initiate the scanning of a receipt. This method returns a Promise containing an ID for the receipt, which can used to locate the extracted data in your Data Cleanroom. Upon completion of the image capture, the resulting image is automatically uploaded —see Data Upload.

const receiptId = await TikiService.receipt.scan();

Email Receipt Extraction

The Client Library supports Gmail and Outlook email accounts using their corresponding vendor specific OAuth2 standards for authorization. Utilization of the Gmail or Outlook integrations requires a client ID and approval of your application from Google and/or Microsoft.

Both integrations follow the OAuth2 authorization code flow, where the user is redirected to an external login URL, hosted by the service provider (Google/Microsoft), to enter their email and password. Upon approval, the user is redirected back to the application with a short-lived authorization token. The token, never credentials, is saved locally in the device's encrypted storage, never shared, and only accessible to the application during execution. A list of connected accounts and last extraction date can be retrieved using the accounts() method.

Utilizing the authorization token, the Client Library temporarily downloads the emails from a list of thousands of known receipt senders. No user email data is permanently retained within the app; upon upload the local cache of emails is flushed. The last successful extraction date is stored locally for deduplication and performance improvement of sequential executions.

await TikiService.gmail.login();
const accounts = await TikiService.receipt.accounts();
const receiptIds = TikiService.receipt.email();
tiki?.rewards().then(response => {
  console.log(response);
});

Data Upload

When utilizing the receipt.scan() or receipt.email() methods captured data is automatically uploaded to our platform for processing. Alternatively, the application can implement its own custom scan and email extraction methods and utilize the receipt.upload(...) method to submit records.

All data uploads require a valid User Data License Agreement. If one does not exist for the user, the Client Library will automatically present the user with the License Agreement flow. If the user has declined participation in the program an error is returned and the data is discarded.

const emailRequest = {
  sender: "[email protected]",
  body: "Thank you for your purchase",
  attachments: [file1, file2]
}

const scanRequest = {
  attachement: [image1]
}

const emailReceiptId = await TikiService.receipt.upload(emailRequest);
const scanReceiptId = await TikiService.receipt.upload(scanRequest);

User Cards

Link a Card to a User

To link a card to a user, use the cards.add method. It requires card details.

const cardDetails = {
  bin: 123456,
  last4: 7890,
  issuer: "Name_Of_Issuer",
  network: "VISA"
};

tiki?.cards.add(cardDetails).then(response => {
  console.log(response);
});

Get User Cards

To retrieve the list of linked cards for a user, use the cards.get method.

tiki?.cards.get().then(response => {
  console.log(response);
});

User Offers

Get User Offers

To retrieve the list of available offers for a user, use the offers method.

tiki?.offers().then(response => {
  console.log(response);
});

Transactions

Send a Transaction

To send a transaction for CLO matching, use the transaction method. It requires transaction details.

const transactionDetails = {
  transactionId: "txn-789",
  amount: 1500,
  currency: "USD",
  status: "APPROVED",
  description: "Purchase at Some Merchant",
  merchantId: "some-merchant-id",
  cardBIN: 123456,
  cardLastFour: 7890
};

tiki?.transaction(transactionDetails).then(response => {
  console.log(response);
});

User Rewards

Get User Rewards

To retrieve current user rewards, use the rewards method. It will return a Rewards object with the current balance and a history of each rewards.

tiki?.rewards().then(response => {
  console.log(response);
});

Data Protection and Privacy

Our Client Library is designed to be an optional, convenient wrapper around our Data Provider HTTP APIs to simplify integration with your application. The library maximizes user security using industry best practices for tokenized authorization and utilizes a minimum necessary data policy for privacy.

Our platform is entirely open-source and available for your team's compliance review at github.com/tiki. This Client Library can be found at github.com/tiki/apps-receipt-capacitor.

Data Persistence

The Client Library does not persist any user data. All scanned and extracted receipts are kept in-memory and discarded upon upload. Authorization tokens are stored in the local device's encrypted storage and only accessible to the application during runtime.

Transport Security

All library requests to APIs utilize HTTPS with TLS 1.3 for transport encryption. This includes requests to third-party APIs including Gmail and Outlook and our own Data Provider APIs.

Known Senders

To avoid interacting with a user's personal and sensitive emails, the Client Library utilizes an explicit list of known receipt email addresses —for example, [email protected]. To extract receipts, emails exclusively from this list are downloaded first to the local device then and uploaded to our system for processing.

User Credentials

No user credentials are ever persisted by the Client Library or shared with any of our systems. Integrations to third-party accounts such as Gmail and Outlook utilize OAuth for tokenized authorization. Authorization tokens are only stored in the local encrypted device storage.

Cardholder Information

No cardholder information is required at any time to handle the CLO features in Client Library or CLO APIs. The only data needed for matching the card with available offers is the last 4 digits of the card and the BIN, usually the first 4-6 digits.