Skip to main content

​
Overview

The Payment Links API sandbox environment provides a safe, isolated testing space where you can develop and test your payment link integrations without affecting production data or processing real transactions. The sandbox mirrors production functionality while using test data and simulated payment flows.
Authentication methods, and response formats in sandbox are identical to production, making it easy to transition your code when ready.

​
Key Differences: Sandbox vs Production

FeatureSandboxProduction
API Endpointbusiness.coinbase.com/sandbox/api/v1/payment-linksbusiness.coinbase.com/api/v1/payment-links
API KeysSame CDP API keysSame CDP API keys
TransactionsSimulated (no real value)Real payment processing
WebhooksRequires sandbox: true labelNo label required
Rate LimitsSame as productionStandard production limits
Data Retention30 days (auto-purged)Permanent
Important Limitation: Sandbox transactions are simulated and do not involve real funds. Payments made through sandbox payment links will not appear in your Coinbase Business wallets. This is expected behavior for sandbox testing.Sandbox payments are received using USDC on Base Sepolia testnet. The sandbox uses an arbitrary test address (0xC00Bb0ac72F15C3dBFc6eb58B257887b529fEF57) for receiving payments. You can verify transactions on the Base Sepolia Block Explorer.

​
Getting Started

​
1. Prerequisites

Before using the sandbox environment, ensure you have:
  • A Coinbase Business account
  • CDP API credentials (same keys work for both sandbox and production)
  • Familiarity with the Payment Links API

​
2. Configure Your Application

The only change required to use sandbox is updating your API endpoint to include the /sandbox path segment:
1

Update Base URL

Change your API base URL to include the sandbox path:
- baseURL: 'https://business.coinbase.com/api/v1/payment-links'
+ baseURL: 'https://business.coinbase.com/sandbox/api/v1/payment-links'
2

Create Test Payment Links

Use the same API calls as production to create payment links:
cdpcurl -X POST \
  -i "YOUR_API_KEY_ID" \
  -s "YOUR_API_KEY_SECRET" \
  "https://business.coinbase.com/sandbox/api/v1/payment-links" \
  -d '{
    "amount": "10.00",
    "currency": "USDC",
    "description": "Test payment"
  }'
3

Test Payment Flows

Use the returned payment link URL to test payment flows

​
API Endpoints

All Payment Links API endpoints are available in sandbox with the /sandbox path prefix:
EndpointSandbox URL
Create Payment LinkPOST /sandbox/api/v1/payment-links
List Payment LinksGET /sandbox/api/v1/payment-links
Get Payment LinkGET /sandbox/api/v1/payment-links/{id}
Deactivate Payment LinkDELETE /sandbox/api/v1/payment-links/{id}
The request and response schemas are identical to production. No changes to API contracts are needed when switching between environments.

​
Webhook Events

Sandbox webhook events work the same as production but are differentiated using the sandbox label. This allows you to:
  • Test webhook integration without receiving production events
  • Validate your webhook handler with realistic event payloads
  • Test failure scenarios and retry logic safely

​
Subscribing to Sandbox Webhooks

To receive webhook events for sandbox payment links, create a subscription with "sandbox": "true" in the labels: 
cdpcurl -X POST \
  -i "YOUR_API_KEY_ID" \
  -s "YOUR_API_KEY_SECRET" \
  "https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions" \
  -d '{
    "description": "Sandbox payment link webhooks",
    "eventTypes": [
      "payment_link.payment.success",
      "payment_link.payment.failed",
      "payment_link.payment.expired"
    ],
    "target": {
      "url": "https://your-webhook-url.com/sandbox",
      "method": "POST"
    },
    "labels": {
      "sandbox": "true"
    },
    "isEnabled": true
  }'

​
Webhook Event Types

The same event types are available for both sandbox and production:
Event TypeDescription
payment_link.payment.successPayment link successfully paid
payment_link.payment.failedPayment link payment failed
payment_link.payment.expiredPayment link expired without payment
For complete webhook setup instructions and signature verification, see the Webhooks documentation.

