Crypto.com Onramp

Crypto.com is currently in limited beta. Please contact support if you’re interested in early access.

Overview

Crypto.com onramp integration allows users to purchase cryptocurrency directly within your application using Crypto.com’s payment infrastructure. This integration supports both widget-based and headless implementations, providing a seamless way for users to fund their wallets with fiat currency.

Dashboard Setup

To enable Crypto.com onramp:

Go to the Funding tab in your Dynamic developer dashboard
Under “Fiat on-ramps”, toggle on Crypto.com
Save the settings

Secret key

You’ll need to create a merchant account on crypto.com. So, go to the merchant.crypto.com and create an account.

Once you’ve created an account, go to integration and copy your secret key and paste it in the Dynamic dashboard.

Return and cancel URLs

You’ll need to set the return and cancel URLs in the Dynamic dashboard. These URLs are used to redirect the user after the payment is completed or cancelled. Once enabled, users will see Crypto.com as an option in the Dynamic widget’s deposit screen. Selecting Crypto.com in the widget opens a tailored screen where the user chooses fiat currency and amount; after confirming, the flow continues to Crypto.com in a new browser tab.

Programmatic Implementation

Using the useOnramp Hook

You can trigger Crypto.com onramp programmatically using the useOnramp hook. This approach gives you full control over when and how the onramp is displayed. You can either fetch the URL to be opened and use it yourself, or you can use the open method to open the onramp (note: open resolves void).

Fetching the URL and opening it yourself

Use the getOnrampUrl method to fetch the URL to be opened.

import { useOnramp } from '@dynamic-labs/sdk-react-core'
import { OnrampProviders } from '@dynamic-labs/sdk-api-core'

const { getOnrampUrl } = useOnramp();

const url = await getOnrampUrl({
  onrampProvider: OnrampProviders.CryptoDotCom,
  address,
  chainName: 'evm', // optional, defaults from primary wallet
  network: '1',     // optional, used only when chainName is 'evm'
  currency: 'USD',
  tokenAmount: 500, // fiat amount
});

// Open it yourself (e.g., window.open(url, ...)) if defined

Auto opening the onramp

import { useOnramp } from '@dynamic-labs/sdk-react-core'
import { OnrampProviders } from '@dynamic-labs/sdk-api-core'

const CryptoDotComOnramp = () => {
  const { enabled, open } = useOnramp()

  const handleCryptoDotComOnramp = async () => {
    await open({
      onrampProvider: OnrampProviders.CryptoDotCom,
      address: '0x1234567890123456789012345678901234567890',
      tokenAmount: 500, // amount in fiat currency
      currency: 'USD',
      chainName: 'evm', // optional, defaults from primary wallet
      network: '1',     // optional, used only when chainName is 'evm'
    })
  }

  return (
    <button onClick={handleCryptoDotComOnramp} disabled={!enabled}>
      Open Crypto.com Onramp
    </button>
  )
}

Accessing Provider Information

You can also access provider configuration details through the providers array. This is useful for dynamically displaying available onramp options:

const { providers } = useOnramp()

// Find Crypto.com provider
const cryptoDotComProvider = providers.find(p => p.id === 'cryptoDotCom')

// Access provider details
console.log(cryptoDotComProvider?.displayName) // "Crypto.com"
console.log(cryptoDotComProvider?.iconUrl)     // Icon URL
console.log(cryptoDotComProvider?.openMode)    // "popup"

Providers Array Structure

The providers array contains configuration for each available onramp provider. This allows you to build custom UI components that dynamically show available options:

[
  {
    "displayName": "Banxa",
    "iconUrl": "https://dynamic.banxa.com/favicon.ico",
    "id": "banxa",
    "openMode": "iframe",
    "url": "https://dynamic.banxa-sandbox.com/?walletAddress=0x9217d782c2f5dF7cC53CcC0Eb0fe213F83DEc48d&coinType=ETH&blockchain=ETH&coinAmount=undefined"
  },
  {
    "displayName": "Crypto.com",
    "iconUrl": "https://iconic.dynamic-static-assets.com/icons/sprite.svg#crypto-dot-com",
    "id": "cryptoDotCom",
    "openMode": "popup",
    "url": "https://js.crypto.com/sdk/payments/checkout/set_wallet?id=8a2cbe01-b479-48f2-99fb-c6d63ec63499&publishableKey=pk_test_RkhZhXF57ZfbjQShKYWFGQkw&sdkMeta=eyJ1cmwiOiJodHRwczovL2pzLmNyeXB0by5jb20vc2RrP3B1Ymxpc2hhYmxlLWtleT1wa190ZXN0X1JraFpoWEY1N1pmYmpRU2hLWVdGR1Frd1x1MDAyNnN0YWdpbmc9ZmFsc2UiLCJ2ZXJzaW9uIjoiMC4zLjEifQ%3D%3D"
  }
]

