The timeline
field on the Charge represents where the payment is in the Commerce flow. For a completed transaction this looks like:
The “PENDING” status indicates a transaction is paid, allowing merchants to proceed with order fulfillment.
Once a payment has been detected onchain by Commerce, we add a payment entry into the payments
field. This is similar to:
The transaction_id
field represents the hash of the transaction that can be used to find it onchain. Payments can happen on Eth Mainnet, Polygon, or Base, so you must refer to the network
field to successfully locate the transaction.
Network | Chain ID | Block Explorer Link |
---|---|---|
Ethereum Mainnet | 1 | https://etherscan.io/tx/<tx_hash> |
Polygon Mainnet | 137 | https://polygonscan.com/tx/<tx_hash> |
Base | 8453 | https://basescan.org/tx/<tx_hash> |
Custom metadata allows you to add relevant information to an order. You can safely add 5-10 properties without exceeding typical data limits. There are no reserved keywords within the metadata object, so feel free to use any terms that fit your needs.
The redirect URL directs users to a specific HTTPS URL after a payment is successful, allowing for actions like updating databases or triggering specific server logic. It’s a flexible tool that can handle everything from simple redirects to your homepage to complex interactions with API endpoints. Unlike webhooks, which are suited for server-side updates, the redirect URL is triggered by successful payments, making it ideal for immediate post-payment actions.
Yes, you can create checkouts through our API. To do so, send a POST request to https://api.commerce.coinbase.com/checkouts. For detailed API parameters, please refer to our API reference.
We do not support testnet transactions. To test transactions, we recommend creating a $1 charge on Base with USDC, where transaction fees are negligible. This allows you to test functionality without significant costs.
Yes, merchants can accept payments in Bitcoin, as well as any other asset available in Coinbase accounts. This includes the full range of assets from the balances of Coinbase’s 100 million users.
However, currently, Bitcoin and UTXO payments from self-custodial wallets or other exchanges are not supported. This policy ensures a fast, stable, and seamless transaction experience for our merchants. We are actively exploring improvements, including the potential integration of additional payment methods like the Lightning Network.
No, charges cannot be underpaid or overpaid. Our system ensures that the exact amount specified is transacted.
Yes, you can restrict payments to only KYC-verified balances. If you require this configuration, please contact our team for assistance.
You can only cancel a charge if it is still in the ‘New’ status. To cancel, send a POST request to the appropriate API endpoint.
If you receive an internal server error, first ensure that you are not making requests from any sanctioned countries. If this does not apply, please contact our support team for assistance.
Our transparent pricing is a simple bundled flat rate with no spread or hidden fees. Coinbase Commerce applies a 1% fee to all transactions.
The primary changes require that you remove addresses
, and no longer use the pricing
field’s entries for individual crypto currencies.
addresses
, the typical use case was locating an onchain transaction, which can be done following the guide above.pricing
, the typical use case was determining the amount received from the Payer.Our Onchain Payment Protocol does not allow over or under payments; so you can be confident that you will always receive the exact amount of USDC that the charge was priced in. If you need to know this, you can refer to the settlement_currency
field under pricing
to know exactly what you received.
We provide a Go SDK and a Command Line Tool to help you integrate and manage our services more effectively.
Yes, we maintain a status page that provides real-time updates on the operational status of our services. This page is designed to keep you informed of any issues impacting our systems, scheduled maintenance, or any other service disruptions. You can access our status page at status.commerce.coinbase.com
To verify if a charge has been fully paid, you can check the status in the timeline array of the Charge API model. A charge is considered fully paid when its status is COMPLETED
.
Additionally, you can use webhook events such as charge:confirmed
to get real-time updates when a charge is fully confirmed and finalized. That said, charge:pending
is enough to make a charge as paid, because it represents that the payment is confirmed by the respective chain.
Warning
While charge:pending
is likely sufficient to consider a charge as paid, be aware that a blockchain reorganization (reorg) could result in a loss of funds. It might be safer to wait for the charge:confirmed
status for final confirmation.
You can implement your own custom frontend by using the Coinbase Commerce API to create charges and manage payments. You can pass the necessary information from the user’s cart to the API and handle the payment process on your custom frontend. Note that while you can create a custom frontend, the actual payment must still be done through the Coinbase Commerce hosted payment page.
If you are receiving HTTP Status Code 500 errors, it could be due to various reasons including server issues or unexpected behavior in the API. First, check status.commerce.coinbase.com for any ongoing issues with Coinbase Commerce services. If issues continue, contact us on Discord for further assistance.
A delay between network confirmation time and the charge webhook event is expected. Coinbase requires additional block confirmations before sending the charge webhook—specifically:
This ensures the appropriate webhook event is sent even if there were to be a fork in the network.
The minimum amount of charges that can be paid with a Coinbase account is 0.01.
The <Checkout />
component provides a one-click checkout experience for onchain commerce, simplifying payment processing for developers. Key features include:
<Checkout />
component with minimal setup.Example integration:
For dynamic charges, set up a backend to create charges and pass the chargeHandler
prop:
Please join our Discord, where you can post questions and see how others are using Coinbase Commerce.
See Also: