# 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](https://github.com/cosmos/cosmos-sdk/blob/master/docs/architecture/adr-036-arbitrary-signature.md) signature. The message required in each API method is different. Here is an Javascript example of using Keplr to generate the signature.

```typescript
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.

```typescript
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

<mark style="color:green;">`POST`</mark> `https://api.card.fina.cash/getAccount`

#### Request Body

| Name                                        | Type   | Description                                                   |
| ------------------------------------------- | ------ | ------------------------------------------------------------- |
| signature<mark style="color:red;">\*</mark> | String | <p>Message to sign:</p><p><code>Fina Card: Sign In</code></p> |
| address<mark style="color:red;">\*</mark>   | String | User's bech32 address                                         |
| pubKey<mark style="color:red;">\*</mark>    | String | User's base64 encoded public key                              |
| chainId<mark style="color:red;">\*</mark>   | String | Chain ID                                                      |

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}

{% tab title="400: Bad Request Missing parameters" %}

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

{% endtab %}

{% tab title="401: Unauthorized User does not exist or incorrect signature" %}

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

{% endtab %}
{% endtabs %}

### Get Sensitive Information

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

<mark style="color:green;">`POST`</mark> `https://api.card.fina.cash/getSensitiveInfo`

#### Request Body

| Name                                        | Type   | Description                                                                                           |
| ------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------- |
| signature<mark style="color:red;">\*</mark> | String | <p>Message to sign:</p><p><code>Fina Card: View Sensitive Information at {{ISO Timestamp}}</code></p> |
| address<mark style="color:red;">\*</mark>   | String | User's bech32 address                                                                                 |
| pubKey<mark style="color:red;">\*</mark>    | String | User's base64 encoded public key                                                                      |
| chainId<mark style="color:red;">\*</mark>   | String | Chain ID                                                                                              |
| timestamp<mark style="color:red;">\*</mark> | String | ISO Timestamp, eg `2023-03-31T13:12:36.128Z`                                                          |
| rsaPubKey<mark style="color:red;">\*</mark> | String | A base64 encoded RSA public key used to encrypt the sensitive information                             |

{% tabs %}
{% tab title="200: OK " %}

```typescript
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:

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

{% endtab %}

{% tab title="400: Bad Request Missing parameters" %}

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

{% endtab %}

{% tab title="401: Unauthorized Incorrect signature or signature expired" %}

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

{% endtab %}
{% endtabs %}

### Get Top Up Information

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

<mark style="color:green;">`POST`</mark> `https://api.card.fina.cash/getTopupInfo`

#### Request Body

| Name                                        | Type   | Description                                                   |
| ------------------------------------------- | ------ | ------------------------------------------------------------- |
| signature<mark style="color:red;">\*</mark> | String | <p>Message to sign:</p><p><code>Fina Card: Sign In</code></p> |
| address<mark style="color:red;">\*</mark>   | String | User's bech32 address                                         |
| pubKey<mark style="color:red;">\*</mark>    | String | User's base64 encoded public key                              |
| chainId<mark style="color:red;">\*</mark>   | String | Chain ID                                                      |

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}

{% tab title="400: Bad Request Missing parameters" %}

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

{% endtab %}

{% tab title="401: Unauthorized User does not exist or incorrect signature" %}

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

{% endtab %}
{% endtabs %}

### Change 3D Secure Settings

Change 3D Secure settings like mobile number and password

<mark style="color:green;">`POST`</mark> `https://api.card.fina.cash/change3DS`

#### Request Body

| Name                                        | Type   | Description                                                                                    |
| ------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------- |
| signature<mark style="color:red;">\*</mark> | String | <p>Message to sign:</p><p><code>Fina Card: Change 3DS Settings at {{ISO Timestamp}}</code></p> |
| address<mark style="color:red;">\*</mark>   | String | User's bech32 address                                                                          |
| pubKey<mark style="color:red;">\*</mark>    | String | User's base64 encoded public key                                                               |
| chainId<mark style="color:red;">\*</mark>   | String | Chain ID                                                                                       |
| timestamp<mark style="color:red;">\*</mark> | String | ISO Timestamp, eg `2023-03-31T13:12:36.128Z`                                                   |
| password                                    | String | New 3D Secure password                                                                         |
| mobile                                      | String | New 3D Secure mobile number                                                                    |

{% tabs %}
{% tab title="200: OK " %}

```typescript
interface Response {
    success: true
}
```

{% endtab %}

