Developer Guide
  • Fiat24 for Developers
  • Integration Guide
    • Part 1: Smart Contracts
    • Part 2: RESTful APIs
    • Part 3: Managing Client Information
    • Part 4: Dune Reporting
    • Part 5: Authorized Access Model
  • MasterCard Design Guide
  • Terms & Conditions - Partners
  • Release Notice
    • 2025-02-01
    • 2024-12-12
    • 2024-12-02
    • 2023-10-01
    • 2023-10-16
    • 2023-12-11
Powered by GitBook

© Fiat24. All rights reserved.

On this page
  • 1. Client Onboarding
  • Using ID module
  • Using API Integration
  • 2. Manage Client Profile
  • Using ID module
  • Using API Integration
  1. Integration Guide

Part 3: Managing Client Information

For individual clients only

PreviousPart 2: RESTful APIsNextPart 4: Dune Reporting

Last updated 1 day ago

Client Information is the key asset from Fiat24 and is also very sensitve data which can cause irrevocable damage to the client.

1. Client Onboarding

Using ID module

Only for 4-Digit and 3-Digit Developer NFT projects.

This guide illustrates how Fiat24 separately manages the client information in a dedicated site id.fiat24.com.

https://id.fiat24.com/login?wallet=<walletTokenId>

The parameter walletTokenId needs to be added in case you want to customise the Login Page with your colors and name

Our onboarding process involves several steps to verify the identity of the customer and ensure that they meet the Swiss KYC/AML requirements to open an account with Fiat24. Here is a general overview of the onboarding process with us:

To start the onboarding process, the customer must own a Fiat24 NFT from www.fiat24.com or OpenSea shop. The NFT must be not verified before (NFT.status = 2).

  1. Check Profile This step check the eligibility of the client to open the account with Fiat24. It involves domicile and nationality check, preconditional risk questionaires and collect client's email and phone number. Fiat24 conducts background checks on the customer to verify their profile and ensure that they meet our requirements to open an account.

  2. Check Address We comply with Swiss regulation to verify user's residential address by GPS location. This step should be done within the browsers such as Chrome or Safari, but not the browser inside the crypto wallet, which usually disabled the Location Services for better safety. According the related regulation, the user must be within 2 km from the given address.

  3. Scan Passport Fiat24 will verify the user's identity by asking for the passport scan. The user need to hold a NFC chip enabled passport to confirm their identity. User need to download the ePassport app ReadID Ready and scan the generated QR code to continue.

Once the customer's identity has been verified and their background checks have been completed, Fiat24 will set up their account. It will take from minutes to maximal 2 business days.

Once the client has completed the onboarding process and their account has been funded, they can start using the Fiat24's services, such as making deposits, withdrawing funds, and conducting transactions.

Using API Integration

Only for 2-Digit and 1-Digit Developer NFT projects.

Using API to deliver onboarding client data are restricted functions exclusively available to internal, trusted systems, ensuring that only authorised applications and users can access sensitive operations or data.

POST https://api.fiat24.com/register

Request Body

