API & Schema Mapping

API endpoint mapping

Create a payment request

Payment Link API
Checkouts API

POST https://business.coinbase.com/api/v1/payment-links
Authorization: Bearer YOUR_JWT_TOKEN
X-Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324

{
  "amount": "100.00",
  "currency": "USDC",
  "network": "base",
  "description": "Payment for order #12345",
  "expiresAt": "2024-12-31T23:59:59Z",
  "successRedirectUrl": "https://example.com/success",
  "failRedirectUrl": "https://example.com/failed",
  "metadata": {
    "order_id": "12345",
    "customer_id": "cust_abc123"
  }
}

POST https://business.coinbase.com/api/v1/checkouts
Authorization: Bearer YOUR_JWT_TOKEN
X-Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324

{
  "amount": "100.00",
  "currency": "USDC",
  "network": "base",
  "description": "Payment for order #12345",
  "expiresAt": "2024-12-31T23:59:59Z",
  "successRedirectUrl": "https://example.com/success",
  "failRedirectUrl": "https://example.com/failed",
  "metadata": {
    "order_id": "12345",
    "customer_id": "cust_abc123"
  }
}

Key changes

Request body schema is identical — no changes required
Only the URL path changes from /payment-links to /checkouts

List payment requests

Payment Link API
Checkouts API

GET https://business.coinbase.com/api/v1/payment-links?pageSize=20&status=ACTIVE
Authorization: Bearer YOUR_JWT_TOKEN

GET https://business.coinbase.com/api/v1/checkouts?pageSize=20&status=ACTIVE
Authorization: Bearer YOUR_JWT_TOKEN

Key changes

Response key changes from paymentLinks to checkouts
Pagination (pageSize, pageToken, nextPageToken) is unchanged
Status filter values are unchanged

Retrieve a specific payment request

Payment Link API
Checkouts API

GET https://business.coinbase.com/api/v1/payment-links/{paymentLinkId}
Authorization: Bearer YOUR_JWT_TOKEN

GET https://business.coinbase.com/api/v1/checkouts/{id}
Authorization: Bearer YOUR_JWT_TOKEN

Key changes

Path parameter renamed from paymentLinkId to id
ID format (24-character hexadecimal) is unchanged

Deactivate a payment request

Payment Link API
Checkouts API

POST https://business.coinbase.com/api/v1/payment-links/{paymentLinkId}/deactivate
Authorization: Bearer YOUR_JWT_TOKEN

POST https://business.coinbase.com/api/v1/checkouts/{id}/deactivate
Authorization: Bearer YOUR_JWT_TOKEN

Key changes

Path parameter renamed from paymentLinkId to id
Behavior is identical — only ACTIVE resources can be deactivated

Response schema mapping

Payment details

Payment Link API Field	Checkouts API Field	Notes
`id`	`id`	Same format (24-character hexadecimal)
`url`	`url`	Same purpose
`status`	`status`	Same values (ACTIVE, PROCESSING, DEACTIVATED, EXPIRED, COMPLETED, FAILED)
`amount`	`amount`	Unchanged
`currency`	`currency`	Unchanged
`network`	`network`	Unchanged
`address`	`address`	Unchanged
`tokenAddress`	`tokenAddress`	Unchanged
`description`	`description`	Unchanged
`metadata`	`metadata`	Unchanged
`expiresAt`	`expiresAt`	Unchanged
`successRedirectUrl`	`successRedirectUrl`	Unchanged
`failRedirectUrl`	`failRedirectUrl`	Unchanged
`createdAt`	`createdAt`	Unchanged
`updatedAt`	`updatedAt`	Unchanged
`settlement`	`settlement`	Unchanged
`transactionHash`	`transactionHash`	Unchanged

Webhook event mapping

Updating your subscriptions

Payment Link API subscription
Checkouts API subscription

cdp data webhooks subscriptions create \
  description="Payment link status webhook" \
  'eventTypes:=["payment_link.payment.success","payment_link.payment.failed","payment_link.payment.expired"]' \
  target.url=https://your-webhook-url.com \
  target.method=POST \
  isEnabled:=true

