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.
Copy 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.
Copy 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
200: OK 400: Bad Request Missing parameters 401: Unauthorized User does not exist or incorrect signature
Copy 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
}[]
}[]
}
Copy interface Response {
success : false
message : "invalid request"
}
Copy 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
200: OK 400: Bad Request Missing parameters 401: Unauthorized Incorrect signature or signature expired
Copy 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:
Copy 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"
);
Copy interface Response {
success : false
message : "invalid request"
}
Copy 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
200: OK 400: Bad Request Missing parameters 401: Unauthorized User does not exist or incorrect signature
Copy interface Response {
topupAddress : string
maxTopupAmount : number
minTopupAmount : number
initialTopupValue : number
rate : number
feeRate : number
decimals : number
denom : string
gasBuffer : number
gasPrice : number
}
Copy interface Response {
success : false
message : "invalid request"
}
Copy 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
200: OK 400: Bad Request Missing parameters 401: Unauthorized User does not exist or incorrect signature
Copy interface Response {
success : true
}
Copy interface Response {
success : false
message : "invalid request"
}
Copy interface Response {
success : false
message : "unauthorized"
}
Toggle Block Card
Block or Unblock card transactions
POST
https://api.card.fina.cash/toggleBlockCard
Request Body
200: OK 400: Bad Request Missing parameters 401: Unauthorized User does not exist or incorrect signature
Copy interface Response {
success : true
}
Copy interface Response {
success : false
message : "invalid request"
}
Copy 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
200: OK 400: Bad Request Missing parameters 401: Unauthorized User does not exist or incorrect signature
Copy interface Response {
txHash : string
topupValue : number
currency : string
timestamp : number
}
Copy interface Response {
success : false
message : "invalid request"
}
Copy 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
200: OK 400: Bad Request Missing parameters 401: Unauthorized User does not exist or incorrect signature 403: Forbidden Account already existed
Copy interface Response {
txHash : string
topupValue : number
currency : string
timestamp : number
}
Copy interface Response {
success : false
message : "invalid request"
}
Copy interface Response {
success : false
message : "unauthorized"
}
Copy interface Response {
success : false
message : "account already exist"
}