Payment Links

A Payment Link is a shareable, reusable page to sell a product or service. You can create a link for a specific set of products and prices and share it with multiple customers through various channels. This allows for quick and easy payment collection without building a full checkout flow.

The Payment Link Object#

A Payment Link object contains all the information necessary to present a payment page to a customer. Here are some of its key attributes:

Attribute	Type	Description
id	string	Unique identifier for the payment link object.
url	string	The URL for the payment page. Customers can be redirected to this URL to make a payment.
active	boolean	Whether the payment link is currently active and can be used for payments.
line_items	array	The list of products and prices that will be purchased.
after_completion	object	Behavior after the purchase is complete, such as redirecting to a URL or showing a confirmation message.
allow_promotion_codes	boolean	Enables the use of promotion codes on the payment page.
currency_id	string	The three-letter ISO currency code.
metadata	object	A set of key-value pairs that you can attach to the object. Useful for storing additional information.
created_at	string	Timestamp of when the object was created.

Create a Payment Link#

Creates a new payment link.

const paymentLink = await payment.paymentLinks.create({
  line_items: [
    {
      price_id: 'price_xxxxxxxxxxxxxx',
      quantity: 1,
      adjustable_quantity: {
        enabled: true,
        minimum: 1,
        maximum: 10,
      },
    },
  ],
  after_completion: {
    type: 'hosted_confirmation',
    hosted_confirmation: {
      custom_message: 'Thanks for your purchase!',
    },
  },
  metadata: {
    order_id: '6735',
  },
});

Parameters#

Name	Type	Description
line_items	array	Required. A list of line item objects, each representing a product to be purchased. See details below.
name	string	An optional internal name for the payment link.
lookup_key	string	An optional, unique string that can be used to retrieve the payment link.
currency_id	string	The ID of the currency for this payment link. If not provided, the default currency is used.
after_completion	object	Specifies the behavior after a successful payment. See details below.
allow_promotion_codes	boolean	Set to true to allow promotion codes to be redeemed. Defaults to false.
consent_collection	object	Configures consent collection for promotions and terms of service. See details below.
nft_mint_settings	object	Settings for minting an NFT after the payment is complete. See details below.
metadata	object	A set of key-value pairs to store additional information.

line_items Object Properties

Name	Type	Description
price_id	string	Required. The ID of the price object.
quantity	number	Required. The quantity of the product being purchased. Must be at least 1.
adjustable_quantity	object	Configuration that allows the customer to adjust the quantity of this line item on the payment page. See details below.

line_items.adjustable_quantity Object Properties

Name	Type	Description
enabled	boolean	Required. Set to true to allow quantity adjustments.
minimum	number	The minimum quantity the customer can select. Must be 0 or greater.
maximum	number	The maximum quantity the customer can select. Must be greater than minimum.

after_completion Object Properties

Name	Type	Description
type	string	Required. The type of completion behavior. Can be hosted_confirmation or redirect.
hosted_confirmation	object	Displays a hosted confirmation message to the customer. Used when type is hosted_confirmation.
redirect	object	Redirects the customer to a specific URL. Used when type is redirect.

after_completion.hosted_confirmation Object Properties

Name	Type	Description
custom_message	string	An optional custom message to display to the customer. Max 200 characters.

after_completion.redirect Object Properties

Name	Type	Description
url	string	The URL to redirect the customer to. Max 2048 characters.

consent_collection Object Properties

Name	Type	Description
promotions	string	Determines how to handle consent for promotional communications. Can be none, opt_in, or opt_out.
terms_of_service	string	Determines how to handle consent for terms of service. Can be none, opt_in, or opt_out.

nft_mint_settings Object Properties

Name	Type	Description
enabled	boolean	Required. Set to true to enable NFT minting after payment.
factory	string	The factory address for minting the NFT. Required if enabled is true.

Returns#

Returns a TPaymentLinkExpanded object if the creation is successful.

