API Reference

Payment Links

A Payment Link is a shareable, reusable page for accepting payments. You can send the link to your customers, and they can use it to purchase products, subscribe to services, or make donations without you needing to build a custom payment interface. Each Payment Link object provides a unique URL that directs users to a secure, hosted payment page.
This is useful for scenarios like selling a single product, setting up a subscription, or collecting donations with minimal integration effort.
The Payment Link Object#A Payment Link object contains all the details needed to present a payment page, including line items, currency, and behavior after payment completion.
{
  "id": "plink_xxxxxxxxxxxxxx",
  "active": true,
  "name": "Premium Subscription",
  "line_items": [
    {
      "price_id": "price_yyyyyyyyyyyyyy",
      "quantity": 1,
      "adjustable_quantity": {
        "enabled": false
      },
      "price": {
        "id": "price_yyyyyyyyyyyyyy",
        "product_id": "prod_zzzzzzzzzzzzzz",
        "active": true,
        "type": "recurring",
        "unit_amount": "29.99",
        "currency_id": "usd_12345",
        "recurring": {
          "interval": "month",
          "interval_count": 1
        },
        "product": {
          "id": "prod_zzzzzzzzzzzzzz",
          "name": "Premium Tier"
        }
      }
    }
  ],
  "currency_id": "usd_12345",
  "after_completion": {
    "type": "hosted_confirmation",
    "hosted_confirmation": {
      "custom_message": "Thank you for subscribing!"
    }
  },
  "allow_promotion_codes": true,
  "customer_creation": "always",
  "submit_type": "pay",
  "url": "https://example.com/pay/plink_xxxxxxxxxxxxxx",
  "livemode": false,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "metadata": {}
}
Create a Payment Link#Creates a new Payment Link object.
payment.paymentLinks.create(params)Parameters
Name
Type
Description
line_items
array
Required. A list of line item objects, each representing a product or price. See details below.
name
string
Optional. The internal name for the payment link. Max 255 characters.
lookup_key
string
Optional. A unique string to identify the payment link, which can be used to retrieve it later. Max 128 characters.
currency_id
string
Optional. The ID of the currency for the payment. If not provided, the default currency is used.
after_completion
object
Optional. Defines the behavior after a successful payment. See details below.
allow_promotion_codes
boolean
Optional. Toggles whether promotion codes can be used with this link. Defaults to false.
enable_subscription_grouping
boolean
Optional. Toggles subscription grouping. Only supported for stake-free subscriptions. Defaults to false.
nft_mint_settings
object
Optional. Configuration for NFT minting after payment. See details below.
consent_collection
object
Optional. Manages the collection of customer consent for promotions and terms of service. See details below.
metadata
object
Optional. A set of key-value pairs that you can attach to the object.
line_items Object Properties
Name
Type
Description
price_id
string
Required. The ID of the Price object.
quantity
number
Required. The quantity of the price to be purchased. Must be at least 1.
adjustable_quantity
object
Optional. Configuration to allow customers to change the quantity on the payment page. See details below.
adjustable_quantity Object Properties
Name
Type
Description
enabled
boolean
Required. If true, the customer can adjust the quantity.
minimum
number
Optional. The minimum quantity the customer can select. Must be less than maximum.
maximum
number
Optional. The maximum quantity the customer can select.
after_completion Object Properties
Name
Type
Description
type
string
Required. The type of action to perform. Can be hosted_confirmation or redirect.
hosted_confirmation
object
Optional. Displays a confirmation message on a hosted page. Used when type is hosted_confirmation.
redirect
object
Optional. Redirects the customer to a specific URL. Used when type is redirect.
hosted_confirmation Object Properties
Name
Type
Description
custom_message
string
Optional. A custom message to display to the customer. Max 200 characters.
redirect Object Properties
Name
Type
Description
url
string
Required. The URL to redirect the customer to. Max 2048 characters.
nft_mint_settings Object Properties
Name
Type
Description
enabled
boolean
Required. Set to true to enable NFT minting upon successful payment.
factory
string
Optional. The factory address required for minting. Required if enabled is true. Max 40 characters.
consent_collection Object Properties
Name
Type
Description
promotions
string
Required. Determines how promotional consent is collected. Can be none, opt_in, or opt_out.
terms_of_service
string
Required. Determines how terms of service consent is collected. Can be none, opt_in, or opt_out.
Returns
Returns the created TPaymentLink object.
Example Request
const paymentLink = await payment.paymentLinks.create({
  name: 'Monthly Pro Plan',
  line_items: [
    {
      price_id: 'price_yyyyyyyyyyyyyy',
      quantity: 1,
    },
  ],
  after_completion: {
    type: 'hosted_confirmation',
    hosted_confirmation: {
      custom_message: 'Thanks for your subscription!',
    },
  },
  allow_promotion_codes: true,
});

