Part 2: API Reference

Introduction

This API (or Application Programming Interface) reference is a set of rules and protocols that defines how a 3rd party project can interact and exchange data with Fiat24 services.

These APIs extends the smart contract functions to access off-chain data.

Rate Limit

To protect our API from misuse, we enforce rate limits on our endpoints. The basic rule is: the more active users you have, the greater API capacity we provide. Below are the tier details:

  • 500 calls/minute for the projects with 20,000+ active users

  • 250 calls/minute for the projects with 5,000+ active users

  • 80 calls/minute for the rest of projects

The rate will be re-evaluated on a weekly basis, typically on Fridays.

Secured APIs

If an API accesses a user’s profile or performs modifications, it must be secured.

Fiat24 does NOT use any standard protocol for authentication and authorisation. All secured requests need to have a header with signed information by the NFT addresss, which guarantees only the end-user can access his/her data.

The header body is structured as follows: 

const headers = {
    "Content-Type"  : "application/json",
    
    tokenid         : <token id of user>,
    network         : 42161,
    
    sign            : <user's wallet signature>,
    hash            : <original text that was hashed>,
    deadline        : <deadline used for signing>
}

The network in header is critical. For example:

  • Requesting /iban/12345 with network=42161 will get CH68 8305 1000 0000 1234 5

  • Requesting /iban/12345 with network=5000 in header will get CH17 8305 1100 0000 1234 5

The fields sign, hash and deadline can be calculated as:

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.

1. Get Client Profile

All those data is very sensitive piece of data and they should be handled and stored with the upmost care.

Get the information about user's NFT account.

Notes:

  • The debitCard field will be set to MSTD when a debit card is eligible; otherwise, it will remain empty

  • limits section extracts the NFT transactional limit from the smart contract

  • depositBank section contains user's Fiat24 IBAN, separately in currencies.

  • contacts section returns a list with all registered Payout bank account details for the given user.

2. Get Cards

Get the Debit Cards information from a user.

Response Body

Important Notices:

  1. If the user doesn't own a card, it returns statusCode = 404.

  2. number, expiry and CVV fields are very sensitive data, they should not be shown without client's consent.

  3. All the limits are monthly (excluding dailyUsed, dailyAvailable, dailyMax) and in EUR.

Showing the Debit Card

The /cards interface does not expose sensitive debit-card data (such as CVV, expiry date). To show the card, call an external fiat24card.js service using the cardToken provided by the /cards interface.

Important:

The cardToken is only valid for 5 minutes (or 300 seconds). When it expires, the card can't be shown again, and it need to generated again.

Currently, we only support Javascript fiat24card.js to integrate the showing card function, and here is the codes.

3. Get Transactions

Get the transactions from a user.

Request Samples:

Mandatory Parameters:

  • currency mandatory as EUR, USD, CHF, CNH, ALL

The value ALL will retrieve transactional data not in real-time, usually 5-15 minutles delay.

Optional Parameters:

  • fromrecord used for paginating (in case we want to do pagination of 10)

  • recordscounts records to retrieve. Also used for paginating

  • fromtimestamp Timestamp to begin

  • totimestamp Timestamp to begin

  • direction Filter the debit or credit transactions, value of IN, OUT, ALL. Default value is ALL

  • type To filter the transactions by types, multiple value possible, separated by comma ','

    • P2P Peer-2-Peer transfer

    • FRX Forex

    • CTU Crypto Top-up

    • CRD Card transactions

    • CDP Cash Deposit

    • CWD Cash Payout

Response Body

The API returns a maximum of 1,000 transactions per request.

Result fields

  1. timestamp is a 10 digits UNIX timestamp,

  2. txId refers to Arbitrum Transaction Hash. More details can be retrieved from Arbiscan.io.

  3. image field will return the image of the sender or the receiver (in case the user is the sender).

  4. from tokenID that sent the transfer

  5. to tokenID that received the transfer

Card Icons

19KB
card-icons.zip
archive
Open

4. Update email

This API enables the secure update of a user's registered email address, a critical function as the email serves as the primary channel for receiving one-time passwords (OTPs) and other sensitive authentication communications. Once validated, the system seamlessly updates the email across all linked services, ensuring uninterrupted delivery of OTPs and essential notifications.

To ensure security, the email requires robust verification—such as multi-factor authentication (MFA) or confirmation via the existing email—before calling this function.

Response

5. Create Card

This API enables the seamless creation of a MasterCard debit card, linked directly to the user’s NFT account.

Response:

6. Change Card Status

This API provides a secure and efficient way to block or unblock a debit card for a specific user, enabling instant control over card activity to prevent unauthorised transactions or reactivate access when needed. The API immediately updates the card’s status, triggering real-time fraud prevention measures or restoring functionality upon request.

Response:

Successfully set the new currency.

7. Unlink digital wallet

