Connect Coinbase Commerce

Why Coinbase Commerce

Brand recognition. A customer who has never paid in crypto is far more likely to complete a checkout that says Coinbase on it than one they have never heard of. It costs 1%, and settles to your own self-custody wallet.

Coinbase narrowed the assets it supports after its 2024 protocol change, and it now leans heavily on USDC. Check the current list in your Coinbase Commerce dashboard before you promise a customer a particular coin.

Where to get the two values

Coinbase Commerce API key — beta.commerce.coinbase.com → Settings → API keys → Create an API key. It is shown once.

Webhook shared secret — the same Settings page, Webhook subscriptions section. Add an endpoint pointing at the webhook URL kitty gives you (see below), then copy the shared secret shown above the endpoint list.

The least fiddly order: connect with just the API key, copy the webhook URL from the card, add the subscription in Coinbase, then Replace keys with the shared secret filled in.

Connecting

Settings → Connections → Take payments → the Coinbase Commerce card → Connect → paste both values → Save and connect, then Test connection.

The webhook, which is not optional

kitty needs Coinbase Commerce to tell it when someone pays. Without that, the checkout takes the money and no order, customer or revenue figure ever appears in kitty.

On the connected card, press Webhook URL, copy it, and paste it into beta.commerce.coinbase.com → Settings → Webhook subscriptions.

Treat that URL like a password — anyone holding it can post events at this venture. It never expires; you rotate it by disconnecting and reconnecting. Deliveries are capped at 300 a minute per venture.

Underpayments

If a customer sends less than the invoice, kitty records what Coinbase says actually arrived rather than the amount you asked for. Your revenue figure stays true to the money.

What it can and cannot do here

One-off payments only — no subscriptions and no failed-payment recovery, because there is no card to re-bill. Refunds happen in Coinbase Commerce and are recorded here when reported.

After it's connected

Test connection proves the key works right now, and names the account it reached — so a member with two logins can see they pasted the wrong one. Do that before you put anything on sale.

Then, in Where new checkouts go, pick this provider on its own or One page, every method, which offers every provider you've connected on a single page and quietly hides one that starts failing.

Anything already on sale keeps the provider it was armed on. A price, once created at a provider, cannot be moved — so to switch, open the venture's Revenue tab, Take off sale, then put it back on sale.

How the keys are stored

Encrypted at rest with AES-256-GCM, used server-side only, never returned to the browser, never written to a log, and never shown again after saving.

Payment keys are scoped to a venture or the whole workspace, never to you personally — two businesses in one workspace settle into two different bank accounts, so a personal key is refused for money on purpose.