​
Best Practices

Keep sandbox configuration completely separate from production:
// config.ts
const config = {
  sandbox: {
    apiUrl: 'https://business.coinbase.com/sandbox/api/v1/payment-links',
  },
  production: {
    apiUrl: 'https://business.coinbase.com/api/v1/payment-links',
  }
};

export const getConfig = () => {
  return process.env.NODE_ENV === 'production'
    ? config.production
    : config.sandbox;
};
Use sandbox to thoroughly test error scenarios:
  • Invalid authentication
  • Malformed requests
  • Payment failures
  • Expired payment links
Create separate webhook subscriptions for sandbox and production:
// Sandbox subscription - requires sandbox label
{
  "labels": { "sandbox": "true" },
  "target": { "url": "https://your-app.com/webhooks/sandbox" }
}

// Production subscription
{
  "labels": {},
  "target": { "url": "https://your-app.com/webhooks/production" }
}
Create automated test suites that run against sandbox:
describe('Payment Links API Integration', () => {
  const baseUrl = 'https://business.coinbase.com/sandbox/api/v1/payment-links';

  test('should create payment link', async () => {
    const response = await createPaymentLink({
      amount: '10.00',
      currency: 'USDC',
      description: 'Test payment'
    });

    expect(response.id).toBeDefined();
    expect(response.status).toBe('ACTIVE');
  });

  test('should list payment links', async () => {
    const response = await listPaymentLinks();
    expect(Array.isArray(response.data)).toBe(true);
  });
});

​
Limitations & Considerations

Be aware of these sandbox limitations when testing:
  • Simulated Transactions: Sandbox payments do not involve real funds
  • No Wallet Updates: Payments will not appear in your Coinbase app wallet
  • Data Retention: Sandbox data is automatically purged after 30 days
  • Performance: Response times may vary from production
  • Third-Party Services: Some third-party integrations may use mocked responses

​
Transitioning to Production

When you’re ready to move from sandbox to production:
1

Complete Integration Testing

Ensure all features work correctly in sandbox with comprehensive test coverage
2

Review Webhook Configuration

  • Verify you have a webhook subscription for production (no sandbox label needed)
  • Ensure your production webhook endpoint is ready to receive events
3

Update Configuration

Switch from sandbox to production endpoints:
- baseURL: 'https://business.coinbase.com/sandbox/api/v1/payment-links'
+ baseURL: 'https://business.coinbase.com/api/v1/payment-links'
4

Test with Small Amounts

Begin with small payment amounts to verify everything works as expected
5

Monitor Closely

Set up monitoring and alerting for:
  • Failed payments
  • API errors
  • Webhook delivery failures

​
Troubleshooting

Problem: Getting authentication errors in sandboxSolutions:
  • Verify your CDP API keys are valid
  • Check that the API key has the required permissions
  • Ensure the Authorization header is properly formatted
  • Confirm the API key hasn’t expired
Problem: Webhook events are not being delivered for sandbox payment linksSolutions:
  • Verify your subscription has "sandbox": "true" in labels
  • Check that your webhook endpoint is accessible and returns 200 OK
  • Ensure you’re subscribed to the correct event types
  • Review webhook signature verification is implemented correctly
Problem: Completed sandbox payments not showing in Coinbase walletThis is expected behavior: Sandbox payments are simulated and will not appear in your Coinbase wallet. To verify payments, check the payment link status via API or webhook events.
Problem: Code works in sandbox but fails in production (or vice versa)Solutions:
  • Verify all configuration uses environment variables
  • Check for hardcoded sandbox-specific URLs
  • Ensure webhook subscriptions have correct sandbox label values

​
Additional Resources

API Reference

Complete API documentation for Payment Links endpoints

Webhooks Guide

Learn how to set up and verify webhook events

Authentication

Learn how to authenticate your API requests

Postman Collection

Download Postman files for testing