Coinbase Commerce

You are integrating Coinbase Commerce (via the Onchain Payment Protocol / Coinbase Business API) as a crypto payment gateway into a [Django / Next.js / etc.] application.

## IMPORTANT CONTEXT BEFORE YOU START
Coinbase shut down the standalone Commerce portal on March 31, 2026 and migrated merchant tooling into Coinbase Business. As of April 2026, Coinbase Business is only available to merchants in the **United States and Singapore**. If your merchant is outside these two countries, stop here — use BitPay, NOWPayments, MoonPay, or Request Network instead. Do not build new Coinbase Commerce integrations for unsupported regions.

## Setup (US / SG merchants)
1. Sign up at https://www.coinbase.com/commerce and verify your business identity.
2. Generate an API key from Settings → API Keys.
3. Generate a webhook shared secret from Settings → Webhooks → Show shared secret.
4. Store both in environment variables — NEVER hardcode them:
   - `COINBASE_COMMERCE_API_KEY`
   - `COINBASE_COMMERCE_WEBHOOK_SECRET`
5. Base URL: `https://api.commerce.coinbase.com`
6. Set your settlement currency to **USDC** in the dashboard to avoid price volatility between checkout and settlement.

## Authentication
All API requests authenticate with two headers:

```python
headers = {
    "X-CC-Api-Key": settings.COINBASE_COMMERCE_API_KEY,
    "X-CC-Version": "2018-03-22",
    "Content-Type": "application/json",
}
```

## Recommended Integration: Hosted Checkout via Charges API
The simplest, lowest-risk integration is to create a charge server-side and redirect the buyer to Coinbase's hosted checkout page.

### Server-side (Create Charge):
```python
import requests

def create_charge(amount_usd, order_id, product_name):
    response = requests.post(
        "https://api.commerce.coinbase.com/charges",
        headers={
            "X-CC-Api-Key": settings.COINBASE_COMMERCE_API_KEY,
            "X-CC-Version": "2018-03-22",
            "Content-Type": "application/json",
        },
        json={
            "name": product_name,
            "description": f"Order {order_id}",
            "pricing_type": "fixed_price",
            "local_price": {
                "amount": f"{amount_usd:.2f}",
                "currency": "USD",
            },
            "metadata": {
                "order_id": str(order_id),
                "customer_email": "[email protected]",
            },
            "redirect_url": "https://yoursite.com/payment-success/",
            "cancel_url": "https://yoursite.com/payment-cancelled/",
        },
    )
    response.raise_for_status()
    charge = response.json()["data"]
    # charge["hosted_url"] — redirect the buyer here
    # charge["id"] — store this to reconcile with webhooks
    return charge
```

## Webhook Handling (Critical)
Never trust the client-side redirect alone — always confirm payment via webhooks, which are signed.

1. Register your webhook endpoint in the dashboard under Settings → Webhooks.
2. Subscribe to the events you need: `charge:created`, `charge:confirmed`, `charge:failed`, `charge:delayed`, `charge:pending`, `charge:resolved`.
3. **Always verify the signature before trusting the payload.** Use the RAW request body, not a parsed/re-serialized version:

```python
import hmac
import hashlib
from django.http import HttpResponse, HttpResponseBadRequest
from django.views.decorators.csrf import csrf_exempt

@csrf_exempt
def coinbase_webhook(request):
    raw_body = request.body  # bytes, do NOT decode/re-encode
    signature = request.META.get("HTTP_X_CC_WEBHOOK_SIGNATURE", "")

    expected = hmac.new(
        settings.COINBASE_COMMERCE_WEBHOOK_SECRET.encode(),
        raw_body,
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        return HttpResponseBadRequest("Invalid signature")

    event = json.loads(raw_body)
    event_type = event["event"]["type"]
    charge = event["event"]["data"]

    # Idempotency: check if we've already processed this event.id
    if Event.objects.filter(provider_event_id=event["event"]["id"]).exists():
        return HttpResponse(status=200)

    if event_type == "charge:confirmed":
        order_id = charge["metadata"].get("order_id")
        # Fulfill the order — be sure to verify amount and currency match
        fulfill_order(order_id, charge)
    elif event_type == "charge:failed":
        mark_order_failed(charge["metadata"].get("order_id"))

    Event.objects.create(provider_event_id=event["event"]["id"])
    return HttpResponse(status=200)
```

4. Return 200 quickly, then process asynchronously for slow work (emails, downstream APIs).
5. Coinbase retries failed webhook deliveries — make your handler idempotent by recording `event.id`.

## Security Best Practices
- Never expose your API key in client-side code. All charge creation happens server-side.
- Always verify the webhook signature against the raw body — do not parse JSON and re-serialize before comparison.
- Set USDC as your settlement currency to avoid volatility between payment and payout.
- Withdraw to a self-custody wallet regularly rather than parking funds in the Coinbase Business balance.
- Rotate API keys if a deployment log, CI secret, or environment file is ever exposed.
- **NEVER enter your seed phrase into a web form, even one that appears to be Coinbase.** Use the dashboard or desktop wallet flow for migrations.

## Testing
- Coinbase Commerce does not provide a dedicated sandbox with test networks; you typically test with small real payments on low-cost networks like Base.
- Use the webhook test feature in the dashboard (Settings → Webhooks → Test webhook) to validate your signature verification without a live payment.
- Verify your idempotency handling by replaying the same webhook event multiple times.

## Common Gotchas
- **Amounts are strings, not numbers.** `"amount": "20.00"` — always two decimal places for USD.
- **No native Bitcoin.** BTC on the Bitcoin mainnet is not supported since 2024. Wrapped BTC and Bitcoin Cash are.
- **No recurring billing primitive.** Build subscriptions with manual reminders, your own onchain contracts, or a separate recurring billing layer (e.g., Stripe for fiat + Commerce for crypto).
- **Crypto payments are final.** No chargebacks means no reversals — design your refund policy around manual, off-chain refunds.
- **Regional restrictions.** Do not integrate for merchants outside US/SG; they cannot currently use Coinbase Business.
- **Signature verification is case-sensitive on the header name.** Read `X-CC-Webhook-Signature` exactly.
- **Expiration.** Charges expire after 1 hour of no payment — handle `charge:failed` events with `timeout` reason gracefully.