🖥️For Developers

Fina Card API (BETA)

Fina Card has public API endpoints so you can integrate Fina Card in your dApp or Wallet UI, or use our API to analyse your spendings://api

Generating Signature

For each API method, you need to include a ADR-36 signature. The message required in each API method is different. Here is an Javascript example of using Keplr to generate the signature.

if (window.keplr) {
    await window.keplr.enable("secret-4");
    const account = await window.keplr.getKey("secret-4");
    const signed = await window.keplr.signArbitrary(
      "secret-4",
      account.bech32Address,
      "Fina Card: Sign In"
    );
    // Parameters required to make a request
    const signature = signed.signature
    const address = account.bech32Address
    const pubKey = signed.pub_key.value
    const chainId = "secret-4"
}

Encryption Key

As Fina needs to query the details of the Top Up transaction, which is encrypted on Secret Network, we need to know the encryption key used in the transaction so we can decrypt the message. Here is an example code to generate the encryption key.

import { fromBase64, toBase64 } from "secretjs";

const getTxEncryptionKey = async (txHash: string, chainId: string) => {
  if (window.keplr) {
    const encryptionUtils = window.keplr.getEnigmaUtils(chainId);
    const txResult = await fetch(
      `${SECRET_LCD_URL}/cosmos/tx/v1beta1/txs/${txHash}`
    ).then((r) => r.json());
    const msg = txResult?.tx?.body?.messages[0].msg
    if (!msg) {
      return "";
    }
    const nonce = fromBase64(msg).slice(0, 32)
    const encryptionKey = toBase64(
      await encryptionUtils.getTxEncryptionKey(nonce)
    );
    return encryptionKey;
  }
  return "";
};

API Methods

Get Account

Get user's Fina Card information and transactions

POST https://api.card.fina.cash/getAccount

Request Body

interface Response {
    id: string
    tier: {
      name: string
      stakingApy: number
      spendingRewards: number
    },
    limits: {
      posPurchase: {
        daily: {
          limit: number
          used: number
        },
        monthly: {
          limit: number
          used: number
        },
      },
      internet: {
        daily: {
          limit: number
          used: number
        },
        monthly: {
          limit: number
          used: number
        },
      },
      withdrawal: {
        daily: {
          limit: number
          used: number
        },
        monthly: {
          limit: number
          used: number
        },
      },
      contactless: {
        daily: {
          limit: number
          used: number
        },
        monthly: {
          limit: number
          used: number
        },
      },
    },
    maskedCardNumber: string
    expiryDate: number
    status: string
    currency: string
    cardHolder: string
    balance: number
    mobile: string
    transactions: {
        id: string
        date: number
        amount: number
        fx: {
          amount: number
          currency: string
        },
        merchant: {
          category: string
          name: string
          longName: string
          city: string
          country: string
          icon: string
          url: string
        },
        description: string
        hash: string
        status: string
        fee: {
          amount: number
          currency: number
          description: string
        }[]
    }[]
}

Get Sensitive Information

Get user's encrypted sensitive card information like full card number, CVV, 3DS password

POST https://api.card.fina.cash/getSensitiveInfo

Request Body

interface Response {
    encrypted3dsPassword: string // encryption scheme label: Card3DSecurePassword
    encryptedCardNumber: string // encryption scheme label: CardNumber
    encryptedCvv: string // encryption scheme label: CVV2
}

To decrypt the information, use the RSA key generated with scheme { hash: "sha256", label: "CardNumber" } . Scheme label for each field is different.

Example:

import NodeRSA from "node-rsa";

// Get user's wallet address and sign message
const chainId = "secret-4"
const timestamp = new Date().toISOString();
const account = await window.keplr.getKey(chainId);
const signed = await window.keplr.signArbitrary(
    chainId,
    account.bech32Address,
    `Fina Card: View Sensitive Information at ${timestamp}`
);
// Generate RSA key
const key = new NodeRSA();
key.generateKeyPair(1024);
const publicKey = Buffer.from(key.exportKey("pkcs1-public")).toString("base64");
// Call API
const result = await fetch(
    `https://api.card.fina.cash/getSensitiveInfo`,
    {
      method: "POST",
      body: JSON.stringify({
          signature: signed.signature,
          address: account.bech32Address,
          pubKey: signed.pub_key.value,
          timestamp,
          rsaPubKey: publicKey,
        }),
      }
).then((r) => r.json());
if (result.success === false) {
  throw new Error(result.message);
}
// Decrypt responses
key.setOptions({
    encryptionScheme: {
      hash: "sha256",
      label: "CardNumber",
    },
});
const cardNumber = key.decrypt(
    result.encryptedCardNumber.split("\n").slice(1, -2).join(""),
    "utf8"
);
key.setOptions({
    encryptionScheme: {
      hash: "sha256",
      label: "CVV2",
    }
});
const cvv = key.decrypt(
    result.encryptedCvv.split("\n").slice(1, -2).join(""),
    "utf8"
);
key.setOptions({
    encryptionScheme: {
      hash: "sha256",
      label: "Card3DSecurePassword",
    }
});
const password = key.decrypt(
    result.encrypted3dsPassword.split("\n").slice(1, -2).join(""),
    "utf8"
);

Get Top Up Information

Get top up information like the price, fee, min and max top up amount, etc

POST https://api.card.fina.cash/getTopupInfo

Request Body

interface Response {
    topupAddress: string
    maxTopupAmount: number
    minTopupAmount: number
    initialTopupValue: number
    rate: number
    feeRate: number
    decimals: number
    denom: string
    gasBuffer: number
    gasPrice: number
}

Change 3D Secure Settings

Change 3D Secure settings like mobile number and password

POST https://api.card.fina.cash/change3DS

Request Body

interface Response {
    success: true
}

Toggle Block Card

Block or Unblock card transactions

POST https://api.card.fina.cash/toggleBlockCard

Request Body

interface Response {
    success: true
}

Top Up

Top up card by sending token to the topupAddress returned from /getTopupInfo and call this API with the TX hash to increase card balance.

POST https://api.card.fina.cash/topup

Request Body

interface Response {
    txHash: string
    topupValue: number
    currency: string
    timestamp: number
}

Create New Card

Create a new card for new user

POST https://api.card.fina.cash/createCard

Request Body

interface Response {
    txHash: string
    topupValue: number
    currency: string
    timestamp: number
}

Last updated