Skip to main content
POST
/
api
/
v1
/
checkouts
Create Checkout
curl --request POST \
  --url https://business.coinbase.com/api/v1/checkouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": "100.50",
  "currency": "USDC",
  "network": "base",
  "description": "Payment for order #12345",
  "expiresAt": "2026-03-20T10:30:00Z",
  "metadata": {
    "invoiceId": "12345",
    "reference": "Payment for invoice #12345",
    "customerId": "cust_abc123"
  },
  "successRedirectUrl": "https://example.com/success",
  "failRedirectUrl": "https://example.com/failed"
}
'
{
  "id": "68f7a946db0529ea9b6d3a12",
  "url": "https://payments.coinbase.com/payment-links/pl_01h8441j23abcd1234567890ef",
  "status": "ACTIVE",
  "amount": "100.50",
  "currency": "USDC",
  "network": "base",
  "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "createdAt": "2024-03-20T10:30:00Z",
  "updatedAt": "2024-03-20T10:30:00Z",
  "tokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "description": "Payment for order #12345",
  "metadata": {
    "invoiceId": "12345",
    "reference": "Payment for invoice #12345",
    "customerId": "cust_abc123"
  },
  "settlement": {
    "totalAmount": "100.00",
    "feeAmount": "1.25",
    "netAmount": "98.75",
    "currency": "USDC"
  },
  "transactionHash": "0x3a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b",
  "expiresAt": "2024-03-20T10:30:00Z",
  "successRedirectUrl": "https://example.com/success",
  "failRedirectUrl": "https://example.com/failed"
}

Authorizations

​
Authorization
string
header
required

A JWT signed using your CDP API Key Secret, encoded in base64. Refer to the Generate Bearer Token section of our Authentication docs for information on how to generate your Bearer Token.

Headers

​
X-Idempotency-Key
string

An optional UUID v4 request header for making requests safely retryable.

Required string length: 36
Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Body

application/json
​
amount
string
required

The payment amount as a string for precise decimal representation. Must be between 0.01 and 100000000 (100 million). Must have at most 2 decimal places.

Pattern: ^\d+(\.\d{1,2})?$
Example:

"100.50"

​
currency
string
required

The currency code for the payment. Only USDC is currently supported.

Required string length: 1 - 10
Example:

"USDC"

​
network
enum<string>
default:base

The blockchain network for the payment. Defaults to base if not specified. More networks will be added in the future.

Available options:
base
Example:

"base"

​
description
string

Human-readable description of the payment.

Maximum string length: 500
Example:

"Payment for order #12345"

​
expiresAt
string<date-time>

Optional expiration timestamp for the checkout in RFC 3339 format. Must be a future timestamp. After this time, the checkout will be automatically expired and cannot accept new payments. If not provided, defaults to 1 hour from creation time.

Example:

"2026-03-20T10:30:00Z"

​
metadata
object

Optional metadata as key-value pairs to be passed through the payment flow.

Example:
{
  "invoiceId": "12345",
  "reference": "Payment for invoice #12345",
  "customerId": "cust_abc123"
}
​
successRedirectUrl
string<uri>

URL to redirect to on successful payment. Must use HTTPS protocol.

Maximum string length: 2048
Pattern: ^https://.*
Example:

"https://example.com/success"

​
failRedirectUrl
string<uri>

URL to redirect to on failed payment. Must use HTTPS protocol.

Maximum string length: 2048
Pattern: ^https://.*
Example:

"https://example.com/failed"

Response

Checkout created successfully.

​
id
string
required

Unique checkout identifier.

Pattern: ^[0-9a-f]{24}$
Example:

"68f7a946db0529ea9b6d3a12"

​
url
string<uri>
required

The generated checkout URL.

Example:

"https://payments.coinbase.com/payment-links/pl_01h8441j23abcd1234567890ef"

​
status
enum<string>
required

The status of the checkout.

  • ACTIVE The checkout is active and can accept payments.
  • PROCESSING The checkout is processing a payment.
  • DEACTIVATED The checkout has been manually deactivated.
  • EXPIRED The checkout has expired based on the expiresAt timestamp.
  • COMPLETED The checkout has been successfully paid.
  • FAILED The checkout has failed due to a payment error.
Available options:
ACTIVE,
PROCESSING,
DEACTIVATED,
EXPIRED,
COMPLETED,
FAILED
Example:

"ACTIVE"

​
amount
string
required

Numeric value representing the amount (maximum 2 decimal places).

Example:

"100.50"

​
currency
string
required

The currency code for the amount.

Example:

"USDC"

​
network
enum<string>
default:base
required

The blockchain network for the payment. Defaults to base if not specified. More networks will be added in the future.

Available options:
base
Example:

"base"

​
address
string
required

The merchant's blockchain receiving address for this checkout.

Example:

"0x742d35Cc6634C0532925a3b844Bc454e4438f44e"

​
createdAt
string<date-time>
required

Timestamp in RFC 3339 format.

Example:

"2024-03-20T10:30:00Z"

​
updatedAt
string<date-time>
required

Timestamp in RFC 3339 format.

Example:

"2024-03-20T10:30:00Z"

​
tokenAddress
string

The token contract address on the network. Only present for non-native tokens.

Example:

"0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"

​
description
string

Human-readable description of the payment.

Example:

"Payment for order #12345"

​
metadata
object

Optional metadata as key-value pairs to be passed through the payment flow.

Example:
{
  "invoiceId": "12345",
  "reference": "Payment for invoice #12345",
  "customerId": "cust_abc123"
}
​
settlement
object

Fee breakdown for a completed payment.

​
transactionHash
string

The on-chain transaction hash. Only present when status is COMPLETED.

Example:

"0x3a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b"

​
expiresAt
string<date-time>

Timestamp in RFC 3339 format.

Example:

"2024-03-20T10:30:00Z"

​
successRedirectUrl
string<uri>

Optional URL to redirect the user to after successful payment authorization.

Example:

"https://example.com/success"

​
failRedirectUrl
string<uri>

Optional URL to redirect the user to after failed payment authorization.

Example:

"https://example.com/failed"