HomeGuidesRecipesAPI ReferenceChangelog
Log In
Guides
These docs are for v2.2.8. Click to read the latest docs for v2.2.9.

Transactions: Fiat-to-Crypto and Crypto-to-Fiat Flows

Unblock API's core functionality revolves around enabling seamless fiat-to-crypto (on-ramp) and crypto-to-fiat (off-ramp) transactions globally. This guide outlines the fundamental processes and key considerations for integrating these core flows into your platform.

Pre-requisites (For both Individuals and Corporates):

  • User/Corporate Onboarding: Ensure the user (Individual) or corporate entity is created within the Unblock system using the appropriate endpoints:

    • Individuals: Use the /user endpoint.
    • Corporates: Use the /corporate endpoint.
  • KYC/KYB Verification: Crucially, KYC verification is mandatory for Individuals and KYB verification is mandatory for Corporates before initiating fiat-to-crypto transactions. The verification process must be successfully completed.

    • Individuals: Refer to the KYC Guide for detailed steps.
    • Corporates: Refer to the KYB Guide for detailed steps.
      No fiat-to-crypto transactions can be processed until the respective KYC or KYB verification is successfully completed and the user/corporate status reflects this.

➡️ Fiat-to-Crypto Transaction Flow:

  1. Setup an Unblock Bank Account:

    • Purpose: A dedicated Unblock bank account (often a Virtual IBAN) is a virtual account provided by Unblock. This account acts as the destination for fiat currency deposits intended for your user (Individual or Corporate). Crucially, these accounts are designed to accept deposits from both the Unblock user's own bank account (1st party) and from third-party sources (3rd party).
    • Action: Use the appropriate endpoint to create an Unblock bank account in the desired fiat currency (e.g., EUR, GBP):
  2. Retrieve Unblock Bank Account Details:

    • Action: After creating the Unblock bank account, retrieve the account details (IBAN, account number, BIC/SWIFT code, etc.) using the appropriate API endpoint: Retrieve Bank Account Details API or Get Corporate Unblock Bank Account API.
    • Information to Provide to User/Corporate: Provide these retrieved Unblock bank account details to your user (Individual or Corporate).
  3. User/Corporate Initiates Fiat Deposit:

    • Action: Instruct the user (individual or corporate) or third party to send fiat to the dedicated Unblock bank account using their preferred payment method (e.g., bank transfer, open banking).
  4. [Sandbox Testing] Simulate Fiat Deposit (Optional - Sandbox Environment Only):

    • Purpose: For testing in the Sandbox environment only, you can simulate an incoming fiat deposit into the user's/corporate's Unblock bank account. This step is not part of the production flow.
    • Action: Use the /simulate endpoint to simulate a fiat deposit.
      curl --request POST  \
              --url 'https://sandbox.getunblock.com/user/bank-account/unblock/{UNBLOCK_BANK_ACCOUNT_UUID}/simulate'  \
              --header 'Authorization: API-Key YOUR_SANDBOX_API_KEY'  \
              --header 'accept: application/json'  \
              --header 'unblock-session-id: YOUR_SESSION_ID' \
              --header 'Content-Type: application/json' \
              --data '{"value": 100}' # Example value, adjust as needed
      Note: Replace {UNBLOCK_BANK_ACCOUNT_UUID} with the actual UUID of the Unblock bank account you created in the Sandbox.
  5. Crypto Conversion & Transfer:

    • Automatic Process: Once the fiat deposit is received in the Unblock bank account (or simulated deposit in Sandbox), Unblock automatically initiates the crypto conversion process.
    • Conversion Logic: The conversion is based on:
    • Crypto Transfer: The converted cryptocurrency is then automatically transferred to the user's/corporate's designated target crypto address that was configured during user/corporate creation or update.
  6. Transaction Webhooks:

    • Real-time Updates: You will receive real-time updates on the transaction status via webhooks.
    • Webhook Events: Key webhook events for fiat-to-crypto transactions include: IN_PROGRESS, CRYPTO_TRANSFER_ISSUED, SUCCESS, ON_HOLD, and FAILED. Understand Webhook Notifications.

