FAQ
How do I determine the charge state from a charge?
The timeline field on the Charge represents where the payment is in the Commerce flow. For a completed transaction this looks like:
[
{
"status": "NEW",
"time": "2024-04-14T17:15:17Z"
},
{
"status": "SIGNED",
"time": "2024-04-14T17:15:41Z"
},
{
"status": "PENDING",
"time": "2024-04-14T17:16:53Z"
},
{
"status": "COMPLETED",
"time": "2024-04-14T17:30:53Z"
}
],
The "PENDING" status indicates a transaction is paid, allowing merchants to proceed with order fulfillment.
How can I find the Onchain payment associated with a Charge?
Once a payment has been detected onchain by Commerce, we add a payment entry into the payments field. This is similar to:
{
"payment_id": "0x1fd123fb4567c8aaaef12b345de67fc01234f5fb6789f123d45d6789a123456d",
"network": "base",
"transaction_id": "0x1fd123fb4567c8aaaef12b345de67fc01234f5fb6789f123d45d6789a123456d",
"status": "pending",
"detected_at": "2024-04-14T17:16:45Z",
"value": {
"local": {
"amount": "1",
"currency": "USD"
},
"crypto": {
"amount": "1",
"currency": "USDC"
}
},
"payer_addresses": [
"0x1230d0123b99e12345a6d7bde89fddc1a123bdf4"
]
}
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> |
What is custom metadata and how can I use it?
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.
What is a redirect URL and how is it used?
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.
What is the difference between fixed and no_price charges?
- Fixed price charges have a predetermined price that cannot be underpaid or overpaid. They ensure that the exact amount specified is paid.
- No_price charges allow users to choose the amount they wish to pay, making them ideal for flexible transactions such as donations.
Can I create checkouts via the API?
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.
Is there support for testnet transactions?
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.
Can I receive payments in Bitcoin?
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.
Can charges be underpaid or overpaid?
No, charges cannot be underpaid or overpaid. Our system ensures that the exact amount specified is transacted.
Can I restrict payments to only KYC-verified balances?
Yes, you can restrict payments to only KYC-verified balances. If you require this configuration, please contact our team for assistance.
How can I cancel a charge?
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.
What should I do if I encounter an internal server error?
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.
How much does it cost to use Coinbase Commerce?
Our transparent pricing is a simple bundled flat rate with no spread or hidden fees. Coinbase Commerce applies a 1% fee to all transactions.
What do I need to update in my integration with Commerce after migrating to the updated payment protocol?
The primary changes require that you remove addresses, and no longer use the pricing field's entries for individual crypto currencies.
- For
addresses, the typical use case was locating an onchain transaction, which can be done following the guide above. - For
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 thesettlement_currencyfield underpricingto know exactly what you received.
Where can I find links to your SDKs?
We provide a Go SDK and a Command Line Tool to help you integrate and manage our services more effectively.
Do you have a status page for Commerce?
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
How can I get additional help?
Please join our Discord, where you can post questions and see how others are using Coinbase Commerce.
See Also: