🖥️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

Name	Type	Description
signature*	String	Message to sign: Fina Card: Sign In
address*	String	User's bech32 address
pubKey*	String	User's base64 encoded public key
chainId*	String	Chain ID

200: OK

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
        }[]
    }[]
}

400: Bad Request Missing parameters

interface Response {
    success: false
    message: "invalid request"
}

401: Unauthorized User does not exist or incorrect signature

interface Response {
    success: false
    message: "unauthorized"
}

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

Name	Type	Description
signature*	String	Message to sign: Fina Card: View Sensitive Information at {{ISO Timestamp}}
address*	String	User's bech32 address
pubKey*	String	User's base64 encoded public key
chainId*	String	Chain ID
timestamp*	String	ISO Timestamp, eg 2023-03-31T13:12:36.128Z
rsaPubKey*	String	A base64 encoded RSA public key used to encrypt the sensitive information

200: OK

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"
);

400: Bad Request Missing parameters

interface Response {
    success: false
    message: "invalid request"
}

401: Unauthorized Incorrect signature or signature expired

interface Response {
    success: false
    message: "unauthorized"
}

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

Name	Type	Description
signature*	String	Message to sign: Fina Card: Sign In
address*	String	User's bech32 address
pubKey*	String	User's base64 encoded public key
chainId*	String	Chain ID

200: OK

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

400: Bad Request Missing parameters

interface Response {
    success: false
    message: "invalid request"
}

401: Unauthorized User does not exist or incorrect signature

interface Response {
    success: false
    message: "unauthorized"
}

Change 3D Secure Settings

Change 3D Secure settings like mobile number and password

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

Request Body

Name	Type	Description
signature*	String	Message to sign: Fina Card: Change 3DS Settings at {{ISO Timestamp}}
address*	String	User's bech32 address
pubKey*	String	User's base64 encoded public key
chainId*	String	Chain ID
timestamp*	String	ISO Timestamp, eg 2023-03-31T13:12:36.128Z
password	String	New 3D Secure password
mobile	String	New 3D Secure mobile number

200: OK

interface Response {
    success: true
}

400: Bad Request Missing parameters

interface Response {
    success: false
    message: "invalid request"
}

401: Unauthorized User does not exist or incorrect signature

interface Response {
    success: false
    message: "unauthorized"
}

Toggle Block Card

Block or Unblock card transactions

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

Request Body

Name	Type	Description
signature*	String	Message to sign: Fina Card: Toggle Block Card at {{ISO Timestamp}}
address*	String	User's bech32 address
pubKey*	String	User's base64 encoded public key
chainId*	String	Chain ID
timestamp*	String	ISO Timestamp, eg 2023-03-31T13:12:36.128Z

200: OK

interface Response {
    success: true
}

400: Bad Request Missing parameters

interface Response {
    success: false
    message: "invalid request"
}

401: Unauthorized User does not exist or incorrect signature

interface Response {
    success: false
    message: "unauthorized"
}

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

Name	Type	Description
signature*	String	Message to sign: Fina Card: Sign In
address*	String	User's bech32 address
pubKey*	String	User's base64 encoded public key
chainId*	String	Chain ID
topupAsset*	String	Token symbol used to top up. eg, SCRT
currency*	String	Currency to top up the card. eg, EUR
txHash*	String	TX hash of your top up
encryptionKey*	String	Encryption key used to encrypt transaction on Secret Network

200: OK

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

400: Bad Request Missing parameters

interface Response {
    success: false
    message: "invalid request"
}

401: Unauthorized User does not exist or incorrect signature

interface Response {
    success: false
    message: "unauthorized"
}

Create New Card

Create a new card for new user

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

Request Body

Name	Type	Description
signature*	String	Message to sign: Fina Card: Sign In
address*	String	User's bech32 address
pubKey*	String	User's base64 encoded public key
chainId*	String	Chain ID
topupAsset*	String	Token symbol used in initial top up. eg, SCRT
currency*	String	Currency to top up the card. eg, EUR
txHash*	String	TX hash of your initial top up
name*	String	Name on your card
mobile*	String	3D Secure mobile number
password*	String	3D Secure password
encryptionKey*	String	Encryption key used to encrypt transaction on Secret Network

200: OK

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

400: Bad Request Missing parameters

interface Response {
    success: false
    message: "invalid request"
}

401: Unauthorized User does not exist or incorrect signature

interface Response {
    success: false
    message: "unauthorized"
}

403: Forbidden Account already existed

interface Response {
    success: false
    message: "account already exist"
}