Get started in testnet
Test USDC transfers
Test USDC transfers in the Cross River sandbox environment using supported blockchain test networks. Both Ethereum (Sepolia) and Solana (Devnet) are available for end-to-end testing.
Prerequisites
- A registered sandbox account in the Cross River developer environment.
- A testnet blockchain wallet address on Ethereum (Sepolia) and or Solana (Devnet).
- Test USDC tokens funded through public faucets.
Get testnet tokens
Test tokens are required to simulate stablecoin payment flows in the sandbox environment. Each blockchain uses separate assets for testing, including USDC for payment simulation and ETH or SOL for network fees.
Asset | Network | Source | Description |
|---|---|---|---|
USDC | Ethereum (Sepolia) & Solana (Devnet) | Provides test USDC on both Sepolia and Devnet networks. Requires a wallet configured for the corresponding test network, such as MetaMask for Sepolia or Phantom for Devnet. | |
ETH | Ethereum (Sepolia) | Provides test ETH for Sepolia network fees. Each request grants a limited amount for development use. | |
SOL | Solana (Devnet) | Provides test SOL for Solana Devnet network fees. Requires a Solana compatible wallet. |
IMPORTANT
Testnet assets have no monetary value and are intended for development and testing only. Always confirm that the correct test network is selected before initiating transfers.
Run your first test
The sandbox environment supports testing of both inbound and outbound stablecoin payment flows.
Test an inbound payment (external to Cross River)
- Retrieve a receiving address: Call GET /v1/accounts/{accountNumber}/account-addresses to retrieve a Cross River-managed receiving address associated with the account for the selected blockchain network.
- Fund a test wallet: Request test USDC and the corresponding network token using the public faucet links listed in the table in the Get testnet tokens section.
- Initiate the transfer: Send test USDC from an external testnet wallet to the retrieved receiving address.
- Onchain confirmation: Once the transaction is confirmed on the test network, Cross River detects the transfer and makes the payment available for PII submission.
- Provide PII: Submit the required sender PII using POST /v1/payments/{id}/pii.
- Verify receipt: After required PII is submitted and the payment is completed, Cross River issues a Crypto.Payment.Received webhook. Webhook logs can be used to confirm successful receipt of the inbound payment and account credit.
Test an outbound payment (Cross River to external)
- Create an external destination wallet: Call POST /v1/accounts/{accountNumber}/external-addressesto register a destination blockchain address for testing.
- Send a payment:
- Call POST /v1/payments to initiate a USDC payment from the Cross River sandbox account to the registered external address.
- Set the blockchain field to either ethereum or solana, based on the selected test network.
- Confirm transaction status: After the transaction is broadcast and confirmed, a Crypto.Payment.Sentwebhook is issued containing the payment ID and blockchain transaction hash.
Additional considerations
- Supported assets in sandbox: USDC on Ethereum Sepolia and Solana Devnet.
- Settlement timing: Confirmation typically occurs within seconds, subject to blockchain network conditions and applicable review processes.
- Network fees: Testnet network fees may apply as part of the sandbox testing flow. These fees are paid using the applicable test network token.