> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloud.coinbase.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API & Schema Mapping
## API endpoint mapping
### Create a payment request
```bash theme={null}
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"
}
}
```
```bash theme={null}
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"
}
}
```
* Request body schema is identical — no changes required
* Only the URL path changes from `/payment-links` to `/checkouts`
### List payment requests
```bash theme={null}
GET https://business.coinbase.com/api/v1/payment-links?pageSize=20&status=ACTIVE
Authorization: Bearer YOUR_JWT_TOKEN
```
```bash theme={null}
GET https://business.coinbase.com/api/v1/checkouts?pageSize=20&status=ACTIVE
Authorization: Bearer YOUR_JWT_TOKEN
```
* Response key changes from `paymentLinks` to `checkouts`
* Pagination (`pageSize`, `pageToken`, `nextPageToken`) is unchanged
* Status filter values are unchanged
### Retrieve a specific payment request
```bash theme={null}
GET https://business.coinbase.com/api/v1/payment-links/{paymentLinkId}
Authorization: Bearer YOUR_JWT_TOKEN
```
```bash theme={null}
GET https://business.coinbase.com/api/v1/checkouts/{id}
Authorization: Bearer YOUR_JWT_TOKEN
```
* Path parameter renamed from `paymentLinkId` to `id`
* ID format (24-character hexadecimal) is unchanged
### Deactivate a payment request
```bash theme={null}
POST https://business.coinbase.com/api/v1/payment-links/{paymentLinkId}/deactivate
Authorization: Bearer YOUR_JWT_TOKEN
```
```bash theme={null}
POST https://business.coinbase.com/api/v1/checkouts/{id}/deactivate
Authorization: Bearer YOUR_JWT_TOKEN
```
* 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
```bash lines theme={null}
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
```
```bash lines theme={null}
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
```javascript theme={null}
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;
}
```
```javascript theme={null}
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;
}
```