This API allows for the secure and immediate deactivation of a digital token associated with a debit card, such as those generated for mobile payment platforms like Apple Pay, Google Pay, or Samsung Pay. When a card is lost, stolen, or compromised, this API ensures that the linked digital token is revoked, preventing unauthorized transactions while keeping the physical card active if needed. The process is automated, reliable, and works across multiple tokenization platforms.

Response:

Successfully set the new currency.

8. Set Default Currency

This API enables users to change the Default Currency for their debit card, providing greater flexibility and convenience for international transactions. This feature helps users avoid unnecessary foreign exchange fees, streamline cross-border spending, and optimize transaction transparency.

Response:

Successfully set the new currency.

9. QR Payment

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:

  1. Swiss QR Bill (QR Rechnung)

  2. SEPA EPC QR

The wallet provider conducts 3 steps to make a QR payment:

1

Verify the QR

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.

2

Call Contract

Call the smart contract clientPayoutRef() and pass the parameters which are provided from last API call.

3

Done

User sign the transaction to finalise the payment.

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:

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.

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().

10. Bank Payout

This section explains how to make a bank payment in EUR or CHF to a supported bank account anywhere in the world. The process involves a few simple steps.

1

Load the bank master data

Developers must load our latest bank master data. The file is a large JSON, so cache it in local storage if possible. Be sure to refresh it periodically—use the lastUpdateAt timestamp field to detect and download the newest version.

At the moment, we don’t support every bank worldwide. However, our list of supported banks is growing, and we currently have around 500 banks in our list.

2

Check the destination bank account format

If the bank is located in an IBAN country, the IBAN format must be validated locally. Below is the Node.js source code for the validation logic.

All following countries, in ISO2 country codes, are IBAN countries.

[AD,AE,AL,AT,AZ,BA,BE,BG,BH,BR,BY,CH,CR,CY,CZ,DE,DK,DO,DZ,EE,EG,ES,FI,FO,FR,GB,GE,GI,GL,GR,GT,HR,HU,IE,IL,IQ,IS,IT,JO,KW,KZ,LB,LC,LI,LK,LT,LU,LV,LY,MC,MD,ME,MK,MR,MT,MU,NL,NO,PK,PL,PS,PT,QA,RO,RS,SA,SC,SE,SI,SK,SM,ST,SV,TG,TL,TN,TR,UA,VA,VG,XK]

3

Obtain the bank data

If the IBAN is valid, you can easily retrieve the bank details from the master bank data. Alternatively, the bank data can be extracted directly from the JSON master file.

Or, if anything wrong,

4

Payment Purpose

User must fill in an integer as purposeId for each bank payout. The values are static and can be get from the following API.

5

Recipient Address

To correctly fill in the recipient’s address, we need high-quality data to avoid failed or returned payments. The consistency between the city/town name and the country is especially important. For example, if an address lists Tokyo with country USA, the payment is very likely to be returned.

We only accept city or town names from our predefined list. As a developer, you need to read this JSON file and provide a dropdown list to your users. This way, users select the country and city from the static data instead of entering them freely.

The response is static, so developers can store the large JSON file locally for faster access. The lastUpdateAt timestamp serves as version information.

The postalCodeRegEx is used to validate postal codes for each country.

6

Construct the Payment Data

Build a JSON data structure that includes all the verified data.

7

Call Smart Contract

Finally, calling the clientPayoutRef() smart contract function will trigger the bank payment. This method is currently available in the EUR24 and CHF24 contracts.

To successfully call the method, you need three parameters: contactId, purposeId, ref. Calling the following API will convert your payment request data into three parameter values.

Response

If something is wrong

Detailed instructions for calling this method can be found here.

8

Done

Once the payment is submitted, it enters the queue. It will be processed during bank operating hours (Monday to Friday, 07:00–17:00 CET, excluding public holidays).

Public APIs

In this section, the following APIs are publicly accessible and do not require a signed header for requests. However, to prevent excessive or abusive usage, we enforce backend safeguards. If too many requests are made within a short time window, the system will temporarily block the activity and return a 500 error response.

1. IBAN

Each Fiat24 NFT has a unique Swiss IBAN, with the ending digits matching the NFT number. 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

From your own script

Or, you can also generate the IBAN with the following code.

2. Country List

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.

Response body providers all ISO-3 countries codes for

  1. Eligible Client Domiciles

  2. Eligible Client Domiciles for obtain a Debit card

  3. Blacklist nationalities

3. Forex rates

Each FX rate includes three values—interbank rate, bid rate, and ask rate—along with a lastUpdatedAt timestamp.

4. KYC Status Check

The following API returns the KYC status of a certain NFT.

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.

5. Email Availability

In Fiat24, each email address can only be associated with a single business relationship. Therefore, an email check must be performed in two scenarios: (1) during registration, and (2) when changing an existing email. This API provides the email check functionality. An email is considered valid only if all response fields return false.

PreviousPart 1: Smart ContractsNextPart 3: Client Onboarding

Last updated