Note: url may be undefined until sufficient parameters (e.g., tokenAmount, currency) are provided.

Field	Type	Description
`displayName`	string	Human-readable name of the provider
`iconUrl`	string	URL to the provider’s icon
`id`	string	Unique identifier for the provider
`openMode`	string	How the onramp opens (`iframe` or `popup`)
`url`	string	The onramp URL with pre-configured parameters

Payment Tracking

Payment ID

Crypto.com provides a payment ID in the onramp URL that you can use to track payment status. This ID is included in the URL parameters when the onramp is opened and is essential for monitoring payment progress.

Getting Payment Information

Use the payment ID from the Crypto.com onramp URL to fetch payment details via their API. You’ll need your Crypto.com secret key for authentication:

curl https://pay.crypto.com/api/payments/{payment_id} \
  -u sk_test_YOUR_SECRET_KEY:

Response:

{
  "id": "5e88d5ab-a331-45e8-9a12-7712a5535cae",
  "original_amount": 50000,
  "amount": 50000,
  "amount_refunded": 0,
  "created": 1760801155,
  "cashback_rate": "0.0",
  "crypto_currency": "CRO",
  "crypto_amount": "3547.1",
  "currency": "USD",
  "customer_id": null,
  "customer_provided_info": {},
  "data_url": "https://pay.crypto.com/sdk/payments/5e88d5ab-a331-45e8-9a12-7712a5535cae?signature=237f91ddeb91",
  "payment_url": "https://js.crypto.com/sdk/payments/checkout/set_wallet?id=5e88d5ab-a331-45e8-9a12-7712a5535cae&publishableKey=pk_test_RkhZhXF57ZfbjQShKYWFGQkw&sdkMeta=eyJ1cmwiOiJodHRwczovL2pzLmNyeXB0by5jb20vc2RrP3B1Ymxpc2hhYmxlLWtleT1wa190ZXN0X1JraFpoWEY1N1pmYmpRU2hLWVdGR1Frd1x1MDAyNnN0YWdpbmc9ZmFsc2UiLCJ2ZXJzaW9uIjoiMC4zLjEifQ%3D%3D",
  "return_url": "https://demo.dynamic.xyz/?snap=...",
  "cancel_url": "https://demo.dynamic.xyz/?snap=...",
  "description": "Crypto purchase for 0x1234567890123456789012345678901234567890",
  "live_mode": false,
  "metadata": {
    "chain": "EVM",
    "network_id": "1",
    "wallet_address": "0x1234567890123456789012345678901234567890",
    "token": "ETH"
  },
  "tax": {},
  "recipient": "Dynamic",
  "refunded": false,
  "status": "pending",
  "time_window": 600,
  "remaining_time": "09:25",
  "settled_at": 0,
  "expired": false,
  "enable_onchain_payment": false,
  "qr_code": "ewogICJpZCIgOiAiNWU4OGQ1YWItYTMzMS00NWU4LTlhMTItNzcxMmE1NTM1Y2FlIiwKICAidHlwZSIgOiAicGF5bWVudCIKfQ==",
  "deep_link": "monaco://pay?payment_url=...",
  "experimental_features": ["exptl_onchain_rebound", "..."],
  "expired_at": 1760819155,
  "payment_type": "checkout",
  "amount_in_usd": "500.0",
  "amount_in_usdc": "500.0",
  "extra_requirements": ["require_login", "require_ssn"],
  "payout_wallet_address": "0x1234567890123456789012345678901234567890",
  "payout_chain_name": "Ethereum"
}

Key Response Fields

The Crypto.com payment API response contains extensive information about the payment. Here are the key fields you’ll commonly use for tracking and displaying payment status:

