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:

Setup an Unblock Bank Account:
- Purpose: An Unblock bank account is a virtual account provided by Unblock. This account acts as the destination for the fiat currency deposit from your user (Individual or Corporate). It is where Unblock receives the fiat currency to initiate the crypto conversion.
- 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.
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).
User/Corporate Initiates Fiat Deposit:
- Action: Instruct your user (Individual or Corporate) to deposit the desired fiat currency amount into the provided Unblock bank account using their preferred payment method (e.g., bank transfer, open banking). They will use the bank details retrieved in the previous step.
[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.
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.
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:

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
Crypto Transfer to Unblock Wallet:
- Instruct users to transfer the desired cryptocurrency amount to their retrieved Unblock wallet address.

[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.

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