How to Set Up Coinbase Business for XFile Ultra

Coinbase Business (CDP Checkouts API — Commerce successor path in this product) runs hosted crypto/stablecoin checkout. Fulfillment listens for checkout.payment.success on the webhook (legacy charge events are also accepted).

Coinbase Business is built-in — no premium plugin required.

Where to find it

Admin → Settings → Payment → Coinbase Business

1. Turn Enable Coinbase Business checkout on

2. Paste CDP API key ID, CDP API key secret, and Webhook secret

3. Register the webhook for checkout.payment.success

4. Match Sandbox mode to the CDP sandbox/test flow

5. Save settings and test

Enable for reseller (optional): shows this gateway on reseller balance top-up checkout. Member Premium upgrade and member balance top-up use the main Enable toggle only. Reseller enable needs the Reseller System premium plugin.

Fields in XFile Ultra

Field	Setting key	From Coinbase CDP
Enable	`coinbase_commerce_checkout_enabled`	Main on/off
Enable for reseller	`coinbase_commerce_checkout_reseller_enabled`	Reseller top-up
CDP API key ID	`coinbase_commerce_api_key`	JSON `id`
CDP API key secret	`coinbase_commerce_api_secret`	JSON `privateKey` (PEM)
Webhook secret	`coinbase_commerce_webhook_secret`	Subscription secret
Sandbox mode	`coinbase_commerce_test_mode`	Sandbox API path

Webhook URL:

https://YOUR-DOMAIN/api/webhooks/coinbase-commerce

Primary event: checkout.payment.success (optional: failed/expired). In sandbox, add the sandbox label on the subscription.

Return (automatic): /api/checkout/coinbase-commerce/return

Required CDP scopes when creating the key

Enable at least:

Account Read
Customer Read
Customer Write

Do not enable Transfer Write unless you specifically need it for something else.

Env overrides: COINBASE_COMMERCE_API_KEY, COINBASE_COMMERCE_API_SECRET, COINBASE_COMMERCE_WEBHOOK_SECRET, optional COINBASE_COMMERCE_TEST_MODE.

Step 1 — Create CDP API keys

1. Open the Coinbase CDP portal

2. Create Secret API keys for your project

3. On create, enable Account Read, Customer Read, and Customer Write

4. Copy the key id → XFile Ultra CDP API key ID

5. Copy the privateKey PEM → CDP API key secret (newlines are OK)

Step 2 — Webhook subscription

Required event (must subscribe): checkout.payment.success

Optional: failed / expired checkout events (not required for fulfillment).

Without checkout.payment.success, Coinbase can complete payment and XFile Ultra may not grant Premium / balance.

1. In CDP, create a webhook subscription pointing to the admin URL

2. Under event subscriptions / permissions, enable checkout.payment.success (required)

3. For testing with Sandbox mode on, include the sandbox label on that subscription

4. Copy the signing secret into XFile Ultra

Step 3 — Paste into XFile Ultra

1. Admin → Settings → Payment → Coinbase Business

2. Paste key id, private key, webhook secret

3. Turn Sandbox mode on while using the sandbox checkout flow

4. Enable checkout → Save

5. Complete a test checkout on /premium

What is Sandbox / Test mode?

Sandbox (sometimes labeled Test mode) means you use the provider’s test environment — fake cards, fake buyers, no real money. Turn it on while learning. When you go live:

1. Turn Sandbox / Test mode off

2. Paste live keys (not test keys)

3. Register live webhooks (Stripe/PayPal have separate Test vs Live webhook endpoints)

Same CDP keys are reused; Sandbox mode changes the API path. Keep webhook subscriptions labeled for sandbox while testing.

Common problems

Scope / Checkouts API errors

Key missing Account/Customer Read/Write. Recreate the key with the scopes above.

Webhook signature errors

Secret rotated in Coinbase but not updated in admin, or live webhook used while Sandbox is on.

Paid at Coinbase, unpaid on site

Webhook not delivered or wrong event. Check CDP webhook delivery logs.