console.log(paymentLink);Example Response
{
  "id": "plink_xxxxxxxxxxxxxx",
  "active": true,
  "name": "Monthly Pro Plan",
  "line_items": [
    {
      "price_id": "price_yyyyyyyyyyyyyy",
      "quantity": 1
    }
  ],
  "after_completion": {
    "type": "hosted_confirmation",
    "hosted_confirmation": {
      "custom_message": "Thanks for your subscription!"
    }
  },
  "allow_promotion_codes": true,
  "url": "https://example.com/pay/plink_xxxxxxxxxxxxxx",
  "livemode": false
}
Retrieve a Payment Link#Retrieves the details of an existing Payment Link by its ID or lookup_key.
payment.paymentLinks.retrieve(id)Parameters
Name
Type
Description
id
string
Required. The unique identifier (plink_...) or lookup_key of the Payment Link to retrieve.
Returns
Returns the TPaymentLinkExpanded object if found, otherwise returns a 404 error.
Example Request
const paymentLinkId = 'plink_xxxxxxxxxxxxxx';
const paymentLink = await payment.paymentLinks.retrieve(paymentLinkId);

console.log(paymentLink);Example Response
{
  "id": "plink_xxxxxxxxxxxxxx",
  "active": true,
  "name": "Monthly Pro Plan",
  "line_items": [
    {
      "price_id": "price_yyyyyyyyyyyyyy",
      "quantity": 1,
      "price": { 
        "id": "price_yyyyyyyyyyyyyy", 
        "product_id": "prod_zzzzzzzzzzzzzz",
        "type": "recurring", 
        "unit_amount": "12.00"
      }
    }
  ],
  "url": "https://example.com/pay/plink_xxxxxxxxxxxxxx",
  "livemode": false
}
Update a Payment Link#Updates an existing Payment Link. Only active payment links can be updated.
payment.paymentLinks.update(id, params)Parameters
Name
Type
Description
id
string
Required. The ID of the Payment Link to update.
name
string
Optional. The updated name for the payment link.
active
boolean
Optional. Whether the link is active. Use the archive method to deactivate a link, as updating an archived link is not permitted.
line_items
array
Optional. An updated list of line items.
after_completion
object
Optional. Updated behavior after a successful payment.
allow_promotion_codes
boolean
Optional. Toggles whether promotion codes can be used.
metadata
object
Optional. A new set of key-value pairs. This will replace the existing metadata, not merge with it.
Returns
Returns the updated TPaymentLink object.
Example Request
const paymentLinkId = 'plink_xxxxxxxxxxxxxx';
const updatedLink = await payment.paymentLinks.update(paymentLinkId, {
  name: 'Updated Monthly Pro Plan',
  metadata: { order_id: '6735' },
});

console.log(updatedLink);Example Response
{
  "id": "plink_xxxxxxxxxxxxxx",
  "active": true,
  "name": "Updated Monthly Pro Plan",
  "metadata": { "order_id": "6735" },
  "url": "https://example.com/pay/plink_xxxxxxxxxxxxxx"
}
List Payment Links#Returns a paginated list of your Payment Links.
payment.paymentLinks.list(params)Parameters
Name
Type
Description
active
boolean
Optional. Filters the list to return only active or inactive payment links.
donation
string
Optional. Set to 'hide' to exclude payment links where submit_type is donate.
livemode
boolean
Optional. Filters by live or test mode.
page
number
Optional. The page number for pagination. Defaults to 1.
pageSize
number
Optional. The number of items per page. Defaults to 20.
order
string[]
Optional. An array defining the sort order, e.g., ['created_at', 'DESC'].
Returns
Returns a paginated object containing a list of TPaymentLinkExpanded objects, the total count, and paging information.
Example Request
const paymentLinks = await payment.paymentLinks.list({
  active: true,
  pageSize: 5,
});

