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",
  "description": "Payment for order #12345",
  "metadata": {
    "invoiceId": "12345",
    "reference": "Payment for invoice #12345",
    "customerId": "cust_abc123"
  },
  "successRedirectUrl": "https://example.com/success",
  "failRedirectUrl": "https://example.com/failed",
  "expiresAt": "2026-03-20T10:30:00Z"
}
'
{
  "id": "68f7a946db0529ea9b6d3a12",
  "url": "https://payments.coinbase.com/payment-links/pl_01h8441j23abcd1234567890ef",
  "amount": "100.50",
  "currency": "USDC",
  "network": "base",
  "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "createdAt": "2024-03-20T10:30:00Z",
  "updatedAt": "2024-03-20T10:30:00Z",
  "status": "ACTIVE",
  "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",
  "settlement": {
    "totalAmount": "100.00",
    "feeAmount": "1.25",
    "netAmount": "98.75",
    "currency": "USDC"
  },
  "fiatAmount": "100.00",
  "fiatCurrency": "USD",
  "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "refundedAmount": "25.00",
  "refunds": [
    {
      "id": "<string>",
      "checkoutId": "<string>",
      "amount": "<string>",
      "status": "PENDING",
      "createdAt": "2024-03-20T10:30:00Z",
      "currency": "USDC",
      "reason": "<string>",
      "transactionHash": "<string>",
      "completedAt": "2024-03-20T10:30:00Z",
      "fiatAmount": "<string>",
      "fiatCurrency": "<string>",
      "exchangeRate": "<string>"
    }
  ]
}

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

Request to create a payment link.

​
amount
string
required

The payment amount. Must be between 0.01 and 100000000 USD (100 million USD). Must have at most 2 decimal places.

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

"100.50"

​
currency
string
required

The currency code for the payment amount.

  • USDC: Amount is used directly (no conversion)
  • Fiat currencies (USD, EUR, SGD, GBP, etc.): Amount is converted to USDC using exchange rate at time of creation.
Required string length: 1 - 10
Example:

"USDC"

​
description
string

Human-readable description of the payment.

Maximum string length: 500
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"
}
​
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"

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

Response

Payment link created successfully.

​
id
string
required

Unique payment identifier.

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

"68f7a946db0529ea9b6d3a12"

​
url
string<uri>
required

The hosted payment page URL.

Example:

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

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

​
status
enum<string>
required

The status of the payment.

  • ACTIVE The payable endpoint is active and can accept payments.
  • PROCESSING The payment is being processed.
  • DEACTIVATED The payable endpoint has been manually deactivated.
  • EXPIRED The payable endpoint has expired based on the expiresAt timestamp.
  • COMPLETED The payable endpoint has been successfully paid.
  • FAILED The payment has failed due to a payment error.
  • REFUNDED The payment has been fully refunded.
  • PARTIALLY_REFUNDED The payment has been partially refunded.
Available options:
ACTIVE,
PROCESSING,
DEACTIVATED,
EXPIRED,
COMPLETED,
FAILED,
REFUNDED,
PARTIALLY_REFUNDED
Example:

"ACTIVE"

​
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 transaction showing the total amount charged, fees deducted, and net amount received.

​
fiatAmount
string

The original amount in fiat currency before conversion to USDC. Only present if payment was created with a fiat currency.

Example:

"100.00"

​
fiatCurrency
string

The original fiat currency code (e.g., USD, EUR, SGD). Only present if payment was created with a fiat currency.

Example:

"USD"

​
transactionHash
string

The blockchain transaction hash for the completed payment. Only present when status is COMPLETED, REFUNDED, or PARTIALLY_REFUNDED.

Example:

"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"

​
refundedAmount
string

The total amount that has been refunded. Only present when a refund has been initiated.

Example:

"25.00"

​
refunds
object[]

List of refunds associated with this payment. Only present when refunds exist.