Skip to main content

​
Overview

Migrate from the Payment Link API to the Checkouts API for improved reliability and a modernized response schema. This guide covers the key changes and provides code examples to help you update your integration.
1

Update base URL

From api/v1/payment-links to api/v1/checkouts
2

Update request/response handling

New field names and response schema
3

Update webhook event types

From payment_link.* to checkout.* events
4

Update ID references

Same 24-character hexadecimal format, new resource type
5

Test thoroughly

Verify status values, webhook payloads, and redirect flows

​
Key differences

ComponentPayment Link APICheckouts API
Base URLhttps://business.coinbase.com/api/v1/payment-linkshttps://business.coinbase.com/api/v1/checkouts
Resource namePayment LinkCheckout
Path parameterpaymentLinkIdid
List response keypaymentLinkscheckouts

​
Webhook event mapping

Payment Link API EventCheckouts API Event
payment_link.payment.successcheckout.payment.success
payment_link.payment.failedcheckout.payment.failed
payment_link.payment.expiredcheckout.payment.expired

​
Migration checklist

​
1. Update API integration

  • Update base URL to https://business.coinbase.com/api/v1/checkouts
  • Update path parameter from paymentLinkId to id
  • Update list response parsing from paymentLinks to checkouts

​
2. Update webhook subscriptions

  • Create new webhook subscriptions with checkout.* event types
  • Keep existing payment_link.* subscriptions until migration is complete
  • Delete old subscriptions once fully migrated

​
3. Update status handling

  • Status values are identical (ACTIVE, PROCESSING, DEACTIVATED, EXPIRED, COMPLETED, FAILED)
  • No changes to fulfillment logic for status transitions

​
4. Test and validate

  • Test in the sandbox environment
  • Verify all webhook event types are handled correctly
  • Verify redirect URLs still function correctly

​
5. Monitor and observe

  • Keep both subscriptions running in parallel during transition
  • Monitor for any missed events
  • Cut over fully once confident in new integration
  • API & Schema Mapping - Detailed endpoint and response comparisons with code examples
  • FAQ - Common questions and troubleshooting