> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dynamic.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Crypto.com Onramp
For new React apps, we recommend the JavaScript SDK with React Hooks (`@dynamic-labs-sdk/react-hooks`) instead of the legacy React SDK documented here. The JS SDK comes with many benefits such as a much smaller bundle size and other optimizations. Use the [React quickstart (JavaScript SDK)](/javascript/reference/react-quickstart) to get started.
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 custom UI implementations, providing a seamless way for users to fund their wallets with fiat currency.
## Dashboard Setup
To enable Crypto.com onramp:
1. Go to [the Funding tab in your Dynamic developer dashboard](https://app.dynamic.xyz/dashboard/funding)
2. Under "Fiat on-ramps", toggle on Crypto.com
3. Save the settings
### Secret key
You'll need to create a merchant account on [crypto.com](https://merchant.crypto.com/). So, go to the [merchant.crypto.com](https://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.
## Widget Implementation
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.
```tsx theme={"system"}
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
```
### Fetching the QR code and opening it yourself
Use the `getOnrampQrCode` method to fetch the QR code to be opened.
```tsx theme={"system"}
import { useOnramp } from '@dynamic-labs/sdk-react-core'
import { OnrampProviders } from '@dynamic-labs/sdk-api-core'
const { getOnrampQrCode } = useOnramp();
const qrCode = await getOnrampQrCode({
onrampProvider: OnrampProviders.CryptoDotCom,
address: '0x1234567890123456789012345678901234567890',
token: 'ETH',
});
// Open it yourself (e.g., window.open(qrCode, ...)) if defined
```
#### Auto opening the onramp
```tsx theme={"system"}
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 (
)
}
```
### Accessing Provider Information
You can also access provider configuration details through the `providers` array. This is useful for dynamically displaying available onramp options:
```tsx theme={"system"}
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:
```json theme={"system"}
[
{
"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:
```bash theme={"system"}
curl https://pay.crypto.com/api/payments/{payment_id} \
-u sk_test_YOUR_SECRET_KEY:
```
**Response:**
```json theme={"system"}
{
"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:
```tsx theme={"system"}
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:
1. **Extracting Payment ID**: Parse the payment ID from the Crypto.com onramp URL
2. **Polling API**: Periodically check payment status using the Crypto.com API
3. **Webhook Integration**: Set up webhooks to receive real-time status updates
```tsx theme={"system"}
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
1. **Validate Parameters**: Always validate wallet addresses and amounts before opening the onramp
2. **Handle Errors Gracefully**: Implement proper error handling for all failure scenarios
3. **Track Payment Status**: Monitor payment status to provide user feedback
4. **Security**: Never expose API keys in client-side code - use server-side endpoints for sensitive operations
5. **User Experience**: Provide clear feedback during payment processing and handle loading states
6. **Provider Selection**: Use the `providers` array to dynamically display available onramp options
7. **Fallback Handling**: Implement fallback mechanisms for when specific providers are unavailable
8. **Amount Validation**: Ensure fiat amounts are reasonable and within supported limits
9. **Currency Support**: Verify that the selected currency is supported by Crypto.com in your region
10. **URL Availability**: Be aware that `url` may be undefined until you supply sufficient parameters (e.g., `tokenAmount`, `currency`)
## Related
* **[useOnramp](/react/reference/hooks/funding/useonramp)** - Programmatic onramp triggering
* **[usePayWithDynamic](/react/reference/hooks/funding/usepaywithdynamic)** - Unified payment flow
* **[Default Onramps](/react/money-and-funding/default-onramps)** - General onramp setup
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.
## Widget Implementation
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.
```tsx theme={"system"}
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
```
### Fetching the QR code and opening it yourself
Use the `getOnrampQrCode` method to fetch the QR code to be opened.
```tsx theme={"system"}
import { useOnramp } from '@dynamic-labs/sdk-react-core'
import { OnrampProviders } from '@dynamic-labs/sdk-api-core'
const { getOnrampQrCode } = useOnramp();
const qrCode = await getOnrampQrCode({
onrampProvider: OnrampProviders.CryptoDotCom,
address: '0x1234567890123456789012345678901234567890',
token: 'ETH',
});
// Open it yourself (e.g., window.open(qrCode, ...)) if defined
```
#### Auto opening the onramp
```tsx theme={"system"}
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 (
)
}
```
### Accessing Provider Information
You can also access provider configuration details through the `providers` array. This is useful for dynamically displaying available onramp options:
```tsx theme={"system"}
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:
```json theme={"system"}
[
{
"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:
```bash theme={"system"}
curl https://pay.crypto.com/api/payments/{payment_id} \
-u sk_test_YOUR_SECRET_KEY:
```
**Response:**
```json theme={"system"}
{
"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:
```tsx theme={"system"}
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:
1. **Extracting Payment ID**: Parse the payment ID from the Crypto.com onramp URL
2. **Polling API**: Periodically check payment status using the Crypto.com API
3. **Webhook Integration**: Set up webhooks to receive real-time status updates
```tsx theme={"system"}
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
1. **Validate Parameters**: Always validate wallet addresses and amounts before opening the onramp
2. **Handle Errors Gracefully**: Implement proper error handling for all failure scenarios
3. **Track Payment Status**: Monitor payment status to provide user feedback
4. **Security**: Never expose API keys in client-side code - use server-side endpoints for sensitive operations
5. **User Experience**: Provide clear feedback during payment processing and handle loading states
6. **Provider Selection**: Use the `providers` array to dynamically display available onramp options
7. **Fallback Handling**: Implement fallback mechanisms for when specific providers are unavailable
8. **Amount Validation**: Ensure fiat amounts are reasonable and within supported limits
9. **Currency Support**: Verify that the selected currency is supported by Crypto.com in your region
10. **URL Availability**: Be aware that `url` may be undefined until you supply sufficient parameters (e.g., `tokenAmount`, `currency`)
## Related
* **[useOnramp](/react/reference/hooks/funding/useonramp)** - Programmatic onramp triggering
* **[usePayWithDynamic](/react/reference/hooks/funding/usepaywithdynamic)** - Unified payment flow
* **[Default Onramps](/react/money-and-funding/default-onramps)** - General onramp setup