This API (or Application Programming Interface) guide is a set of rules and protocols that defines how a 3rd party software can interact and exchange data with Fiat24 banking services.
These APIs extends the smart contract functions in Part 1 to access off-chain data.
Authentication & Access
Fiat24 does NOT use any standard protocol for authentication and authorization. All requests need to have a header with signed information by the NFT holder, which guarantees only the end-user can access his/her data.
To faciliate developer's integration work, we provide the signed header for our demo account #10365.
const headers = {
tokenid: <token id of user>,
network: 42161,
sign: <user's wallet signature>,
hash: <original text that was hashed>,
deadline: <deadline used for signing>,
"Content-Type": "application/json"
}
where:
// We only allow the signature to be valid for 20 minutes max.
// Can be less than that if want more security.
const SIGNATURE_DEADLINE_IN_SECONDS = 1200;
// Alternative to Date.now()
// sometimes the device clock is out of sync and can give the wrong timestamp
const serverTimestamp = await fetch("https://api.fiat24.com/timestamp");
const now = serverTimestamp.timestamp;
const deadline = Math.round(now/1000) + SIGNATURE_DEADLINE_IN_SECONDS;
const hash = "Hello world"; // Could be any text
const deadlineHash = web3.utils.sha3(hash + deadline);
const messageToSign = `I agree to access my profile. ${deadlineHash}`;
// web3.js
const sign = await web3.eth.personal.sign(messageToSign, address)
// ethers
const sign = await signer.signMessage({ message: messageToSign });
return { hash, deadline, sign };
where:
address is the address of the user's wallet.
signer.signMessage is the signatures of the user's wallet personal sign.
Please note that in some programming languages SHA3 function might act a bit different than the web3.utils.sha3(). The SHA3 of a simple text such as SHA3("Fiat24"), should give as a response 0x1cf688cdaa53bf4605bfbb1ab56565651179978e63d41cf2df557d5bb5f1bd90.
Functions
All RESTful interfaces are read-only functions, which retrieve off-chain data from Fiat24's backend system. All those data is very sensitive piece of data and they should be handled and stored with the upmost care.
1. Get Client Profile
Requires Authentication
Get the information about a specific account by NFT ID.
The traditional way to fund user's Fiat24 account is to trigger a bank transfer or wire directly from the customer's account to our bank account in his/her currency. This Bank account detail endpoints are provided for users to fill in bank account details for such a deposit.
In order for us to link this in coming payment with a corresponding Fiat24 client, the individual creating bank transfer need to include specific text in the "payment reference" field. which is always user's token_id.
Payout Bank Account Details
This section returns a list with all registered Payout bank account details for the given user. Account receive options can also include local and international details to receive money on the currency balance.
2. Get Cards
Requires Authentication
Get the VISA Debit Cards information from a user.
Request
GET https://api.fiat24.com/cards
Response Body
If the card is not available, the 500 code is returned.
{
"statusCode" : 500,
"tokenId" : 10365
}
If the card is found, the following data is returned
The API returns a maximum of 1,000 transactions per request.
Result fields
timestamp is a 10 digits UNIX timestamp,
txId refers to Arbitrum Transaction Hash. More details can be retrieved from Arbiscan.io.
image field will return the image of the sender or the receiver (in case the user is the sender).
from tokenID that sent the transfer
to tokenID that received the transfer
Card Icons
4. Get IBAN
Each Fiat24 NFT can map to an unique Swiss IBAN.
For example, the NFT #12345 will own the IBAN of CH6883051000000012345. Wallet Provider can calculate the Swiss IBAN directly from the NFT id with the following request:
From API
GET https://api.fiat24.com/iban/<nftId>
This API is public, a signed header is not required.
Response Body of GET https://api.fiat24.com/iban/12345
{"iban":"CH6883051000000012345"}
From OpenSea API
Or you can get the IBAN as an attribute from OpenSea's metadata.
GET https://api.opensea.io/api/v2/chain/arbitrum/contract/0x133CAEecA096cA54889db71956c7f75862Ead7A0/nfts/<nftId>
Response Body for a NFT id = 12345. The line no. 16 states the IBAN.
Fiat24 currently cannot serve all countries and regions, but we are actively expanding the scope of regions where we can provide our services. The eligible countries are published from our own FAQ, however, we provide the API for wallet providers to check the eligible countries efficiently.
GET https://api.fiat24.com/countries
This API is public, a signed header is not required.
Response body providers all ISO-3 countries codes for
We provide a simple way to enable wallet providers to initialise the QR payments for the end users. Currently, we support the following QR payments:
Swiss QR Bill (QR Rechnung)
SEPA EPC QR
UnionPay QR (Coming in Q4/2024)
The wallet provider conducts 3 steps to make a QR payment:
Scan the QR and read as a string. Call the following URL and pass the string as parameter to get the information of a valid QR.
GET https://api.fiat24.com/verify?qr= QR_STRING
Call the smart contract clientPayoutRef() and pass the parameters which are provided from last API call.
The end user sign the transaction and the payment is done.
Case 1: Swiss QR Bill
A QR-bill is an invoice with an integrated payment part and receipt in Switzerland. The QR-bill replaced the old orange and red payment slips on 30 September 2022.
The upper part of the QR-bill (1) is like a normal invoice; the lower part is divided into two parts just like today's payment slips: the payment part (2) and the receipt (3). The payment part includes the Swiss QR Code (4), which contains all relevant information necessary for both invoicing and payment. A typical QR bill looks like the following:
Here is the sample of request url:
GET https://api.fiat24.com/verify?qr=SPC%0D%0A0200%0D%0A1%0D%0ALI7830174502999200012%0D%0AS%0D%0ARobert%20Schneider%20AG%0D%0AMusterstrasse%0D%0A18%0D%0A9490%0D%0AVaduz%0D%0ALI%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A1949.75%0D%0ACHF%0D%0AS%0D%0AHans%20Mustermann%0D%0AMusterstrasse%0D%0A27a%0D%0A9490%0D%0AVaduz%0D%0ALI%0D%0AQRR%0D%0A210000000003139471430009017%0D%0AAuftrag%20vom%2015.06.2020%0D%0AEPD%0D%0A%2F%2FS1%2F11%2F200427%2F30%2F102673386%2F31%2F200427%2F32%2F7.7%2F40%2F0%3A30
Inside the response body, the line 2 - 20 are information the wallet could show to the end user, indicating the business purpose of this QR code. The line 21 - 27 are the parameter values to call the smart contract function CHF24.clientPayoutRef().
Case 2: SEPA (EPC) QR
The European Payments Council QR Code guidelines define the content of a QR code that can be used to initiate SEPA credit transfer (SCT). These QR code guidelines are used on many invoices and payment requests in the European countries (mostly in Austria, Belgium, Finland, Germany, The Netherlands) .
Usually, SEPA QR has no fixed layout, it can be placed anywhere in an invoice or bill.
Here is the sample of request url:
GET https://api.fiat24.com/verify?qr=BCD%0A001%0A1%0ASCT%0ANTSBDEB1XXX%0ABlueRabbIT%0ADE59100110012628958324%0AEUR1043.62%0A%0A%0AInvoice%20%23%2016%20Customer%20%23%201%201st%20January%202021%0A
Inside the response body, the line 2 - 14 are information the wallet could show to the end user, indicating the business purpose of this QR code. The line 15 - 21 are the parameter values to call the smart contract function EUR24.clientPayoutRef().
8. KYC Status Check
The following API returns the KYC status of a certain NFT.
GET https://api.fiat24.com/status-kyc?id=NFT_ID
The response code can be easily referred as:
NOT_INIT : KYC has not been started yet.
CA_COMPLETED_PENDING_SCAN : First part registration completed, ready for ID scan step.
PROCESSING_SCAN : User scanned the passport, waiting to process the information (around 15-20 seconds), after that user will become either: MANUAL_REVIEW, COMPLETED or REJECTED.
PENDING_ACTION : Client needs action to finish the KYC, for example the passport has not been scanned yet, or has been scanned but user needs to re-do it, or needs to re-add address.
COMPLETED : The KYC has been successfully done, the client is in live status.
MANUAL_REVIEW : The KYC has been submitted, but due to regulatory reason, it's under manual review phase.
REJECTED : The KYC has been submitted, but rejected by compliance. Due to regulatory reason or company policy, we cannot serve the client.
INTERNAL_ERROR : Unknown system error. When the NFT is not minted, you will have such status as well.
9. Payment Purposes
The following API returns the Payment Purposes for the ClientPayoutRef
GET https://api.fiat24.com/payment-purposes
Response sample:
{"purposes":[{"value":1,"name":"Purchase of goods"},{"value":2,"name":"Payment for services (leisure, medical, travel, education, insurance, telecom, etc.)"},{"value":3,"name":"Family support and inheritance"},{"value":4,"name":"Charity donation"},{"value":5,"name":"Salary, Benefits, Dividends"},{"value":6,"name":"Real Estate and rent"},{"value":7,"name":"Credit / debit card coverage"},{"value":8,"name":"Investment, securities, trading"},{"value":9,"name":"Currency exchange"},{"value":10,"name":"Tax and governmental payments"},{"value":11,"name":"Loan, Collateral"}]}