cdp data webhooks subscriptions create \
  description="Checkout status webhook" \
  'eventTypes:=["checkout.payment.success","checkout.payment.failed","checkout.payment.expired"]' \
  target.url=https://your-webhook-url.com \
  target.method=POST \
  isEnabled:=true

Event type mapping

Payment Link API Event	Checkouts API Event
`payment_link.payment.success`	`checkout.payment.success`
`payment_link.payment.failed`	`checkout.payment.failed`
`payment_link.payment.expired`	`checkout.payment.expired`

Node.js implementation examples

Payment Link API
Checkouts API

const axios = require('axios');
const { v4: uuidv4 } = require('uuid');

function generateBearerToken() {
  // Refer to authentication docs
  return 'YOUR_JWT_TOKEN';
}

async function createPaymentLink(orderData) {
  const response = await axios.post(
    'https://business.coinbase.com/api/v1/payment-links',
    {
      amount: orderData.amount,
      currency: 'USDC',
      network: 'base',
      description: orderData.description,
      successRedirectUrl: orderData.successUrl,
      failRedirectUrl: orderData.failUrl,
      metadata: orderData.metadata
    },
    {
      headers: {
        'Authorization': `Bearer ${generateBearerToken()}`,
        'Content-Type': 'application/json',
        'X-Idempotency-Key': uuidv4()
      }
    }
  );

  return {
    id: response.data.id,
    url: response.data.url,
    expiresAt: response.data.expiresAt
  };
}

async function getStatus(id) {
  const response = await axios.get(
    `https://business.coinbase.com/api/v1/payment-links/${id}`,
    { headers: { 'Authorization': `Bearer ${generateBearerToken()}` } }
  );
  return response.data.status;
}

const axios = require('axios');
const { v4: uuidv4 } = require('uuid');

function generateBearerToken() {
  // Refer to authentication docs
  return 'YOUR_JWT_TOKEN';
}

async function createCheckout(orderData) {
  const response = await axios.post(
    'https://business.coinbase.com/api/v1/checkouts',  // only URL changes
    {
      amount: orderData.amount,
      currency: 'USDC',
      network: 'base',
      description: orderData.description,
      successRedirectUrl: orderData.successUrl,
      failRedirectUrl: orderData.failUrl,
      metadata: orderData.metadata
    },
    {
      headers: {
        'Authorization': `Bearer ${generateBearerToken()}`,
        'Content-Type': 'application/json',
        'X-Idempotency-Key': uuidv4()
      }
    }
  );

  return {
    id: response.data.id,
    url: response.data.url,
    expiresAt: response.data.expiresAt
  };
}

async function getStatus(id) {
  const response = await axios.get(
    `https://business.coinbase.com/api/v1/checkouts/${id}`,  // only URL changes
    { headers: { 'Authorization': `Bearer ${generateBearerToken()}` } }
  );
  return response.data.status;
}

GET STARTED

WALLETS

PAYMENTS

STABLECOINS

TRADING

ONCHAIN TOOLS

CUSTOMERS

WEBHOOKS

CONSUMER APIS

BUSINESS APIS

INSTITUTIONAL APIS

API endpoint mapping

Create a payment request

List payment requests

Retrieve a specific payment request

Deactivate a payment request

Response schema mapping

Payment details

Webhook event mapping

Updating your subscriptions

Event type mapping

Node.js implementation examples

​API endpoint mapping

​Create a payment request

​List payment requests

​Retrieve a specific payment request

​Deactivate a payment request

​Response schema mapping

​Payment details

​Webhook event mapping

​Updating your subscriptions

​Event type mapping

​Node.js implementation examples

API endpoint mapping

Create a payment request

List payment requests

Retrieve a specific payment request

Deactivate a payment request

Response schema mapping

Payment details

Webhook event mapping

Updating your subscriptions

Event type mapping

Node.js implementation examples