console.log(`Found ${paymentLinks.count} active payment links.`);
console.log(paymentLinks.list);Example Response
{
  "count": 50,
  "list": [
    {
      "id": "plink_xxxxxxxxxxxxxx",
      "active": true,
      "name": "Monthly Pro Plan"
    },
    {
      "id": "plink_zzzzzzzzzzzzzz",
      "active": true,
      "name": "Annual Premium Plan"
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}
Archive a Payment Link#Deactivates a Payment Link, making it unusable for new payments. This action cannot be undone, and archived links cannot be updated.
payment.paymentLinks.archive(id)Parameters
Name
Type
Description
id
string
Required. The ID of the Payment Link to archive.
Returns
Returns the TPaymentLink object with its active status set to false.
Example Request
const paymentLinkId = 'plink_xxxxxxxxxxxxxx';
const archivedLink = await payment.paymentLinks.archive(paymentLinkId);

console.log(`Archived: ${archivedLink.id}, Active: ${archivedLink.active}`);Example Response
{
  "id": "plink_xxxxxxxxxxxxxx",
  "active": false,
  "name": "Monthly Pro Plan"
}This marks the payment link as inactive, preventing any new payments.

Name	Type	Description
`line_items`	`array`	Required. A list of line item objects, each representing a product or price. See details below.
`name`	`string`	Optional. The internal name for the payment link. Max 255 characters.
`lookup_key`	`string`	Optional. A unique string to identify the payment link, which can be used to retrieve it later. Max 128 characters.
`currency_id`	`string`	Optional. The ID of the currency for the payment. If not provided, the default currency is used.
`after_completion`	`object`	Optional. Defines the behavior after a successful payment. See details below.
`allow_promotion_codes`	`boolean`	Optional. Toggles whether promotion codes can be used with this link. Defaults to `false`.
`enable_subscription_grouping`	`boolean`	Optional. Toggles subscription grouping. Only supported for stake-free subscriptions. Defaults to `false`.
`nft_mint_settings`	`object`	Optional. Configuration for NFT minting after payment. See details below.
`consent_collection`	`object`	Optional. Manages the collection of customer consent for promotions and terms of service. See details below.
`metadata`	`object`	Optional. A set of key-value pairs that you can attach to the object.

Name	Type	Description
`price_id`	`string`	Required. The ID of the `Price` object.
`quantity`	`number`	Required. The quantity of the price to be purchased. Must be at least 1.
`adjustable_quantity`	`object`	Optional. Configuration to allow customers to change the quantity on the payment page. See details below.

Name	Type	Description
`enabled`	`boolean`	Required. If `true`, the customer can adjust the quantity.
`minimum`	`number`	Optional. The minimum quantity the customer can select. Must be less than `maximum`.
`maximum`	`number`	Optional. The maximum quantity the customer can select.

Name	Type	Description
`type`	`string`	Required. The type of action to perform. Can be `hosted_confirmation` or `redirect`.
`hosted_confirmation`	`object`	Optional. Displays a confirmation message on a hosted page. Used when `type` is `hosted_confirmation`.
`redirect`	`object`	Optional. Redirects the customer to a specific URL. Used when `type` is `redirect`.

Name	Type	Description
`enabled`	`boolean`	Required. Set to `true` to enable NFT minting upon successful payment.
`factory`	`string`	Optional. The factory address required for minting. Required if `enabled` is `true`. Max 40 characters.

Overview

Getting Started

SDK Structure

Environments

Core Concepts

API Reference

Payment Links

The Payment Link Object#

Create a Payment Link#

Retrieve a Payment Link#

Update a Payment Link#

List Payment Links#

Archive a Payment Link#

Payment Methods

Payment Currencies

Name	Type	Description
`promotions`	`string`	Required. Determines how promotional consent is collected. Can be `none`, `opt_in`, or `opt_out`.
`terms_of_service`	`string`	Required. Determines how terms of service consent is collected. Can be `none`, `opt_in`, or `opt_out`.

Name	Type	Description
`id`	`string`	Required. The ID of the Payment Link to update.
`name`	`string`	Optional. The updated name for the payment link.
`active`	`boolean`	Optional. Whether the link is active. Use the `archive` method to deactivate a link, as updating an archived link is not permitted.
`line_items`	`array`	Optional. An updated list of line items.
`after_completion`	`object`	Optional. Updated behavior after a successful payment.
`allow_promotion_codes`	`boolean`	Optional. Toggles whether promotion codes can be used.
`metadata`	`object`	Optional. A new set of key-value pairs. This will replace the existing metadata, not merge with it.

Name	Type	Description
`active`	`boolean`	Optional. Filters the list to return only active or inactive payment links.
`donation`	`string`	Optional. Set to `'hide'` to exclude payment links where `submit_type` is `donate`.
`livemode`	`boolean`	Optional. Filters by live or test mode.
`page`	`number`	Optional. The page number for pagination. Defaults to `1`.
`pageSize`	`number`	Optional. The number of items per page. Defaults to `20`.
`order`	`string[]`	Optional. An array defining the sort order, e.g., `['created_at', 'DESC']`.