Request Body
{
    "chainId"  : 5000,
    "nftId"    : 10365,
    "email"    : "sample@gmail.com",
    "profile"  : {
      "annualSalary": "B2",                // Single item (SALARIES)
      "totalAssets": "B1",                 // Single item (TOTAL_ASSETS)
      "mainOccupation": "EMP",              // Single item (OCCUPATIONS)
      "jobCategory": "EEE",                // Single item (JOB_CATEGORIES)
      "sector": "ACC",                     // Single item (SECTORS_MAPPING)
      "sourceOfFunds": "SAV",              // Single item (SOURCE_OF_FUNDS)
      "purposes": "SLR,PNS,IVT,FRX,TUP",   // List separated by comma of Purposes (PURPOSES_LIST)
      "signature": "0x.........",              // TAN signature using wallet
      "tanAddress": "0x....",                  // User's address used during signature
      "tanDateMs":  123212312321               // Timestamp when user signed in ms
    },
    "address"  : {
      "countryISO3": "CHE",       // Country ISO3 input by user
      "street": "Sample Street",  // Street input by user
      "streetNumber": "123",      // Street number input by user
      "postalCode": "12345",             // Zip input by user
      "city": "Zürich",           // City input by user
      "gps": { "lat": 47.35055383741818, "lng": 8.560838999296362 },    // GPS of the input location
      "addressProof": { "lat": 47.35055383741818, "lng": 8.560838999296362 }, // Current user coordinates
      "reverseAddresProof": "Bellerivestrasse 245, Zurich 8008, Switzerland", // Reverse location using current user coordinates.
      "distance": 0.1             // Distance between the two GPS points (in KM)
    },
    "id" : {
      "gender": "M", // "M" or "F"
      "firstName": "James", // Latin
      "lastName": "Bond", // Latin
      "nameOfHolder" : "詹姆斯·邦德", // First Name + Last Name in original language
      "birthday": "27.06.1991",
      "documentNumber": "ABCDE1234",
      "documentType": "I", // "P", "I" (Passport or ID)
      "documentValidUntil": "27.06.2099",
      "issuerCountry": "CHE",
      "nationality": "CHE"
    },
    "files" : {
      "clientProfilePdfUrl": "<url_to_sumsub_or_similar_pdf>",
      "idVerificationPdfUrl": "<url_to_sumsub_or_similar_pdf>"
    }
}

Response

The registration information has been submitted successfully, and all requirements have been met. Therefore, the client has been successfully accepted.

Response Body
{
    "status": 200,
    "data": {
        "status": "OK"
    }
}

The registration information has been submitted successfully, but it does not qualify as a client due to company policy.

Response Body
{
    "status": 200,
    "data": {
        "status": "NOK"
    }
}

The registration information has been submitted successfully. However, due to specific reasons, the application requires manual review

Response Body
{
    "status": 200,
    "data": {
        "status": "REVIEW"
    }
}

If an error occurs on the server side, a 500 error code will be returned.

Response Body
{
    "status": 500
}

Reference values from the Request Body

Many fields in the request JSON body are enumerated values. The following JavaScript code provides a reference for all possible values.

Field values
const OCCUPATIONS = [
  { value: "EMP", name: "Employed" },
  { value: "SLF", name: "Self-employed / Freelancer" },
  { value: "RET", name: "Retired / Pension recipient" },
  { value: "STU", name: "Trainee / Student" },
  { value: "LOS", name: "Unemployed" }
];

const JOB_CATEGORIES = [
  { value: "EEE", name: "Employee" },
  { value: "MNG", name: "Manager" },
  { value: "CLV", name: "C-Level / Executive Board" },
  { value: "DIR", name: "Director / Member of the Management Board" }
];

const PURPOSES_LIST = [
  { value: "SLR", name: "Salary account" },
  { value: "EXP", name: "Living expenses" },
  { value: "PNS", name: "Savings / Pension" },
  { value: "PTP", name: "Peer-to-peer payments" },
  { value: "IVT", name: "Investments" },
  { value: "FRX", name: "Money exchange" },
  { value: "TUP", name: "Crypto top-up" }
]

const SOURCE_OF_FUNDS = [
  { value: "SAV", name: "Savings and Pension" },
  { value: "BIZ", name: "Own business operations or salary" },
  { value: "ERB", name: "Inheritance" },
  { value: "INV", name: "Capital gain from traditional investments" },
  { value: "DIG", name: "Digital Asset Investment" },
  { value: "REA", name: "Capital gain from real estate" },
  { value: "RUL", name: "Compensation from legal rulings" }
];

const SECTORS_MAPPING = {
  "ACC": "Accountancy",
  "ADM": "Administrative / HR / Recruitment",
  "SEX": "Adult Entertainment / Dating Business",
  "AGR": "Agriculture / Forestry / Fishing",
  "NUC": "Atomic/Nuclear-related",
  "ANT": "Arts and Antiques Dealer",
  "BRK": "Broker / Dealer",
  "CAS": "Casinos / Gambling and connected (all forms)",
  "TSM": "Catering and Restaurants / Hotel industry / Cleaning",
  "NGO": "Charities and Social services / NGO / Religious or political organisations",
  "BAU": "Construction / Real Estate",
  "BTC": "Crypto Exchange / Broker",
  "ART": "Culture / Entertainment / Theme parks ",
  "EDU": "Education",
  "WTR": "Electricity / Water Supply / Sewage / Waste Management",
  "EMG": "Emergency Serving",
  "BNK": "Financial Services - Retail Banking",
  "PBK": "Financial Services - Private Banking",
  "FIN": "Financial Services - Foreign Exchange Dealer",
  "ISU": "Financial Services - Insurance",
  "MTA": "Financial Services - Payment Services",
  "TRA": "Financial Services – Regulated money transfer agent",
  "GOV": "Government / Public Administration / Defence",
  "MED": "Healthcare / Medical",
  "INT": "Information Technology",
  "JEW": "Jewellery incl. All Precious Stones and Metals",
  "LAW": "Legal",
  "MAN": "Manufacturing excl. tobacco",
  "MKT": "Marketing / Media / Communications / Social media",
  "MIN": "Mining and Quarrying",
  "FAR": "Pharmaceuticals",
  "OIL": "Oils and Gas",
  "TBK": "Tobacco",
  "SAL": "Retail sales excl. tobacco",
  "RUB": "Rubber and Plastic",
  "DEV": "Science / Engineering / Technology",
  "WEL": "Sports and Wellness",
  "SCW": "Social Work",
  "TSP": "Transportation and Storage",
  "WPN": "Weapon or Armament manufacturing and trade",
};

const NON_ALLOWED_SECTORS = [
  "SEX", "ANT", "NUC", "BRK", "CAS", "NGO", "CRYPTO_CURRENCY", "EMG", "PBK", "FIN", "ISU", "TRA", "MTA", "GOV", "JEW", "MIN", "OIL", "FAR", "SCW", "TBK", "TSP", "WPN"
];

const SALARIES = {
  "B1": "under 50'000",
  "B2": "50'000 - 100'000",
  "B3": "100'000 - 500'000",
  "B4": "500'000 - 1'000'000",
  "B5": "over 1'000'000",
}

const TOTAL_ASSETS = {
  "B1": "under 100'000",
  "B2": "100'000 - 500'000",
  "B3": "500'000 - 1'000'000",
  "B4": "1'000'000 - 10'000'000",
  "B5": "over 10'000'000"
}

2. Manage Client Profile

Fiat24 NFT holders are responsible for keeping their personal information up to date. This section introduces two methods for viewing and updating client and debit card information.

Fiat24 enables all developer projects, regardless of their Developer NFT digits, to access both the ID module and API integration for managing client and debit card information.

Using ID module

Here is the procedure for users to update the information.

  1. Connect to https://id.fiat24.com Log in to the dapp with the wallet address holding the Fiat24 NFT. If the NFT is in any verifed status, such as Live, the client will successfully log into the portal. Once the client is logged in, navigate to the Identity section from the menu bar.

  2. Update the personal information In the Identity section, the client can update her/his email address, phone number, and other personal details.

  3. Managing the Debit Card Storing our Debit Card data securely is extremely important in order to protect the financial information and prevent unauthorized access or fraud to Fiat24 users. This information can include the card number, expiration date, CVV code, and in some cases, the name and address. If this information falls into the wrong hands, it can be used to make unauthorized purchases or gain access to your bank account. When the clients log into https://id.fiat24.com and go to the Debit Card section, she/he can:

    1. See the complete card information All card information is displayed here, include card holder name, card number, expiry and CVV.

    2. Limit management Client can see all limits applied to the card, include daily limits, weekly limits, monthly limits and single transaction limits. Above them, we offer an overall budget level limit to be approved by the user with their signature of the crypto wallet. The default value is 5000 EUR. The budget approval button is marked in orange below.

    3. Control the card Clients are able to enable or disable the card the card

Using API Integration

Modify email address

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. To ensure security, the API requires robust verification—such as multi-factor authentication (MFA) or confirmation via the existing email—before processing any changes. Once validated, the system seamlessly updates the email across all linked services, ensuring uninterrupted delivery of OTPs and essential notifications.

PUT https://api.fiat24.com/email
Request Body, to ask for OTP
{
  "email" : "sample@hotmail.com"
}

Email format is ok, and there is no duplication.

Response with OTP code
{
  "statusCode" : 200
  "email"      : "sample@hotmail.com",
  "otp"        : "P98TY3",
  "expiry"     : 1748675004
}

The email is not acceptable.

Reponse Body
{
  "statusCode" : 401
}

Once successfully get the OTP, call the API again with it, before it expires.

Request Body, to verify OTP
{
  "email" : "sample@hotmail.com",
  "otp"   : "P98TY3"
}

Response

Successfully updated the new email.

Response Body
{
  "statusCode" : 200
}

Email fails to be updated.

Response Body
{
  "statusCode" : 401
}

Fail to update email, the sent OTP has been expired.

Response Body
{
  "statusCode" : 408
}

This API enforces strict email uniqueness validation, ensuring that no single email address can be registered to multiple user accounts. When a user attempts to update their email, the system automatically checks for duplicates—rejecting the new email immediately if it is already associated with an existing account. This prevents individuals from linking the same email to multiple profiles, maintaining data integrity and reducing the risk of fraud or account misuse. By enforcing a one-email-per-account rule, the API enhances security, simplifies user management, and ensures that critical communications—such as OTPs and notifications—are delivered exclusively to the intended recipient.

Create Debit Card

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

POST https://api.fiat24.com/card
Request Body
{
    // No data required
} 

Response:

Successfully set the new currency.

Response Body
{

}

Fail to set the currency.

Response Body
{

}

Change Debit 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 unauthorized 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. The API ensures compliance with banking regulations while offering seamless integration with existing systems for automated or manual card management.

POST https://api.fiat24.com/card-status
Request Body
{
  "statusChange" : "block", // "block", "unblock"
  "externalId"   : "XXXXXX" // "card.externalId"
}

Response:

Successfully set the new currency.

Response Body
{

}

Fail to set the currency.

Response Body
{

}

Deactivate digital token

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.

POST https://api.fiat24.com/card-device-token
Request Body
{
  "statusChange" : "deactivate", // "activate", "deactivate"
  "cardTokenId"  : "XXXXXX", // "card.activeTokens[].id"
  "externalId"   : "XXXXXX", // "card.externalId"
}

Response:

Successfully set the new currency.

Response Body
{

}

Fail to set the currency.

Response Body
{

}

Change Debit Card Default Currency

This API enables users to change the Default Currency for their debit card, providing greater flexibility and convenience for international transactions. The API updates the card’s settings in real-time, ensuring that future purchases or online payments are automatically processed in the preferred currency, when the Direct Pay balance is insufficient.

This feature helps users avoid unnecessary foreign exchange fees, streamline cross-border spending, and optimize transaction transparency.

PUT https://api.fiat24.com/card-currency
Request Body
{
  "currency"   : "EUR",     // "EUR, USD, CNH, CHF"
  "externalId" : "XXXXXX",  // "card.externalId"
}

Response:

Successfully set the new currency.

Response Body
{

}

Fail to set the currency.

Response Body
{

}

Blabla

Debit Card - Details
Debit Card - Limits
Debit Card - Security