{% tab title="400: Bad Request Missing parameters" %}

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

{% endtab %}

{% tab title="401: Unauthorized User does not exist or incorrect signature" %}

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

{% endtab %}
{% endtabs %}

### Toggle Block Card

Block or Unblock card transactions

<mark style="color:green;">`POST`</mark> `https://api.card.fina.cash/toggleBlockCard`

#### Request Body

| Name                                        | Type   | Description                                                                                  |
| ------------------------------------------- | ------ | -------------------------------------------------------------------------------------------- |
| signature<mark style="color:red;">\*</mark> | String | <p>Message to sign:</p><p><code>Fina Card: Toggle Block Card at {{ISO Timestamp}}</code></p> |
| address<mark style="color:red;">\*</mark>   | String | User's bech32 address                                                                        |
| pubKey<mark style="color:red;">\*</mark>    | String | User's base64 encoded public key                                                             |
| chainId<mark style="color:red;">\*</mark>   | String | Chain ID                                                                                     |
| timestamp<mark style="color:red;">\*</mark> | String | ISO Timestamp, eg `2023-03-31T13:12:36.128Z`                                                 |

{% tabs %}
{% tab title="200: OK " %}

```typescript
interface Response {
    success: true
}
```

{% endtab %}

{% tab title="400: Bad Request Missing parameters" %}

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

{% endtab %}

{% tab title="401: Unauthorized User does not exist or incorrect signature" %}

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

{% endtab %}
{% endtabs %}

### 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.

<mark style="color:green;">`POST`</mark> `https://api.card.fina.cash/topup`

#### Request Body

| Name                                            | Type   | Description                                                   |
| ----------------------------------------------- | ------ | ------------------------------------------------------------- |
| signature<mark style="color:red;">\*</mark>     | String | <p>Message to sign:</p><p><code>Fina Card: Sign In</code></p> |
| address<mark style="color:red;">\*</mark>       | String | User's bech32 address                                         |
| pubKey<mark style="color:red;">\*</mark>        | String | User's base64 encoded public key                              |
| chainId<mark style="color:red;">\*</mark>       | String | Chain ID                                                      |
| topupAsset<mark style="color:red;">\*</mark>    | String | Token symbol used to top up. eg, `SCRT`                       |
| currency<mark style="color:red;">\*</mark>      | String | Currency to top up the card. eg, `EUR`                        |
| txHash<mark style="color:red;">\*</mark>        | String | TX hash of your top up                                        |
| encryptionKey<mark style="color:red;">\*</mark> | String | Encryption key used to encrypt transaction on Secret Network  |

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}

{% tab title="400: Bad Request Missing parameters" %}

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

{% endtab %}

{% tab title="401: Unauthorized User does not exist or incorrect signature" %}

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

{% endtab %}
{% endtabs %}

### Create New Card

Create a new card for new user

<mark style="color:green;">`POST`</mark> `https://api.card.fina.cash/createCard`

#### Request Body

| Name                                            | Type   | Description                                                   |
| ----------------------------------------------- | ------ | ------------------------------------------------------------- |
| signature<mark style="color:red;">\*</mark>     | String | <p>Message to sign:</p><p><code>Fina Card: Sign In</code></p> |
| address<mark style="color:red;">\*</mark>       | String | User's bech32 address                                         |
| pubKey<mark style="color:red;">\*</mark>        | String | User's base64 encoded public key                              |
| chainId<mark style="color:red;">\*</mark>       | String | Chain ID                                                      |
| topupAsset<mark style="color:red;">\*</mark>    | String | Token symbol used in initial top up. eg, `SCRT`               |
| currency<mark style="color:red;">\*</mark>      | String | Currency to top up the card. eg, `EUR`                        |
| txHash<mark style="color:red;">\*</mark>        | String | TX hash of your initial top up                                |
| name<mark style="color:red;">\*</mark>          | String | Name on your card                                             |
| mobile<mark style="color:red;">\*</mark>        | String | 3D Secure mobile number                                       |
| password<mark style="color:red;">\*</mark>      | String | 3D Secure password                                            |
| encryptionKey<mark style="color:red;">\*</mark> | String | Encryption key used to encrypt transaction on Secret Network  |

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}

{% tab title="400: Bad Request Missing parameters" %}

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

{% endtab %}

{% tab title="401: Unauthorized User does not exist or incorrect signature" %}

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

{% endtab %}

{% tab title="403: Forbidden Account already existed" %}

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

{% endtab %}
{% endtabs %}