Field	Type	Description
`id`	string	Unique payment identifier
`status`	string	Current payment status (pending, completed, failed, cancelled)
`amount`	number	Payment amount in fiat currency (e.g., 500 = $500.00)
`original_amount`	number	Original payment amount before any adjustments
`currency`	string	Fiat currency code (e.g., “USD”)
`crypto_currency`	string	Cryptocurrency symbol (e.g., “CRO”, “ETH”)
`crypto_amount`	string	Amount of cryptocurrency to be received
`amount_in_usd`	string	Payment amount in USD
`amount_in_usdc`	string	Payment amount in USDC
`payout_wallet_address`	string	Destination wallet address for the crypto
`payout_chain_name`	string	Blockchain network name (e.g., “Ethereum”)
`metadata`	object	Additional payment metadata including chain and network info
`time_window`	number	Payment time window in seconds (e.g., 600 = 10 minutes)
`remaining_time`	string	Time remaining for payment completion (e.g., “09:25”)
`expired`	boolean	Whether the payment has expired
`expired_at`	number	Unix timestamp when payment expires
`created`	number	Unix timestamp when payment was created
`settled_at`	number	Unix timestamp when payment was settled (0 if not settled)
`payment_url`	string	URL for the payment checkout interface
`return_url`	string	URL to redirect to after successful payment
`cancel_url`	string	URL to redirect to after cancelled payment
`qr_code`	string	Base64 encoded QR code for mobile payments
`deep_link`	string	Deep link for mobile app payments
`live_mode`	boolean	Whether this is a live payment (false for test mode)
`extra_requirements`	array	Additional requirements (e.g., [“require_login”, “require_ssn”])
`ncw_connections`	array	Available wallet connection methods
`network_cost`	string	Network transaction cost

Payment Status Values

Status	Description
`pending`	Payment is being processed
`completed`	Payment has been successfully completed
`failed`	Payment failed for various reasons
`cancelled`	Payment was cancelled by the user

Extracting Payment ID from URLs

When a user initiates a Crypto.com payment, the payment ID is included in the URL parameters. You can extract it for tracking purposes:

const extractPaymentId = (url: string) => {
  const urlParams = new URLSearchParams(url.split('?')[1])
  return urlParams.get('id')
}

// Example usage
const paymentUrl = "https://js.crypto.com/sdk/payments/checkout/set_wallet?id=5e88d5ab-a331-45e8-9a12-7712a5535cae&publishableKey=pk_test_RkhZhXF57ZfbjQShKYWFGQkw"
const paymentId = extractPaymentId(paymentUrl)
console.log(paymentId) // "5e88d5ab-a331-45e8-9a12-7712a5535cae"

Implementing Payment Status Tracking

You can implement payment status tracking by:

Extracting Payment ID: Parse the payment ID from the Crypto.com onramp URL
Polling API: Periodically check payment status using the Crypto.com API
Webhook Integration: Set up webhooks to receive real-time status updates

const trackPaymentStatus = async (paymentId: string) => {
  try {
    const response = await fetch(`https://pay.crypto.com/api/payments/${paymentId}`, {
      headers: {
        'Authorization': `Basic ${btoa('sk_test_YOUR_SECRET_KEY:')}`
      }
    })

    const paymentData = await response.json()

    if (paymentData.expired) {
      console.log('Payment has expired')
      return
    }

    console.log(`Payment ${paymentData.id}:`)
    console.log(`- Status: ${paymentData.status}`)
    console.log(`- Amount: $${(paymentData.amount / 100).toFixed(2)} ${paymentData.currency}`)
    console.log(`- Crypto: ${paymentData.crypto_amount} ${paymentData.crypto_currency}`)
    console.log(`- Wallet: ${paymentData.payout_wallet_address}`)
    console.log(`- Remaining time: ${paymentData.remaining_time}`)

    switch (paymentData.status) {
      case 'completed':
        console.log('Payment completed successfully!')
        console.log(`Settled at: ${new Date(paymentData.settled_at * 1000).toISOString()}`)
        break
      case 'failed':
        console.log('Payment failed')
        break
      case 'cancelled':
        console.log('Payment cancelled')
        break
      case 'pending':
        console.log('Payment still pending')
        if (!paymentData.expired) {
          setTimeout(() => trackPaymentStatus(paymentId), 5000)
        }
        break
    }
  } catch (error) {
    console.error('Error tracking payment status:', error)
  }
}

