Migrating to the Onchain Payment Protocol

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:

  1. Sign in using the legacy flow

  2. Complete the migration flow

    1. Update your wallet by migrating your Commerce wallet to the Coinbase Wallet interface, or provide a deposit address for your preferred wallet

    2. Update your login credentials (by linking or creating a new 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:

  1. Download Coinbase Wallet. 

  2. 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.

  3. 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, 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.


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:

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 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. 


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.