Skip to main content

​
Overview

Migrate from Commerce Charge API to Payment Link API for improved reliability, simplified integration, and modern authentication. This guide covers the key changes and provides code examples to help you update your integration.
Payment Link API requires a Coinbase Business account.
1

Update authentication

Switch from API key to JWT Bearer tokens
2

Change base URL

From api.commerce.coinbase.com to business.coinbase.com/api/v1
3

Update request/response handling

New field names and flattened structure
4

Implement status monitoring

Use webhooks for real-time notifications or polling
5

Test thoroughly

New ID formats and status values require updates to your logic

​
Key differences

ComponentCharge API (Commerce)Payment Link API
Base URLhttps://api.commerce.coinbase.comhttps://business.coinbase.com/api/v1
AuthenticationX-CC-Api-Key headerBearer token with CDP API key
Primary resourceChargePayment Link
ID formatUUID24-character hexadecimal
Payment URL fieldhosted_urlurl
Payment Link API requires CDP API key authentication.

​
Status and field mappings

FeatureCharge APIPayment Link API
Status valuesNEW, SIGNED, PENDING, COMPLETED, EXPIRED, FAILEDACTIVE, COMPLETED, DEACTIVATED, EXPIRED, FAILED
Amount structurelocal_price.amount and local_price.currencyamount and currency (flat structure)
Network specificationAuto-selectedExplicit network field
Redirect URLsredirect_url, cancel_urlsuccessRedirectUrl, failRedirectUrl

​
Migration checklist

​
1. Update authentication

  • Create CDP API keys
  • Implement JWT Bearer token generation
  • Update API key storage and rotation procedures
  • Test authentication with Payment Link API

​
2. Update API integration

  • Update base URL to https://business.coinbase.com/api/v1
  • Modify request bodies to match new schema
  • Update response parsing to handle new field names
  • Implement idempotency key generation for create requests

​
3. Handle status changes

  • Map Charge statuses to Payment Link statuses in your system
  • Update order fulfillment logic for new status values
  • Set up webhooks for real-time payment notifications (see Webhooks documentation)
  • Update customer-facing status messages

​
4. Update payment flows

  • Use url field instead of hosted_url for payment pages
  • Update redirect URL parameters
  • Test full payment flow end-to-end
  • Verify metadata is correctly passed through

​
5. Handle pagination

  • Update list operations to use pageSize and pageToken
  • Implement nextPageToken handling for multiple pages
  • Test pagination with large datasets

​
6. Test and validate

  • Consider testing your integration with the sandbox environment
  • Verify amount calculations (ensure proper decimal handling)
  • Test expired payment link scenarios
  • Test deactivation flow
  • Verify metadata preservation
  • Test redirect URLs

​
7. Monitor and observe

  • Set up monitoring for API errors
  • Track payment success rates
  • Monitor payment link expiration rates
  • Set up alerts for failed payments
  • API & Schema Mapping - Detailed endpoint and response comparisons with code examples
  • FAQ - Common questions and troubleshooting