Supported Parameters

When opening Crypto.com onramp via the SDK, use these parameters:

Parameter	Type	Description
`address`	string	Destination wallet address for the purchase
`token`	string (optional)	Token symbol (e.g., “ETH”), if applicable
`tokenAmount`	number	Amount in fiat currency (e.g., 500 for $500.00)
`currency`	string	Fiat currency code (e.g., “USD”)
`chainName`	string	Chain family (e.g., “evm”)
`network`	string or number	Network identifier; used only when `chainName` is “evm” (e.g., “1” for ETH)

Note: The SDK requests a provider URL from Dynamic’s API using these parameters. It does not construct Crypto.com-specific query parameters directly on the client.

Error Handling

Common error scenarios and how to handle them in your application:

Insufficient Funds

Error: User doesn’t have sufficient funds for the purchase
Handling: Display appropriate error message and suggest alternative amounts

Invalid Wallet Address

Error: The provided wallet address is invalid
Handling: Validate wallet address format before opening onramp

Network Issues

Error: Network connectivity issues during payment processing
Handling: Implement retry logic and fallback mechanisms

Best Practices

Validate Parameters: Always validate wallet addresses and amounts before opening the onramp
Handle Errors Gracefully: Implement proper error handling for all failure scenarios
Track Payment Status: Monitor payment status to provide user feedback
Security: Never expose API keys in client-side code - use server-side endpoints for sensitive operations
User Experience: Provide clear feedback during payment processing and handle loading states
Provider Selection: Use the providers array to dynamically display available onramp options
Fallback Handling: Implement fallback mechanisms for when specific providers are unavailable
Amount Validation: Ensure fiat amounts are reasonable and within supported limits
Currency Support: Verify that the selected currency is supported by Crypto.com in your region
URL Availability: Be aware that url may be undefined until you supply sufficient parameters (e.g., tokenAmount, currency)

useOnramp - Programmatic onramp triggering
usePayWithDynamic - Unified payment flow
Default Onramps - General onramp setup

Installation & Configuration

Authenticate

Bring Your Own Authentication

Wallets

Money & Funding

Chains & Networks

Users & Verified Credentials

Gating & Access Control

Customizing Our UI

General Guidance

Crypto.com Onramp

Overview

Dashboard Setup

Secret key

Return and cancel URLs

Widget Implementation

Programmatic Implementation

Using the useOnramp Hook

Fetching the URL and opening it yourself

Auto opening the onramp

Accessing Provider Information

Providers Array Structure

Payment Tracking

Payment ID

Getting Payment Information

Key Response Fields

Payment Status Values

Extracting Payment ID from URLs

Implementing Payment Status Tracking

Supported Parameters

Error Handling

Insufficient Funds

Invalid Wallet Address

Network Issues

Best Practices

Installation & Configuration

Authenticate

Bring Your Own Authentication

Wallets

Money & Funding

Chains & Networks

Users & Verified Credentials

Gating & Access Control

Customizing Our UI

General Guidance

​Overview

​Dashboard Setup

​Secret key

​Return and cancel URLs

​Widget Implementation

​Programmatic Implementation

​Using the useOnramp Hook

​Fetching the URL and opening it yourself

​Auto opening the onramp

​Accessing Provider Information

​Providers Array Structure

​Payment Tracking

​Payment ID

​Getting Payment Information

​Key Response Fields

​Payment Status Values

​Extracting Payment ID from URLs

​Implementing Payment Status Tracking

​Supported Parameters

​Error Handling

​Insufficient Funds

​Invalid Wallet Address

​Network Issues

​Best Practices

​Related

Overview

Dashboard Setup

Secret key

Return and cancel URLs

Widget Implementation

Programmatic Implementation

Using the useOnramp Hook

Fetching the URL and opening it yourself

Auto opening the onramp

Accessing Provider Information

Providers Array Structure

Payment Tracking

Payment ID

Getting Payment Information

Key Response Fields

Payment Status Values

Extracting Payment ID from URLs

Implementing Payment Status Tracking

Supported Parameters

Error Handling

Insufficient Funds

Invalid Wallet Address

Network Issues

Best Practices

Related