Skip to main content

​
API endpoint mapping

​
Create a payment request

  • Charge API
POST https://api.commerce.coinbase.com/charges
X-CC-Api-Key: YOUR_API_KEY

{
  "name": "Order #12345",
  "description": "Payment for order #12345",
  "pricing_type": "fixed_price",
  "local_price": {
    "amount": "100.00",
    "currency": "USD"
  },
  "redirect_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel",
  "metadata": {
    "order_id": "12345",
    "customer_id": "cust_abc123"
  }
}
  • Amount is now a direct string field (not nested in local_price)
  • Currency is specified directly (Payment Link API currently supports USDC)
  • Network specification is now explicit (defaults to base)
  • Redirect URLs have been renamed for clarity
  • name field is removed; use description instead
  • Idempotency is supported via X-Idempotency-Key header

​
List payment requests

  • Charge API
GET https://api.commerce.coinbase.com/charges
X-CC-Api-Key: YOUR_API_KEY
  • Pagination uses pageSize and pageToken instead of Commerce’s cursor-based approach
  • Can filter by status (ACTIVE, DEACTIVATED, EXPIRED, COMPLETED)
  • Response includes nextPageToken for retrieving next page

​
Retrieve a specific payment request

  • Charge API
GET https://api.commerce.coinbase.com/charges/{charge_code_or_charge_id}
X-CC-Api-Key: YOUR_API_KEY
  • Use the payment link ID (24-character hexadecimal format)
  • No support for retrieval by code (use ID only)

​
Cancel/deactivate a payment request

  • Charge API
No explicit endpoint available
- Charges expire based on expires_at timestamp
- Cannot manually cancel active charges
  • Explicit deactivation endpoint available
  • Deactivated payment links cannot accept further payments
  • Status changes to DEACTIVATED

​
Response schema mapping

​
Payment details

Charge API FieldPayment Link API FieldNotes
ididFormat changed from UUID to 24-character hexadecimal
codeN/ACode not available in Payment Link API
hosted_urlurlThe shareable payment URL
namedescriptionName field replaced by description
descriptiondescriptionSame purpose
pricing.local.amountamountFlattened structure
pricing.local.currencycurrencyFlattened structure
N/AnetworkNew field specifying blockchain network
N/AaddressNew field with destination blockchain address
N/AtokenAddressNew field with token contract address
expires_atexpiresAtSame purpose, RFC 3339 format
metadatametadataSame purpose
redirect_urlsuccessRedirectUrlRenamed for clarity
cancel_urlfailRedirectUrlRenamed for clarity
created_atcreatedAtSame purpose, RFC 3339 format
N/AupdatedAtNew field tracking last update
timelinestatusStatus now a single field instead of timeline array
web3_dataN/ATransaction details handled differently

​
Status mapping

Understanding status transitions is crucial for order fulfillment:
Charge API StatusPayment Link API StatusDescription
NEWACTIVEPayment request is active and awaiting payment
SIGNEDACTIVEIn Payment Link, signing happens within the payment flow
PENDING(Check via transaction monitoring)Payment detected, awaiting confirmation
COMPLETEDCOMPLETEDPayment confirmed and finalized
EXPIREDEXPIREDPayment request expired without payment
FAILED(Handled via monitoring)Payment attempt failed
N/ADEACTIVATEDPayment link manually deactivated
Important considerations:
  • Payment Link API focuses on the link status, not individual transaction status
  • Monitor payments using the blockchain address provided in the response
  • Consider integrating with webhooks or polling the address for transaction updates
  • Once a payment is detected and confirmed, the status changes to COMPLETED

​
Webhooks

​
Charge API webhooks

Commerce provides webhook events:
  • charge:created
  • charge:pending
  • charge:confirmed
  • charge:failed
Currently, Payment Link API does not have built-in webhook support. Consider these alternatives:
  1. Polling: Periodically check payment link status via GET endpoint
  2. Blockchain Monitoring: Monitor the provided blockchain address for incoming transactions
  3. Transaction History: Use Coinbase Business API to monitor transaction history
Webhook support for Payment Link API may be added in future updates. Check the latest documentation for updates.

​
Node.js implementation examples

  • Charge API
const axios = require('axios');

async function createCharge(orderData) {
  const response = await axios.post(
    'https://api.commerce.coinbase.com/charges',
    {
      name: orderData.name,
      description: orderData.description,
      pricing_type: 'fixed_price',
      local_price: {
        amount: orderData.amount,
        currency: 'USD'
      },
      redirect_url: orderData.successUrl,
      cancel_url: orderData.cancelUrl,
      metadata: orderData.metadata
    },
    {
      headers: {
        'X-CC-Api-Key': process.env.COMMERCE_API_KEY,
        'Content-Type': 'application/json'
      }
    }
  );

  return {
    id: response.data.id,
    hostedUrl: response.data.hosted_url,
    expiresAt: response.data.expires_at
  };
}

async function getChargeStatus(chargeId) {
  const response = await axios.get(
    `https://api.commerce.coinbase.com/charges/${chargeId}`,
    {
      headers: {
        'X-CC-Api-Key': process.env.COMMERCE_API_KEY
      }
    }
  );

  const timeline = response.data.timeline;
  const currentStatus = timeline[timeline.length - 1].status;

  return currentStatus;
}