Creating a Deposit Transaction

Deposits can be created in two ways:

1. Implicitly - If the user sends approved funds to their deposit address, Omnia will process the deposit and take the appropriate actions.
2. Explicitly - You may present a deposit transaction for the user to sign and submit.

This guide explains how to create a new deposit transaction for the "explicit" deposit flow.

NOTE: Omnia also provides embeddable widgets to handle deposit flows. Consider using an embeddable widget for an easier integration.

Prerequisites

• Active blockchain account (see Creating a Blockchain Account)
• Registered counterparty for the sending address
• Valid api key

Step 1: Create the Deposit Transaction

POST /blockchain-accounts/{blockchain-account-id}/deposit-transactions
Authorization: Bearer {your-api-key}
Content-Type: application/json

{
  "amount": "100.50",
  "currency": {
    "type": "stablecoin-currency",
    "symbol": "USDC",
    "network": "solana"
  },
  "sourceId": "CPT_01BX5ZZKBKACTAV9WEVGEMMVS1"
}

Request Parameters

Currency Types

Stablecoin Currency

{
  "type": "stablecoin-currency",
  "symbol": "USDC",
  "network": "solana"
}

Deposit Token Currency

{
  "type": "deposit-token-currency",
  "id": "DPT_01BX5ZZKBKACTAV9WEVGEMMVS1"
}

Step 2: Receive the Response

The API returns a serialized blockchain transaction that the user must sign and submit to complete the deposit.

Example Response

{
  "id": "TXN_01BX5ZZKBKACTAV9WEVGEMMVS1",
  "amount": "100.50",
  "currency": {
    "type": "stablecoin-currency",
    "symbol": "USDC",
    "network": "solana"
  },
  "serializedTransaction": "base64_encoded_transaction_data"
}

Response Fields

Step 3: Present Transaction to User for Signing

The user must sign and submit the transaction using their wallet:

For Solana Wallets

// Deserialize the transaction
const transaction = Transaction.from(Buffer.from(serializedTransaction, 'base64'));

// Present to user for signing
const signature = await window.solana.signAndSendTransaction(transaction);
console.log('Transaction submitted:', signature);

Step 4: Monitor Transaction Status

Check the transaction status using the transactions endpoint:

GET /transactions/{transaction-id}
Authorization: Bearer {your-api-key}

Transaction Status Flow

1. pending - Transaction created and ready for user signature
2. completed - User submitted transaction to blockchain, deposit successful, bank account credited
3. failed - Transaction failed due to compliance issues, insufficient funds, or user rejection

Compliance and Risk Screening

The system automatically performs:

Sanctions Screening

• Checks sender against OFAC and global sanctions lists
• Verifies compliance with AML regulations
• Reviews transaction patterns for suspicious activity

Risk Assessment

• Evaluates transaction amount against limits
• Checks counterparty verification status
• Reviews historical transaction patterns

Regulatory Reporting

• Generates required compliance reports
• Maintains audit trails
• Submits regulatory filings as needed

Transaction Limits

Deposits are subject to configured limits:

Single Transaction Limits

{
  "type": "deposit-transaction-limit",
  "interval": "single-transaction",
  "amount": "10000.00",
  "currency": {
    "type": "stablecoin-currency",
    "symbol": "USDC",
    "network": "solana"
  }
}

Daily Limits

{
  "type": "deposit-transaction-limit",
  "interval": "daily",
  "amount": "50000.00",
  "currency": {
    "type": "stablecoin-currency",
    "symbol": "USDC",
    "network": "solana"
  },
  "allowedSources": ["CPT_verified_wallets_only"]
}

Error Handling

Common error scenarios:

Limit Exceeded (400)

{
  "error": "DEPOSIT_LIMIT_EXCEEDED",
  "message": "Daily deposit limit of $50,000 exceeded",
  "details": {
    "currentTotal": "45000.00",
    "attemptedAmount": "10000.00",
    "dailyLimit": "50000.00"
  }
}

Unknown Counterparty (400)

{
  "error": "UNKNOWN_COUNTERPARTY",
  "message": "Source counterparty not registered",
  "details": {
    "sourceId": "CP_unknown_wallet",
    "requiredAction": "Register counterparty first"
  }
}

Compliance Hold (400)

{
  "error": "COMPLIANCE_HOLD",
  "message": "Transaction held for compliance review",
  "details": {
    "reviewType": "AML_SCREENING",
    "estimatedReviewTime": "24-48 hours"
  }
}

Best Practices

Security

• Validate user inputs before creating transactions
• Verify transaction contents before presenting to user
• Implement proper wallet connection security
• Use secure counterparty identification

User Experience

• Clearly explain transaction details to users
• Provide transaction previews before signing
• Handle wallet rejections gracefully
• Show clear status updates during processing
• Implement proper error messages for failed transactions

API Reference

• Create Deposit: POST /blockchain-accounts/{id}/deposit-transactions
• Check Status: GET /transactions/{id}
• List Transactions: GET /transactions
• Register Counterparty: POST /counterparties
• Set Limits: POST /blockchain-accounts/{id}/transaction-limits