On April 15, 2024, all Coinbase Commerce merchants will need to migrate to the new Commerce product built on the onchain payment protocol. This upgrade offers:
Faster and more reliable processing with support for the Base network
Improved fund storage options
An updated login experience, including additional two-factor authentication options
Upgrade details
The new protocol enhances your crypto management with automatic settlement in USDC (or USD for managed merchants), real-time transaction processing, and expanded payment options.
Migration is mandatory and involves moving to our new payment system, updating your wallet, and updating your login credentials.
Migration steps
Coinbase-managed merchants can migrate any time before April 15, otherwise you will be automatically opted in on April 15.
Self-managed merchants need to:
Sign in using the legacy flow
Complete the migration flow
Update your wallet by migrating your Commerce wallet to the Coinbase Wallet interface, or provide a deposit address for your preferred wallet
Update your login credentials (by linking or creating a new Coinbase.com login)
The process should take no more than 5-10 minutes and is accessible from the merchant portal.
Accessing funds with a seed phrase
To access your funds:
Download Coinbase Wallet.
Get the 12-word seed phrase (also called a recovery phrase) you were given when you set up your Commerce account.
If it’s backed up in Google Drive, you can use the migration tool to decrypt the uploaded key.
In Coinbase Wallet, select the option to import or restore an existing wallet and enter the 12-word seed phrase.
Your Ethereum balances are now directly accessible in your self-custodial wallet.
You can continue to withdraw your non-EVM compatible currencies (e.g. Bitcoin, Bitcoin Cash, Dogecoin, and Litecoin) from the Commerce portal.
Cryptocurrency support
The new platform supports hundreds of currencies, including assets like ETH, MATIC, USDC, USDT, DAI, and more. Customers can also pay with any asset held on Coinbase.com, including Bitcoin, Doge, and Litecoin. However, payments in Bitcoin, Doge, Litecoin, and Bitcoin cash can no longer be processed from a self-custodial wallet or third-party exchange.
Settlement
Self-managed merchants
All incoming payments will be automatically swapped for USDC and deposited to the desired Ethereum/EVM deposit address on whichever chain your customers paid you on: Ethereum, Base, or Polygon.
Coinbase-managed merchants
All incoming payments will be automatically deposited directly to the Coinbase Exchange ledger as USD or USDC.
If USD is the desired settlement currency, please ensure you have selected USD from: https://exchange.coinbase.com/profile/settlement
Invoice and payment-flow changes
The Invoice checkout type has been removed, but you can use checkouts to create custom payment links that are similar to the legacy invoices. Once a customer opens/views the charge, the payment link will be valid for 48 hours.
The new payment system ensures accurate payment amounts, eliminating the need for manual resolution of overpayments or underpayments.
To achieve this, we ask customers to link their wallets so we can send transaction details directly, reducing manual data entry and streamlining the process. This also lets our system suggest the quickest, most cost-effective payment method based on their holdings.
The system supports self-custody wallets on Ethereum, Base, and Polygon, as well as payments from Coinbase.com accounts. However, payments from self-custody wallets on the Bitcoin network or from other exchanges are no longer supported.
For more information on how the payment experience has changed for your customers, please see our help center article.
Customer payments
Customers can pay using self-custodial wallets on Base, Polygon, and Ethereum networks, or with any cryptocurrency held in their Coinbase account. Note that customers are not required to have a Coinbase account to make a payment.
Troubleshooting
If you're not receiving payments as expected after migration, here are some tips:
Don’t use the ‘address’ field from the root layer of the Legacy Charge model
This field doesn’t exist for a Web3 Charge
Use local pricing
Ensure your charge is in cash currency; payments denominated in cryptocurrency aren’t currently supported
Track successful transactions via webhooks
Use the success_events struct inside the transfer_intent struct of the Charge model. This contains the transaction hash for successful transactions, which can be used on the blockchain to confirm completed payments.
For more detailed guidance, please reference our developer documentation.