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 the settlement_currency field under pricing to 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.

• Go SDK
• Command Line Tool

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 verify if a charge has been fully paid?

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.

How can I implement my own custom frontend for payments?

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.

Why am I receiving HTTP Status Code 500 errors?

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.

Why is there a delay between network confirmation and the charge webhook event?

A delay between network confirmation time and the charge webhook event is expected. Coinbase requires additional block confirmations before sending the charge webhook—specifically:

• For Polygon, 128 blocks are required.
• For Ethereum, 85 blocks are required.
• For Base, 420 blocks are required.

This ensures the appropriate webhook event is sent even if there were to be a fork in the network.

What is the minimum amount that can be charged?

The minimum amount of charges that can be paid with a Coinbase account is $1.00. For self-custody accounts, it can be as low as$0.01.

How can I implement OnchainKit Checkout with Coinbase Commerce?

The <Checkout /> component provides a one-click checkout experience for onchain commerce, simplifying payment processing for developers. Key features include:

• Plug-and-Play Integration: Add the <Checkout /> component with minimal setup.
• Dynamic Payment Flows: Generate charges dynamically or use product IDs for fixed pricing.
• Customizable UI: Add branding, styles, and custom button text.

Example integration:

<Checkout productId="my-product-id">
  <CheckoutButton />
</Checkout>

For dynamic charges, set up a backend to create charges and pass the chargeHandler prop:

const chargeHandler = async () => {
  const response = await fetch("/createCharge", { method: "POST" });
  const { id } = await response.json();
  return id;
};

<Checkout chargeHandler={chargeHandler}>
  <CheckoutButton />
</Checkout>;

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:

• Payment Status
• Create a charge
• Using Webhooks