⬅️ Crypto-to-Fiat Transactions (Off-Ramping)

Crypto-to-fiat transactions enable users to convert their cryptocurrencies back into fiat currencies and withdraw them to their bank accounts. The process involves:

  1. User Authentication & Wallet Retrieval:

  2. Crypto Transfer to Unblock Wallet:

    • Instruct users to transfer the desired cryptocurrency amount to their retrieved Unblock wallet address.
  3. [Sandbox Testing] Simulate Crypto Deposit:

    • For Sandbox testing only, you will need to manually simulate an incoming crypto deposit to the user's Unblock wallet address. This is typically done by minting test crypto tokens. See the section below for detailed instructions on how to mint test tokens in the Sandbox environment. This step is not part of the production flow.

    Token

    Mumbai

    (Polygon testnet)

    Goerli

    (Optimism testnet)

    Sepolia

    (Arbitrum testnet)

    Alfajores

    (Celo testnet)

    Sepolia

    (Ethereum testnet)

    Shasta

    (Tron testnet)

    USDc Native

    0xc8c86

    0x507D0

    0x53D0d7

    0xe5c957

    USDc.e

    0x7ffae0

    0xece450

    0xf99ea7

    USDT

    0x2f32c5

    0x59dc25

    0xECE450

    0x2efc02

    TSUENfi

    DAI

    0x22a8d4

    0x53d0d7

    0xF83B3C

    0x14ea7e

    cEUR

    0x10c892

Each of these token contracts has a public mint() function that can be used to mint test tokens directly to any wallet of your choice; these tokens can then be used to simulate a cryptoToFiat transfer.

  1. Setup Destination Bank Account:
    • Users need to configure a destination bank account (their external bank account) where they will receive the converted fiat currency.
    • Use the /user/bank-account/remote or /corporate/{corporate_uuid}/bank-account/remote endpoints to allow users to set up their destination bank account details in the desired fiat currency for withdrawal. It's important that the destination bank account currency matches the desired withdrawal currency. Set up Destination Bank Account API or Set up Corporate Destination Bank Account API.
  2. Fiat Conversion & Withdrawal:
    • Upon receiving the crypto transfer, Unblock initiates the fiat conversion and automatically sends the fiat currency to the user's configured destination bank account.
  3. Transaction Webhooks:
    • Similar to fiat-to-crypto, you will receive webhook updates for crypto-to-fiat transactions, including IN_PROGRESS, FIAT_TRANSFER_ISSUED, SUCCESS, ON_HOLD, FAILED, and LIMIT_BREACHED events. Explore Webhook Types

💡 Key Considerations for Transaction Flows

  • KYC Requirements: Understand and implement the necessary Know Your Customer (KYC) procedures, especially for higher transaction values and crypto-to-fiat flows in certain regions. Review KYC Guide
  • Supported Regions & Currencies: Ensure you are aware of the supported regions, currencies, and payment methods for both fiat and crypto transactions. See Supported Coverage
  • Handling Transactions Below Minimum Fee: Be aware that if a configured minimum_fee (set via the Fee Management API) is greater than the user's transaction amount, the transaction will still execute. The minimum_fee will be deducted, resulting in a zero final transfer amount (fiat or crypto). Your application should handle this outcome, potentially by preventing such small transactions upfront or clearly communicating the zero transfer result to the user and via webhooks.
  • Error Handling: Implement robust error handling to manage potential transaction failures, insufficient funds, or compliance-related holds. Utilize webhook notifications for real-time error awareness.
  • Transaction Limits: Be mindful of any minimum transaction values and potential transaction limits that may apply. Check Transaction Limits

By understanding these core transaction flows and integrating with the Unblock API, you can empower your users with seamless and efficient access to global fiat and crypto payments.


What’s Next