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):
     • Individuals: Use the /user/bank-account/unblock endpoint. See Create Unblock Bank Account API
     • Corporates: Use the /corporate/{corporate_uuid}/bank-account/unblock endpoint. See Create Corporate Unblock Bank Account API.

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. The value in the request body is the example deposit amount (adjust as needed).

     Bash

     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 'bakkt-session-id: YOUR_SESSION_ID' \
       --header 'Content-Type: application/json' \
       --data '{"value": 100}'

     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:
     • The user's/corporate's pre-configured token preferences (if set). Explore Token Preferences API or Explore Corporate Token Preferences API.
     • Current exchange rates. Explore Exchange Rate API.
   • 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:

   • Ensure the user is authenticated and has a valid session ID. Learn about Authentication.
   • Retrieve the user's Unblock crypto wallet address for the desired blockchain network using the /wallet endpoint. Get User Wallet API

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	Amoy (Polygon testnet)	Sepolia (Optimism testnet)	Sepolia (Arbitrum testnet)	Alfajores (Celo testnet)	Sepolia (Ethereum testnet)	Sepolia (Base testnet)	Shasta (Tron testnet)	Solana Devnet	Avalanche testnet
   USDc Native	0xDc1d5	0x7E6FD	0x7E6FD		0x196FF	0x7E6FD		8T3Km	0x7E6FD
   USDc.e	0xA6B68	0x0b6b	0x0b6bb
   USDT	0x5A96	0x0ccC7	0x0ccC7		0x2F220		TMbsA	CwdGG	0x0ccC7
   cUSD				0x2D91e
   cEUR				0xa248F9	0x58129
   EURa			0x512c5

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.
On Avalanche testnet, calling mint() requires sending ceil(amount) * 1 gwei in AVAX.

4. 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.
5. 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.
6. 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
• USD Transaction Requirements: For both on-ramping and off-ramping USD, the user must be a US resident and have completed the specific US KYC process, including providing their SSN. See our KYC guide for details.
• 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.