Skip to main content
POST
/
api
/
v1
/
payment-links
Create Payment Link
curl --request POST \
  --url https://business.coinbase.com/api/v1/payment-links \
  --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://pay.coinbase.com/pl_01h8441j23abcd1234567890ef",
  "status": "ACTIVE",
  "amount": "100.50",
  "currency": "USDC",
  "network": "base",
  "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "description": "Payment for order #12345",
  "expiresAt": "2024-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",
  "createdAt": "2024-03-20T10:30:00Z",
  "updatedAt": "2024-03-20T10:30:00Z",
  "settlement": {
    "totalAmount": "100.00",
    "feeAmount": "1.25",
    "netAmount": "98.75"
  }
}

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

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).

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 length: 500
Example:

"Payment for order #12345"

​
expiresAt
string<date-time>

Optional expiration timestamp for the payment link in RFC 3339 format. Must be a future timestamp. After this time, the link will be automatically expired and cannot accept new payments. If not provided, defaults to 1 year 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 length: 2048
Example:

"https://example.com/success"

​
failRedirectUrl
string<uri>

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

Maximum length: 2048
Example:

"https://example.com/failed"

Response

Payment link created successfully.

​
id
string
required

Unique payment link identifier.

Example:

"68f7a946db0529ea9b6d3a12"

​
url
string<uri>
required

The generated payment link URL.

Example:

"https://pay.coinbase.com/pl_01h8441j23abcd1234567890ef"

​
status
enum<string>
required

The status of the payment link.

  • ACTIVE The payment link is active and can accept payments.
  • DEACTIVATED The payment link has been manually deactivated.
  • EXPIRED The payment link has expired based on the expiresAt timestamp.
  • COMPLETED The payment link has been successfully paid.
Available options:
ACTIVE,
DEACTIVATED,
EXPIRED,
COMPLETED
Example:

"ACTIVE"

​
amount
string
required

Numeric value representing the amount.

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 blockchain address where funds should be sent.

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 (for ERC-20 tokens).

Example:

"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"

​
description
string

Human-readable description of the payment.

Example:

"Payment for order #12345"

​
expiresAt
string<date-time>

Timestamp in RFC 3339 format.

Example:

"2024-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>

Optional URL to redirect the user to after successful payment authorization. This indicates the user has successfully authorized the payment, not that the payment has been completed.

Example:

"https://example.com/success"

​
failRedirectUrl
string<uri>

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

Example:

"https://example.com/failed"

​
settlement
object

Financial breakdown of the payment link transaction showing the total amount charged, fees deducted, and net amount received.