Eco Checkout is a single-page web application that enables merchants to seamlessly receive stablecoin payments. Merchants should redirect their users to the Eco Checkout web app via a specially crafted URL that includes the necessary payment parameters.
For example, a merchant from their website can redirect users to:
https://ecocheckout.xyz/?amount=5.00&token=usdc&recipient=0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97&network=8453&redirect=www.google.comThe merchant can include a redirect parameter to return the user to their site after the payment is completed.
Eco Checkout, powered by Eco Routes, makes it easy for users to aggregate and pay using stablecoins across multiple blockchain networks.
Eco Checkout is a single-page application (SPA) designed to facilitate stablecoin payments across multiple blockchain networks using Eco Routes
The app integrates with the Eco Routes SDK, allowing it to create and execute payment intents efficiently.
The application is fully open-source and can be customized to suit your needs. While the core logic is generalized, you can tailor the user interface to match your branding or workflow.
- Node.js
- Package manager (npm, yarn, or pnpm)
Create a .env.local file with the following variables:
| Variable | Description | Example |
|---|---|---|
NEXT_PUBLIC_REOWN_APP_ID |
Your Reown App ID | your_reown_app_id |
NEXT_PUBLIC_APP_BASE_URL |
Your app's base URL | http://localhost:3000 |
NEXT_PUBLIC_ALCHEMY_API_KEY |
Optional: Alchemy API key for RPC endpoints | your_alchemy_api_key |
NEXT_PUBLIC_ECO_DAPP_ID |
Your Eco DApp ID used for platform integration | your_eco_dapp_id |
NEXT_PUBLIC_RELAYOOR_BASE_URL |
Relayoor API base URL | your_eco_realyoor_url |
NEXT_PUBLIC_QUOTES_BASE_URL |
Base URL for the Quotes API | your_eco_quotes_url |
UPSTASH_REDIS_REST_URL |
Upstash Redis REST API endpoint | https://your-upstash-url.upstash.io |
UPSTASH_REDIS_REST_TOKEN |
Authentication token for accessing Upstash Redis | your_upstash_redis_token |
You can get a Reown App ID from https://cloud.reown.com/sign-in.
Note:
TheNEXT_PUBLIC_ALCHEMY_API_KEYis optional. If not set, the application will use public RPC endpoints by default. Setting this variable will enable the use of Alchemy's RPC endpoints for better performance and reliability.The
UPSTASH_REDIS_REST_URLandUPSTASH_REDIS_REST_TOKENare used to generate a short, shareable version of the full URL of the app. You can get these at upstash.com.
Choose your preferred package manager:
# Using npm
npm install && npm run dev
# Using yarn
yarn install && yarn dev
# Using pnpm
pnpm install && pnpm devThe tokens and chains supported by the SPA are the ones supported by ECO. You can find it here in the Eco docs
The application accepts several query parameters in the URL that control the payment flow:
-
recipient: Ethereum address of the payment recipient- Must be a valid Ethereum address (0x followed by 40 hex characters)
- If invalid or empty, defaults to null
-
amount: Payment amount the user must pay- Must be a positive number
- Supports up to 2 decimal places
- If invalid or empty, defaults to null
-
network: The network where the tokens will be received- Must be a valid and Eco-supported chain ID
- If invalid, defaults to null
-
token: The desired token to receive- Must be an Eco-supported token (e.g., "USDC")
- If invalid or empty, defaults to "USDC"
-
redirect: URL to redirect after payment completion- Optional parameter
- If not provided, defaults to an empty string
-
showFees: If set to "true", shows the fees to the user- Optional parameter
- If not provided, the network fees aren't shown
A URL requesting 5 USDC on Base and then redirecting to www.google.com (imagine it's the merchant website) looks like this:
https://ecocheckout.xyz?amount=5.00&token=usdc&recipient=0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97&network=8453&redirect=www.google.comThe PaymentParamsValidator class handles parameter validation:
- Invalid or empty parameters are replaced with default values
- The app shows a "Missing Parameters" view if required parameters are missing
- Transaction processing only begins when all required parameters are valid
If any required query parameters are missing, users can fill them in using a simple form shown in a special view that appears before the checkout process. Ideally, merchants should provide a redirect link to their users, that already includes all required query parameters.
- The merchant constructs the Eco Checkout URL with the required parameters and redirects the user to it
- Parameters are validated on page load
- If valid, the user can proceed to payment; if not valid, the user must manually fill in the required missing parameters
- The user connects their wallet
- If the connected wallet contains enough tokens to cover the due amount, the user is presented with an optimized selection of tokens; if the wallet's total value is insufficient, the user is prompted to connect another wallet
- If the user is not satisfied with the optimized token selection, they can change it by opening the advanced token selection modal
- The user reviews the checkout through the payment recap step before proceeding with the actual payment
- The user lands in the transactions view, where the first transaction is automatically started
- Once the user completes all transactions, if a redirect link is provided as a query parameter, the user is shown a button that redirects to the merchant's website; otherwise, the payment process finishes with a success message and the window can be closed.
We welcome contributions! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
- Fork the repository
- Install dependencies using your preferred package manager
- Create a
.env.localfile with the required environment variables - Run the development server
- Make your changes
- Submit a pull request