{
  "id": "plink_xxxxxxxxxxxxxx",
  "active": true,
  "url": "https://payment.arcblock.io/pl/plink_xxxxxxxxxxxxxx",
  "line_items": [
    {
      "price_id": "price_xxxxxxxxxxxxxx",
      "quantity": 1,
      "adjustable_quantity": {
        "enabled": true,
        "minimum": 1,
        "maximum": 10
      }
    }
  ],
  "after_completion": {
    "type": "hosted_confirmation",
    "hosted_confirmation": {
      "custom_message": "Thanks for your purchase!"
    }
  },
  "metadata": {
    "order_id": "6735"
  }
}

Retrieve a Payment Link#

Retrieves the details of an existing payment link.

const paymentLinkId = 'plink_xxxxxxxxxxxxxx';
const paymentLink = await payment.paymentLinks.retrieve(paymentLinkId);

Parameters#

Name	Type	Description
id	string	Required. The unique identifier or lookup_key of the payment link to retrieve.

Returns#

Returns a TPaymentLinkExpanded object, which includes expanded details about the line items and their associated prices and products.

{
  "id": "plink_xxxxxxxxxxxxxx",
  "active": true,
  "url": "https://payment.arcblock.io/pl/plink_xxxxxxxxxxxxxx",
  "line_items": [
    {
      "price_id": "price_xxxxxxxxxxxxxx",
      "quantity": 1,
      "price": {
        "id": "price_xxxxxxxxxxxxxx",
        "product_id": "prod_yyyyyyyyyyyyyy",
        "unit_amount": "10.00",
        "product": {
          "id": "prod_yyyyyyyyyyyyyy",
          "name": "My Awesome Product"
        }
      }
    }
  ]
}

Update a Payment Link#

Updates a payment link by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Note that you cannot update an archived payment link.

const paymentLinkId = 'plink_xxxxxxxxxxxxxx';
const updatedPaymentLink = await payment.paymentLinks.update(paymentLinkId, {
  active: false,
  metadata: {
    order_id: '6735-updated'
  }
});

Parameters#

Name	Type	Description
id	string	Required. The ID of the payment link to update.
...		The second argument is an object containing the fields to update. It supports many of the same parameters as the create method, such as active, line_items, metadata, and after_completion. All fields are optional.

Returns#

Returns the updated TPaymentLink object.

{
  "id": "plink_xxxxxxxxxxxxxx",
  "active": false,
  "metadata": {
    "order_id": "6735-updated"
  }
}

List all Payment Links#

Returns a list of your payment links.

const paymentLinks = await payment.paymentLinks.list({
  active: true,
  limit: 5
});

Parameters#

Name	Type	Description
active	boolean	Filters the list to only include active or inactive payment links.
donation	string	Set to 'hide' to exclude payment links where submit_type is donate.
page	number	The page number for pagination. Defaults to 1.
pageSize	number	The number of objects to return per page. Defaults to 20.
order	string	The order to sort the results by. For example, 'created_at:DESC'.

Returns#

Returns a paginated object containing a list of TPaymentLinkExpanded objects.

{
  "count": 15,
  "list": [
    {
      "id": "plink_xxxxxxxxxxxxxx",
      "active": true
    },
    {
      "id": "plink_yyyyyyyyyyyyyy",
      "active": true
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}

Archive a Payment Link#

Deactivates a payment link, making it unusable for payments. This action is reversible by updating the active attribute to true.

const paymentLinkId = 'plink_xxxxxxxxxxxxxx';
const archivedPaymentLink = await payment.paymentLinks.archive(paymentLinkId);

Parameters#

Name	Type	Description
id	string	Required. The ID of the payment link to archive.

Returns#

Returns the archived TPaymentLink object with its active property set to false.

{
  "id": "plink_xxxxxxxxxxxxxx",
  "active": false,
  "url": "https://payment.arcblock.io/pl/plink_xxxxxxxxxxxxxx"
}